@backburner/cli 0.1.0

package/dist/src/tasks/derivation/handlers/retry-failed-task.js

@@ -0,0 +1,125 @@
+import { createEntityId } from "../../../github/normalize.js";
+import { extractRetryCommentId } from "../../retry.js";
+export const retryFailedTaskHandler = {
+    name: "retry_failed_task",
+    derive(context, env, sink) {
+        for (const task of deriveRetryTasks(context, env, sink)) {
+            sink.replace(task);
+        }
+        return [];
+    }
+};
+const RETRY_REASON_SUFFIX = "Retry requested by a human comment after a technical failure.";
+function deriveRetryTasks(context, env, sink) {
+    const legacyRetryTargetCommentId = getLegacyRetryTargetCommentId(context, env);
+    if (!context.attention?.reasons.includes("retry_requested") && !legacyRetryTargetCommentId) {
+        return [];
+    }
+    const retryRequests = collectRetryRequests(context, env, legacyRetryTargetCommentId);
+    if (retryRequests.length === 0) {
+        return [];
+    }
+    const requeuedTasks = new Map();
+    for (const request of retryRequests) {
+        for (const failedTask of findMatchingFailedTasks(request, context, env)) {
+            // prepare_pr_for_merge retry depends on normal derivation having already built
+            // the current-cycle task; keep retryFailedTaskHandler after parent handlers.
+            const currentDesiredTask = sink.get(failedTask.id);
+            if (failedTask.kind === "prepare_pr_for_merge" && !currentDesiredTask) {
+                continue;
+            }
+            const baseTask = currentDesiredTask ?? failedTask;
+            requeuedTasks.set(failedTask.id, {
+                ...baseTask,
+                status: "pending",
+                context: {
+                    ...baseTask.context,
+                    recoveryNeeded: true
+                },
+                reason: appendRetryReason(baseTask.reason),
+                ...(failedTask.lastExecutionId ? { lastExecutionId: failedTask.lastExecutionId } : {}),
+                ...(failedTask.lastFailureCommentId ? { lastFailureCommentId: failedTask.lastFailureCommentId } : {}),
+                updatedAt: env.input.now
+            });
+        }
+    }
+    return [...requeuedTasks.values()];
+}
+function collectRetryRequests(context, env, legacyRetryTargetCommentId) {
+    const requests = new Map();
+    for (const commentId of context.attention?.commentIds ?? []) {
+        const comment = env.currentCommentsById.get(commentId);
+        const targetFailureCommentId = comment ? extractRetryCommentId(comment.body) : undefined;
+        if (!targetFailureCommentId || requests.has(targetFailureCommentId)) {
+            continue;
+        }
+        requests.set(targetFailureCommentId, {
+            targetFailureCommentId
+        });
+    }
+    if (requests.size === 0 && legacyRetryTargetCommentId) {
+        requests.set(legacyRetryTargetCommentId, {
+            targetFailureCommentId: legacyRetryTargetCommentId
+        });
+    }
+    return [...requests.values()];
+}
+function findMatchingFailedTasks(request, context, env) {
+    const candidates = env.existingTasks.filter((task) => task.status === "failed" &&
+        task.lastFailureCommentId === request.targetFailureCommentId &&
+        taskMatchesRepo(task, context));
+    const modernMatches = candidates.filter((task) => task.workstreamId === context.workstream.id);
+    if (modernMatches.length > 1) {
+        console.warn(`[retry_failed_task] Multiple modern tasks matched failure comment ${request.targetFailureCommentId} for workstream ${context.workstream.id}; retrying all: ${modernMatches.map((task) => task.id).join(", ")}`);
+    }
+    if (modernMatches.length > 0) {
+        return modernMatches;
+    }
+    const legacySourceIds = buildLegacyWorkstreamSourceIds(context);
+    const legacyMatches = candidates.filter((task) => task.workstreamId === undefined && legacyTaskMatchesCurrentWorkstreamSource(task, legacySourceIds));
+    if (legacyMatches.length > 1) {
+        console.warn(`[retry_failed_task] Ignoring ambiguous legacy retry target ${request.targetFailureCommentId} for workstream ${context.workstream.id}; matched tasks: ${legacyMatches.map((task) => task.id).join(", ")}`);
+        return [];
+    }
+    return legacyMatches.length === 1 ? legacyMatches : [];
+}
+function appendRetryReason(reason) {
+    const suffix = ` ${RETRY_REASON_SUFFIX}`;
+    let baseReason = reason;
+    while (baseReason.endsWith(suffix)) {
+        baseReason = baseReason.slice(0, -suffix.length);
+    }
+    return `${baseReason}${suffix}`;
+}
+function getLegacyRetryTargetCommentId(context, env) {
+    return env.input.previousState.attention.find((record) => record.workstreamId === context.workstream.id)?.retryTargetCommentId;
+}
+function taskMatchesRepo(task, context) {
+    if (task.repoSlug === context.workstream.repoKey) {
+        return true;
+    }
+    return Boolean(context.repoConfig && task.repoId === context.repoConfig.id);
+}
+function legacyTaskMatchesCurrentWorkstreamSource(task, sourceIds) {
+    return (sourceIds.has(task.sourceId) ||
+        (task.parentSourceId !== undefined && sourceIds.has(task.parentSourceId)));
+}
+function buildLegacyWorkstreamSourceIds(context) {
+    const sourceIds = new Set();
+    if (context.issue) {
+        sourceIds.add(context.issue.id);
+    }
+    if (context.activePullRequest) {
+        sourceIds.add(context.activePullRequest.id);
+    }
+    for (const prNumber of context.attention?.pullRequestNumbers ?? []) {
+        sourceIds.add(createEntityId("pull_request", context.workstream.repoKey, prNumber));
+    }
+    if (context.workstream.origin.type === "pr") {
+        sourceIds.add(createEntityId("pull_request", context.workstream.repoKey, context.workstream.origin.number));
+    }
+    if (context.workstream.origin.type === "issue") {
+        sourceIds.add(createEntityId("issue", context.workstream.repoKey, context.workstream.origin.number));
+    }
+    return sourceIds;
+}

package/dist/src/tasks/derivation/handlers/review-pr.js

@@ -0,0 +1,28 @@
+import { createPullRequestTask } from "../builders.js";
+export const reviewPullRequestHandler = {
+    name: "review_pr",
+    derive(context, env) {
+        const task = deriveReviewTask(context, env);
+        return task ? [task] : [];
+    }
+};
+function deriveReviewTask(context, env) {
+    const { workstream, attention, activePullRequest, activeWorktree, repoConfig, repoSyncRecord } = context;
+    if (!attention || !activePullRequest || !repoConfig) {
+        return undefined;
+    }
+    const reviewRequested = attention.reasons.includes("pr_review_requested");
+    const reviewNeedsAction = reviewRequested &&
+        (!attention.lastHandledReviewHeadSha ||
+            attention.lastHandledReviewHeadSha !== attention.currentPullRequestHeadSha);
+    const isReviewWorkstream = workstream.origin.type === "pr" || workstream.phase === "pr_review";
+    if (!reviewNeedsAction || !isReviewWorkstream) {
+        return undefined;
+    }
+    return createPullRequestTask("review_pr", activePullRequest, repoSyncRecord, {
+        reason: `Pull request has the "${repoConfig.labels.agentReview}" label and code changed (head: ${activePullRequest.headSha || "unknown"}).`,
+        summary: `Review PR #${activePullRequest.number}: ${activePullRequest.title}`,
+        contextBuilder: env.input.contextBuilder,
+        now: env.input.now
+    }, activeWorktree, workstream.id);
+}

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

@@ -0,0 +1,24 @@
+export function isActiveParentWorkstream(workstream) {
+    return (workstream.status === "open" &&
+        workstream.phase !== "abandoned" &&
+        workstream.phase !== "resolved");
+}
+export function resolvePacketPullRequest(worktree, currentPrsByRepoAndNumber) {
+    if (worktree.prNumber !== undefined) {
+        const pr = currentPrsByRepoAndNumber.get(`${worktree.repoSlug}:${worktree.prNumber}`);
+        if (pr) {
+            return pr;
+        }
+    }
+    if (worktree.prUrl) {
+        const match = worktree.prUrl.match(/\/pull\/(\d+)$/);
+        if (match) {
+            const prNumber = Number(match[1]);
+            const pr = currentPrsByRepoAndNumber.get(`${worktree.repoSlug}:${prNumber}`);
+            if (pr) {
+                return pr;
+            }
+        }
+    }
+    return undefined;
+}

package/dist/src/tasks/derivation/handlers/sync-parent-branch.js

@@ -0,0 +1,100 @@
+import { buildParentBranchSyncPreflight } from "../../../workstreams/packet-plan.js";
+import { buildTaskRecord } from "../builders.js";
+export const syncParentBranchPreflightHandler = {
+    name: "sync_parent_branch_preflight",
+    derive(context, env) {
+        const task = deriveSyncParentBranchPreflightTask(context, env);
+        return task ? [task] : [];
+    }
+};
+export const syncParentBranchHandler = {
+    name: "sync_parent_branch",
+    derive(context, env) {
+        const task = deriveSyncParentBranchTask(context, env);
+        return task ? [task] : [];
+    }
+};
+function deriveSyncParentBranchPreflightTask(context, env) {
+    const { workstream, attention, issue, repoConfig, repoSyncRecord } = context;
+    if (workstream.origin.type !== "issue" ||
+        !issue ||
+        !attention?.reasons.includes("packet_wave_complete_sync_needed") ||
+        !workstream.packetPlan) {
+        return undefined;
+    }
+    const defaultBranch = repoConfig?.defaultBranch ?? repoSyncRecord?.defaultBranch ?? undefined;
+    const preflight = buildParentBranchSyncPreflight({ workstream, defaultBranch });
+    if (!preflight) {
+        return undefined;
+    }
+    const reason = [
+        `Current packet wave ${preflight.currentWaveIndex} is complete and a future wave exists.`,
+        `Parent integration branch: ${preflight.parentIntegrationBranch}`,
+        `Default branch: ${preflight.defaultBranch}`,
+        `Next wave index: ${preflight.nextWaveIndex}`,
+        `Completed packet IDs: ${preflight.completedPacketIds.join(", ")}`,
+        `Pending future packet IDs: ${preflight.pendingFuturePacketIds.join(", ")}`,
+        preflight.parentPrNumber ? `Parent PR: #${preflight.parentPrNumber}` : undefined
+    ]
+        .filter(Boolean)
+        .join(" ");
+    return buildTaskRecord(`task:sync_parent_branch_preflight:${workstream.id}`, "sync_parent_branch_preflight", issue, repoSyncRecord, {
+        reason,
+        summary: `Inspect parent branch sync before packet wave ${preflight.nextWaveIndex} for issue #${issue.number}`,
+        contextBuilder: env.input.contextBuilder,
+        now: env.input.now
+    }, env.input.contextBuilder.build({
+        taskKind: "sync_parent_branch_preflight",
+        repoIdentifier: issue.repoSlug,
+        sourceKind: "issue",
+        sourceUrl: issue.url,
+        labels: issue.labels,
+        issueTitle: issue.title,
+        issueBody: issue.body,
+        preflight,
+        ...(repoSyncRecord?.localPath ? { localRepoPath: repoSyncRecord.localPath } : {})
+    }), workstream.id);
+}
+function deriveSyncParentBranchTask(context, env) {
+    const { workstream, attention, issue, repoConfig, repoSyncRecord } = context;
+    if (workstream.origin.type !== "issue" ||
+        !issue ||
+        issue.state !== "open" ||
+        !attention?.reasons.includes("packet_wave_complete_sync_needed") ||
+        !workstream.packetPlan ||
+        !repoConfig) {
+        return undefined;
+    }
+    const defaultBranch = repoConfig.defaultBranch ?? repoSyncRecord?.defaultBranch ?? undefined;
+    const preflight = buildParentBranchSyncPreflight({ workstream, defaultBranch });
+    if (!preflight || !preflight.parentPrNumber) {
+        return undefined;
+    }
+    const parentPr = env.currentPrsByRepoAndNumber.get(`${workstream.repoKey}:${preflight.parentPrNumber}`);
+    if (!parentPr || parentPr.state !== "open" || !parentPr.labels.includes(repoConfig.labels.agentSyncParentBranch)) {
+        return undefined;
+    }
+    const reason = [
+        `Explicit sync requested via label "${repoConfig.labels.agentSyncParentBranch}" on parent PR #${parentPr.number}.`,
+        `Current packet wave ${preflight.currentWaveIndex} is complete and a future wave exists.`,
+        `Parent integration branch: ${preflight.parentIntegrationBranch}`,
+        `Default branch: ${preflight.defaultBranch}`,
+        `Next wave index: ${preflight.nextWaveIndex}`,
+        `Completed packet IDs: ${preflight.completedPacketIds.join(", ")}`,
+        `Pending future packet IDs: ${preflight.pendingFuturePacketIds.join(", ")}`
+    ].join(" ");
+    return buildTaskRecord(`task:sync_parent_branch:${parentPr.id}`, "sync_parent_branch", parentPr, repoSyncRecord, {
+        reason,
+        summary: `Sync parent branch for issue #${issue.number} before packet wave ${preflight.nextWaveIndex}`,
+        contextBuilder: env.input.contextBuilder,
+        now: env.input.now
+    }, env.input.contextBuilder.build({
+        taskKind: "sync_parent_branch",
+        repoIdentifier: parentPr.repoSlug,
+        sourceKind: "pull_request",
+        sourceUrl: parentPr.url,
+        labels: parentPr.labels,
+        preflight,
+        ...(repoSyncRecord?.localPath ? { localRepoPath: repoSyncRecord.localPath } : {})
+    }), workstream.id);
+}

package/dist/src/tasks/derivation/handlers/wave-assessment.js

@@ -0,0 +1,223 @@
+import { buildParentBranchSyncPreflight } from "../../../workstreams/packet-plan.js";
+import { buildWaveAssessmentCheckpoint, buildWaveAssessmentCheckpointIdentity } from "../../../workstreams/wave-assessment/checkpoint.js";
+import { buildTaskRecord } from "../builders.js";
+export const waveAssessmentHandler = {
+    name: "wave_assessment",
+    derive(context, env) {
+        const assessmentTask = deriveWavePlanAssessmentTask(context, env);
+        if (assessmentTask) {
+            return [assessmentTask];
+        }
+        const replanningTask = deriveWavePlanReplanningTask(context, env);
+        return replanningTask ? [replanningTask] : [];
+    }
+};
+export function isWaveAssessmentCheckpointAllowed(context, env) {
+    const checkpoint = resolveWaveAssessmentCheckpoint(context, env);
+    if (!checkpoint) {
+        return false;
+    }
+    const assessment = findMatchingPublishedFinalizedWaveAssessment(context.workstream, env, checkpoint.identity);
+    return assessment?.decision === "continue";
+}
+export function hasOpenWaveAssessmentParentPullRequest(context, env) {
+    const checkpoint = resolveWaveAssessmentCheckpoint(context, env);
+    if (!checkpoint) {
+        return false;
+    }
+    const parentPrNumber = context.workstream.integration?.prNumber;
+    const parentPr = parentPrNumber !== undefined
+        ? env.currentPrsByRepoAndNumber.get(`${context.workstream.repoKey}:${parentPrNumber}`)
+        : undefined;
+    return parentPr?.state === "open";
+}
+function deriveWavePlanAssessmentTask(context, env) {
+    const resolved = resolveWaveAssessmentTaskContext(context, env);
+    if (!resolved) {
+        return undefined;
+    }
+    const { checkpoint, issue, parentPr, repoSyncRecord, workstream } = resolved;
+    if (findMatchingPublishedFinalizedWaveAssessment(workstream, env, checkpoint.identity)) {
+        return undefined;
+    }
+    const unpublishedAssessment = findMatchingFinalizedWaveAssessment(workstream, env, checkpoint.identity, { requirePostedComment: false });
+    const taskId = buildWaveAssessmentTaskId(checkpoint);
+    if (hasUnresolvedTask(env, taskId)) {
+        return undefined;
+    }
+    return buildTaskRecord(taskId, "wave_plan_assessment", parentPr, repoSyncRecord, {
+        reason: [
+            `Current packet wave ${checkpoint.identity.currentWaveIndex} is complete and future packets remain.`,
+            `Parent PR #${parentPr.number} is open.`,
+            unpublishedAssessment && !unpublishedAssessment.postedCommentId
+                ? "A finalized wave assessment exists, but its parent PR comment was not posted; rerun the assessment publication path."
+                : "No finalized wave assessment exists for this checkpoint."
+        ].join(" "),
+        summary: `Assess completed packet wave ${checkpoint.identity.currentWaveIndex} before wave ${checkpoint.identity.nextWaveIndex}`,
+        contextBuilder: env.input.contextBuilder,
+        now: env.input.now
+    }, env.input.contextBuilder.build({
+        taskKind: "wave_plan_assessment",
+        repoIdentifier: parentPr.repoSlug,
+        sourceKind: "pull_request",
+        sourceUrl: parentPr.url,
+        parentUrl: issue.url,
+        labels: parentPr.labels,
+        issueTitle: issue.title,
+        issueBody: issue.body,
+        waveAssessmentCheckpoint: checkpoint,
+        ...(repoSyncRecord?.localPath ? { localRepoPath: repoSyncRecord.localPath } : {})
+    }), workstream.id);
+}
+function deriveWavePlanReplanningTask(context, env) {
+    const resolved = resolveWaveAssessmentTaskContext(context, env);
+    if (!resolved) {
+        return undefined;
+    }
+    const { checkpoint, issue, parentPr, repoSyncRecord, workstream } = resolved;
+    const assessment = findMatchingPublishedFinalizedWaveAssessment(workstream, env, checkpoint.identity);
+    if (!assessment || assessment.decision !== "replan") {
+        return undefined;
+    }
+    if (findMatchingPublishedFinalizedWaveAssessment(workstream, env, checkpoint.identity, { decision: "continue" })) {
+        return undefined;
+    }
+    const taskId = buildWaveReplanningTaskId(checkpoint);
+    const existing = env.existingTasksById.get(taskId);
+    if (hasUnresolvedTask(env, taskId)) {
+        return undefined;
+    }
+    return buildTaskRecord(taskId, "wave_plan_replanning", parentPr, repoSyncRecord, {
+        reason: [
+            `Finalized wave assessment ${assessment.id} requires replanning.`,
+            `Current packet wave ${checkpoint.identity.currentWaveIndex} is complete before wave ${checkpoint.identity.nextWaveIndex}.`,
+            existing?.status === "completed"
+                ? "A previous replanning task completed, but no superseding continue assessment was published; rerun replanning completion."
+                : undefined
+        ].filter((line) => line !== undefined).join(" "),
+        summary: `Replan packet workstream after wave assessment ${assessment.id}`,
+        contextBuilder: env.input.contextBuilder,
+        now: env.input.now
+    }, env.input.contextBuilder.build({
+        taskKind: "wave_plan_replanning",
+        repoIdentifier: parentPr.repoSlug,
+        sourceKind: "pull_request",
+        sourceUrl: parentPr.url,
+        parentUrl: issue.url,
+        labels: parentPr.labels,
+        issueTitle: issue.title,
+        issueBody: issue.body,
+        waveAssessmentCheckpoint: checkpoint,
+        finalizedWaveAssessment: assessment,
+        ...(repoSyncRecord?.localPath ? { localRepoPath: repoSyncRecord.localPath } : {})
+    }), workstream.id);
+}
+function resolveWaveAssessmentTaskContext(context, env) {
+    const { workstream, attention, issue, repoSyncRecord } = context;
+    if (workstream.origin.type !== "issue" ||
+        !issue ||
+        issue.state !== "open" ||
+        !attention?.reasons.includes("packet_wave_complete_sync_needed")) {
+        return undefined;
+    }
+    const checkpoint = resolveWaveAssessmentCheckpoint(context, env);
+    if (!checkpoint) {
+        return undefined;
+    }
+    const parentPrNumber = workstream.integration?.prNumber;
+    const parentPr = parentPrNumber !== undefined
+        ? env.currentPrsByRepoAndNumber.get(`${workstream.repoKey}:${parentPrNumber}`)
+        : undefined;
+    if (!parentPr || parentPr.state !== "open") {
+        return undefined;
+    }
+    return { checkpoint, issue, parentPr, repoSyncRecord, workstream };
+}
+function resolveWaveAssessmentCheckpoint(context, env) {
+    const { workstream, repoConfig, repoSyncRecord } = context;
+    const defaultBranch = repoConfig?.defaultBranch ?? repoSyncRecord?.defaultBranch ?? undefined;
+    const preflight = buildParentBranchSyncPreflight({ workstream, defaultBranch });
+    if (!preflight || !preflight.parentPrNumber) {
+        return undefined;
+    }
+    const parentPr = env.currentPrsByRepoAndNumber.get(`${workstream.repoKey}:${preflight.parentPrNumber}`);
+    if (!parentPr?.headSha) {
+        return undefined;
+    }
+    return buildWaveAssessmentCheckpoint(buildWaveAssessmentCheckpointIdentity(preflight, {
+        parentHeadSha: parentPr.headSha,
+        planRevision: resolvePlanRevision(workstream),
+        originalPlanningSessionId: resolveOriginalPlanningSessionId(workstream, env),
+        planNodeIds: workstream.packetPlan ? Object.keys(workstream.packetPlan.packets).sort() : []
+    }));
+}
+function buildWaveAssessmentTaskId(checkpoint) {
+    return `task:wave_plan_assessment:${checkpoint.id}`;
+}
+function buildWaveReplanningTaskId(checkpoint) {
+    return `task:wave_plan_replanning:${checkpoint.id}`;
+}
+function hasUnresolvedTask(env, taskId) {
+    const task = env.existingTasksById.get(taskId);
+    return task?.status === "pending" || task?.status === "dispatched" || task?.status === "failed";
+}
+function findMatchingPublishedFinalizedWaveAssessment(workstream, env, identity, options = {}) {
+    return findMatchingFinalizedWaveAssessment(workstream, env, identity, { ...options, requirePostedComment: true });
+}
+function findMatchingFinalizedWaveAssessment(workstream, env, identity, options) {
+    const persistedAssessments = workstream.packetPlan?.waveAssessments ?? [];
+    const executionAssessments = env.input.previousState.executions
+        .map(readWaveAssessmentResult)
+        .filter((assessment) => assessment !== undefined);
+    const assessments = [...persistedAssessments, ...executionAssessments]
+        .filter((assessment) => assessment.status === "finalized")
+        .filter((assessment) => !options.requirePostedComment || Boolean(assessment.postedCommentId))
+        .filter((assessment) => options.decision === undefined || assessment.decision === options.decision)
+        .filter((assessment) => checkpointIdentitiesEqual(assessment.checkpoint.identity, identity))
+        .sort(compareAssessmentsNewestFirst);
+    return assessments[0];
+}
+function readWaveAssessmentResult(execution) {
+    const result = execution.result;
+    return result?.waveAssessment;
+}
+function compareAssessmentsNewestFirst(left, right) {
+    return getAssessmentTimestamp(right).localeCompare(getAssessmentTimestamp(left));
+}
+function getAssessmentTimestamp(assessment) {
+    return assessment.finalizedAt ?? assessment.updatedAt ?? assessment.createdAt ?? "";
+}
+function checkpointIdentitiesEqual(left, right) {
+    return (left.repoKey === right.repoKey &&
+        left.workstreamId === right.workstreamId &&
+        left.waveId === right.waveId &&
+        left.parentPrNumber === right.parentPrNumber &&
+        left.parentHeadSha === right.parentHeadSha &&
+        left.parentIntegrationBranch === right.parentIntegrationBranch &&
+        left.defaultBranch === right.defaultBranch &&
+        left.planRevision === right.planRevision &&
+        left.originalPlanningSessionId === right.originalPlanningSessionId &&
+        left.currentWaveIndex === right.currentWaveIndex &&
+        left.nextWaveIndex === right.nextWaveIndex &&
+        arraysEqual(left.completedPacketIds, right.completedPacketIds) &&
+        arraysEqual(left.pendingFuturePacketIds, right.pendingFuturePacketIds) &&
+        arraysEqual(left.planNodeIds, right.planNodeIds));
+}
+function arraysEqual(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function resolvePlanRevision(workstream) {
+    return (workstream.packetPlan?.source?.generatedAt ??
+        workstream.packetPlan?.updatedAt ??
+        `${workstream.packetPlan?.currentWaveIndex ?? 0}:${Object.keys(workstream.packetPlan?.packets ?? {}).sort().join(",")}`);
+}
+function resolveOriginalPlanningSessionId(workstream, env) {
+    const planBreakdownExecutions = env.input.previousState.executions
+        .filter((execution) => execution.taskKind === "plan_breakdown" && execution.taskStatus === "completed")
+        .filter((execution) => {
+        const task = env.input.previousState.tasks.find((candidate) => candidate.id === execution.taskId);
+        return task?.workstreamId === workstream.id;
+    })
+        .sort((left, right) => right.endedAt.localeCompare(left.endedAt));
+    return planBreakdownExecutions[0]?.result?.planBreakdownSessionId ?? "unknown";
+}

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

@@ -0,0 +1,101 @@
+import { buildTaskRecord, createPullRequestTask } from "../builders.js";
+export const writePlanHandler = {
+    name: "write_plan",
+    derive(context, env) {
+        const task = deriveWritePlanTask(context, env);
+        return task ? [task] : [];
+    }
+};
+export function deriveWritePlanTask(context, env) {
+    const { workstream, attention, issue, activePullRequest, activeWorktree, repoSyncRecord, packetPullRequest } = context;
+    if (workstream.status !== "open" ||
+        workstream.phase === "abandoned" ||
+        workstream.phase === "resolved") {
+        return undefined;
+    }
+    if (packetPullRequest && packetPullRequest.state !== "open") {
+        return undefined;
+    }
+    const isPacketPlanning = activeWorktree?.packet && activeWorktree.status === "planning";
+    if (!isPacketPlanning && workstream.origin.type === "issue") {
+        if (workstream.phase === "product_discovery" || workstream.phase === "product_specification") {
+            return undefined;
+        }
+        if (workstream.product && workstream.product.status !== "spec_written") {
+            return undefined;
+        }
+    }
+    if (workstream.phase !== "planning" && workstream.phase !== "plan_feedback" && !isPacketPlanning) {
+        return undefined;
+    }
+    if (!isPacketPlanning) {
+        if (attention?.reasons.includes("pr_review_requested") ||
+            (attention?.reasons.includes("plan_approved") && activeWorktree?.status !== "planning")) {
+            return undefined;
+        }
+    }
+    if (activeWorktree?.status !== "planning") {
+        return undefined;
+    }
+    if (activeWorktree) {
+        const parentSource = issue ?? activePullRequest;
+        const source = (isPacketPlanning ? packetPullRequest : undefined) ?? parentSource;
+        if (source) {
+            return createWorktreeWritePlanTask(source, activeWorktree, {
+                contextBuilder: env.input.contextBuilder,
+                now: env.input.now
+            }, parentSource, workstream.id);
+        }
+    }
+    if (!activePullRequest) {
+        return undefined;
+    }
+    return createPullRequestTask("write_plan", activePullRequest, repoSyncRecord, {
+        reason: 'Pull request carries the "agent-in-progress" label and still needs the planning step.',
+        summary: `Write plan for PR #${activePullRequest.number}: ${activePullRequest.title}`,
+        contextBuilder: env.input.contextBuilder,
+        now: env.input.now
+    }, undefined, workstream.id);
+}
+function createWorktreeWritePlanTask(source, worktree, input, parentSource, workstreamId) {
+    const reason = worktree.packet
+        ? `Implementation packet "${worktree.packet.packetId}" is in wave ${worktree.packet.waveIndex} and is ready for planning.`
+        : source.kind === "issue"
+            ? "Product Spec is written; the first engineering step is to write the plan."
+            : 'Pull request carries the "agent-in-progress" label and still needs the planning step.';
+    const summary = worktree.packet
+        ? `Write plan for packet "${worktree.packet.packetId}" in wave ${worktree.packet.waveIndex}`
+        : `Write plan for ${source.kind === "issue" ? "issue" : "PR"} #${source.number}: ${source.title}`;
+    return buildTaskRecord(`task:write_plan:worktree:${worktree.id}`, "write_plan", source, undefined, {
+        reason,
+        summary,
+        contextBuilder: input.contextBuilder,
+        now: input.now
+    }, input.contextBuilder.build({
+        taskKind: "write_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
+                }
+                : {}),
+        ...(worktree.triggerCommentUrl ? { commentUrl: worktree.triggerCommentUrl } : {}),
+        ...(worktree.triggerCommentText ? { commentText: worktree.triggerCommentText } : {})
+    }), workstreamId);
+}

package/dist/src/tasks/derivation/handlers/write-product-spec.js

@@ -0,0 +1,49 @@
+import { buildTaskRecord } from "../builders.js";
+export const writeProductSpecHandler = {
+    name: "write_product_spec",
+    derive(context, env) {
+        const task = deriveWriteProductSpecTask(context, env);
+        return task ? [task] : [];
+    }
+};
+function deriveWriteProductSpecTask(context, env) {
+    const { workstream, issue, activeWorktree } = context;
+    if (!issue || workstream.origin.type !== "issue") {
+        return undefined;
+    }
+    if (workstream.phase !== "product_specification") {
+        return undefined;
+    }
+    if (!activeWorktree || activeWorktree.status !== "product_specification") {
+        return undefined;
+    }
+    if (activeWorktree.productSpecWrittenAt) {
+        return undefined;
+    }
+    return createWorktreeProductSpecTask(issue, activeWorktree, {
+        contextBuilder: env.input.contextBuilder,
+        now: env.input.now
+    }, workstream.id);
+}
+function createWorktreeProductSpecTask(issue, worktree, input, workstreamId) {
+    const productSpecDocumentPath = worktree.productSpecDocumentPath;
+    return buildTaskRecord(`task:write_product_spec:worktree:${worktree.id}`, "write_product_spec", issue, undefined, {
+        reason: "Issue has Product approval; Product Manager must write the Product Spec before engineering planning.",
+        summary: `Write Product Spec for issue #${issue.number}: ${issue.title}`,
+        contextBuilder: input.contextBuilder,
+        now: input.now
+    }, input.contextBuilder.build({
+        taskKind: "write_product_spec",
+        repoIdentifier: issue.repoSlug,
+        sourceKind: "issue",
+        sourceUrl: issue.url,
+        labels: issue.labels,
+        localRepoPath: worktree.path,
+        branchName: worktree.branchName,
+        planDocumentPath: worktree.planDocumentPath,
+        ...(productSpecDocumentPath ? { productSpecDocumentPath } : {}),
+        logDocumentPath: worktree.logDocumentPath,
+        issueTitle: issue.title,
+        issueBody: issue.body
+    }), workstreamId);
+}

package/dist/src/tasks/derivation/runner.js

@@ -0,0 +1,18 @@
+export function runBlockingHandler(handler, context, env, sink) {
+    const tasks = handler.derive(context, env, sink);
+    let shouldBlock = false;
+    for (const task of tasks) {
+        const mergedTask = sink.add(task);
+        if (handler.shouldBlockRemainingHandlers(mergedTask)) {
+            shouldBlock = true;
+        }
+    }
+    return shouldBlock;
+}
+export function runHandlers(handlers, context, env, sink) {
+    for (const handler of handlers) {
+        for (const task of handler.derive(context, env, sink)) {
+            sink.add(task);
+        }
+    }
+}

package/dist/src/tasks/derivation/types.js

@@ -0,0 +1 @@
+export {};