@backburner/cli 0.1.0

package/dist/src/workflows/registry.js

@@ -0,0 +1,174 @@
+const READ_ONLY_HANDOFF_POLICY = {
+    expectsPushableHandoff: false,
+    orchestratorOwnsPush: true,
+    remotePublishOwner: "orchestrator"
+};
+const WORKSPACE_WRITE_HANDOFF_POLICY = {
+    expectsPushableHandoff: true,
+    orchestratorOwnsPush: true,
+    remotePublishOwner: "orchestrator"
+};
+const WORKFLOW_TASK_DEFINITIONS = [
+    {
+        kind: "product_discovery",
+        role: "product",
+        modelClass: "strong",
+        executionPermission: "read-only",
+        handoffPolicy: READ_ONLY_HANDOFF_POLICY,
+        sourceKinds: ["issue"]
+    },
+    {
+        kind: "write_product_spec",
+        role: "product",
+        modelClass: "strong",
+        executionPermission: "workspace-write",
+        handoffPolicy: WORKSPACE_WRITE_HANDOFF_POLICY,
+        sourceKinds: ["issue"]
+    },
+    {
+        kind: "respond_issue_comment",
+        role: "discussion",
+        modelClass: "strong",
+        executionPermission: "read-only",
+        handoffPolicy: READ_ONLY_HANDOFF_POLICY,
+        sourceKinds: ["comment"]
+    },
+    {
+        kind: "review_pr",
+        role: "review",
+        modelClass: "strong",
+        executionPermission: "read-only",
+        handoffPolicy: READ_ONLY_HANDOFF_POLICY,
+        sourceKinds: ["pull_request"]
+    },
+    {
+        kind: "respond_pr_comment",
+        role: "discussion",
+        modelClass: "cheap",
+        executionPermission: "workspace-write",
+        handoffPolicy: WORKSPACE_WRITE_HANDOFF_POLICY,
+        sourceKinds: ["comment"]
+    },
+    {
+        kind: "write_plan",
+        role: "planning",
+        modelClass: "strong",
+        executionPermission: "workspace-write",
+        handoffPolicy: WORKSPACE_WRITE_HANDOFF_POLICY,
+        sourceKinds: ["issue"]
+    },
+    {
+        kind: "implement_plan",
+        role: "implementation",
+        modelClass: "cheap",
+        executionPermission: "workspace-write",
+        handoffPolicy: WORKSPACE_WRITE_HANDOFF_POLICY,
+        sourceKinds: ["pull_request"]
+    },
+    {
+        kind: "plan_breakdown",
+        role: "implementation_manager",
+        modelClass: "strong",
+        executionPermission: "read-only",
+        handoffPolicy: READ_ONLY_HANDOFF_POLICY,
+        sourceKinds: ["issue", "pull_request"]
+    },
+    {
+        kind: "wave_plan_assessment",
+        role: "planning",
+        modelClass: "strong",
+        executionPermission: "read-only",
+        handoffPolicy: READ_ONLY_HANDOFF_POLICY,
+        sourceKinds: ["pull_request"]
+    },
+    {
+        kind: "wave_plan_replanning",
+        role: "implementation_manager",
+        modelClass: "strong",
+        executionPermission: "workspace-write",
+        handoffPolicy: WORKSPACE_WRITE_HANDOFF_POLICY,
+        sourceKinds: ["pull_request"]
+    },
+    {
+        kind: "sync_parent_branch_preflight",
+        role: "implementation_manager",
+        modelClass: "strong",
+        executionPermission: "read-only",
+        handoffPolicy: READ_ONLY_HANDOFF_POLICY,
+        sourceKinds: ["issue"]
+    },
+    {
+        kind: "sync_parent_branch",
+        role: "implementation_manager",
+        modelClass: "strong",
+        executionPermission: "workspace-write",
+        handoffPolicy: WORKSPACE_WRITE_HANDOFF_POLICY,
+        sourceKinds: ["pull_request"]
+    },
+    {
+        kind: "prepare_pr_for_merge",
+        role: "implementation_manager",
+        modelClass: "strong",
+        executionPermission: "workspace-write",
+        handoffPolicy: WORKSPACE_WRITE_HANDOFF_POLICY,
+        sourceKinds: ["pull_request"]
+    },
+    {
+        kind: "extract_retrospective_problems",
+        role: "retrospective",
+        modelClass: "strong",
+        executionPermission: "read-only",
+        handoffPolicy: READ_ONLY_HANDOFF_POLICY,
+        sourceKinds: ["retrospective_candidate"]
+    },
+    {
+        kind: "investigate_learning_opportunity",
+        role: "retrospective",
+        modelClass: "strong",
+        executionPermission: "read-only",
+        handoffPolicy: READ_ONLY_HANDOFF_POLICY,
+        sourceKinds: ["retrospective_problem"]
+    },
+    {
+        kind: "draft_management_learning_proposal",
+        role: "retrospective",
+        modelClass: "strong",
+        executionPermission: "read-only",
+        handoffPolicy: READ_ONLY_HANDOFF_POLICY,
+        sourceKinds: ["learning_opportunity"]
+    }
+];
+export class WorkflowRegistry {
+    definitions;
+    constructor(definitions = WORKFLOW_TASK_DEFINITIONS) {
+        this.definitions = new Map(definitions.map((def) => [def.kind, def]));
+    }
+    getDefinition(kind) {
+        const definition = this.definitions.get(kind);
+        if (!definition) {
+            throw new Error(`No workflow task definition registered for task kind "${kind}"`);
+        }
+        return definition;
+    }
+    resolveTaskExecutionPolicy(kind) {
+        const definition = this.getDefinition(kind);
+        return {
+            executionPermission: definition.executionPermission,
+            handoffPolicy: definition.handoffPolicy
+        };
+    }
+    get definitionsList() {
+        return Array.from(this.definitions.values());
+    }
+}
+export const workflowRegistry = new WorkflowRegistry();
+export function getWorkflowTaskDefinition(kind) {
+    return workflowRegistry.getDefinition(kind);
+}
+/**
+ * Returns the list of capability names required by the given task kind.
+ * Returns an empty array when the kind has no required capabilities.
+ */
+export function getRequiredCapabilityNames(kind) {
+    return workflowRegistry.getDefinition(kind).requiredCapabilityNames ?? [];
+}

package/dist/src/workflows/triage.js

@@ -0,0 +1,90 @@
+import { buildWorktreeProductSpecTaskRecord, ImplementationWorkflowService } from "../worktrees/service.js";
+export class TriageFollowUpService {
+    implementationWorkflow;
+    constructor(gitGateway, gitHubGateway, now = () => new Date().toISOString()) {
+        this.implementationWorkflow = new ImplementationWorkflowService(gitGateway, gitHubGateway, now);
+    }
+    async materializeStartImplementation(input) {
+        const reposById = new Map(input.repos.map((repo) => [repo.id, repo]));
+        const tasksById = new Map(input.tasks.map((task) => [task.id, task]));
+        const worktrees = [...this.implementationWorkflow.linkPullRequests(input.state.worktrees, input.state.prs, input.repos)];
+        for (const issue of input.issues) {
+            const repo = reposById.get(issue.repoId);
+            if (!repo || !issue.labels.includes(repo.labels.agentProductApproved)) {
+                continue;
+            }
+            const repoPath = input.repoPaths.get(issue.repoId);
+            if (!repoPath) {
+                continue;
+            }
+            const alreadyHasSpecTask = [...tasksById.values()].some((task) => task.kind === "write_product_spec" && task.sourceId === issue.id);
+            const existingWorktree = worktrees.find((worktree) => worktree.repoId === repo.id && worktree.issueNumber === issue.number);
+            if (existingWorktree &&
+                existingWorktree.status !== "closed" &&
+                existingWorktree.prNumber !== undefined &&
+                existingWorktree.prUrl !== undefined &&
+                (existingWorktree.productSpecWrittenAt || alreadyHasSpecTask)) {
+                continue;
+            }
+            const prepared = await this.implementationWorkflow.ensureWorktreeForIssue({
+                repo,
+                repoPath,
+                codeRoot: input.codeRoot,
+                issue,
+                decision: {
+                    decision: "start_implementation",
+                    summary: "Product direction approved; prepare Product Spec before engineering planning."
+                },
+                existingWorktrees: worktrees
+            });
+            const existingIndex = worktrees.findIndex((worktree) => worktree.id === prepared.worktree.id);
+            if (existingIndex === -1) {
+                worktrees.push(prepared.worktree);
+            }
+            else {
+                worktrees[existingIndex] = prepared.worktree;
+            }
+            let withPr;
+            try {
+                const result = await this.implementationWorkflow.ensurePullRequestForWorktree(repo, issue, prepared.worktree);
+                withPr = result.worktree;
+            }
+            catch {
+                continue;
+            }
+            const pushedIndex = worktrees.findIndex((worktree) => worktree.id === withPr.id);
+            if (pushedIndex === -1) {
+                worktrees.push(withPr);
+            }
+            else {
+                worktrees[pushedIndex] = withPr;
+            }
+            if (!withPr.productSpecWrittenAt && !alreadyHasSpecTask) {
+                const writeProductSpecTask = buildWorktreeProductSpecTaskRecord(withPr, issue, input.state.issueMetadata.generatedAt ?? withPr.updatedAt);
+                tasksById.set(writeProductSpecTask.id, writeProductSpecTask);
+            }
+        }
+        return {
+            tasks: [...tasksById.values()].sort(compareTasks),
+            worktrees: worktrees.sort(compareWorktrees)
+        };
+    }
+}
+function compareTasks(left, right) {
+    const repoComparison = left.repoSlug.localeCompare(right.repoSlug);
+    if (repoComparison !== 0) {
+        return repoComparison;
+    }
+    const kindComparison = left.kind.localeCompare(right.kind);
+    if (kindComparison !== 0) {
+        return kindComparison;
+    }
+    return left.id.localeCompare(right.id);
+}
+function compareWorktrees(left, right) {
+    const repoComparison = left.repoSlug.localeCompare(right.repoSlug);
+    if (repoComparison !== 0) {
+        return repoComparison;
+    }
+    return left.id.localeCompare(right.id);
+}

package/dist/src/workflows/workstream-machine/derive-events.js

@@ -0,0 +1,121 @@
+import { hasFeedback, isAbandoned, isReviewRequested, isResolved } from "./selectors.js";
+export function deriveWorkstreamMachineEvents(input) {
+    // Repo reconciliation has already resolved the workstream projection; this layer
+    // only converts those resolved facts into ordered phase-machine events.
+    const events = derivePrimaryPhaseEvents(input);
+    for (const rule of eventRules) {
+        events.push(...rule.derive(input, events));
+    }
+    return events;
+}
+const eventRules = [
+    {
+        derive: (input) => input.previousPhase === undefined ? [{ type: "WORKSTREAM_INITIALIZED" }] : []
+    },
+    {
+        derive: (input) => input.attentionReasons.includes("contextual_feedback_received")
+            ? [{ type: "contextualFeedbackReceived" }]
+            : []
+    },
+    {
+        derive: (_input, events) => hasPhaseSignal(events) ? [] : [{ type: "NO_PHASE_SIGNAL_OBSERVED" }]
+    }
+];
+function derivePrimaryPhaseEvents(input) {
+    if (isResolved(input)) {
+        return [{ type: "WORKSTREAM_MERGED" }];
+    }
+    if (isAbandoned(input)) {
+        return [{ type: "WORKSTREAM_CLOSED" }];
+    }
+    if (input.attentionReasons.includes("cancel_requested")) {
+        return [{ type: "CANCEL" }];
+    }
+    if (input.attentionReasons.includes("retry_requested")) {
+        return [{ type: "RETRY" }];
+    }
+    if (input.attentionReasons.includes("product_approval_observed") &&
+        input.activeWorktreeStatus === undefined) {
+        return [{ type: "PRODUCT_APPROVAL_OBSERVED" }];
+    }
+    if (isReviewRequested(input)) {
+        return [{ type: "ACTIVE_PR_REVIEW_REQUEST_OBSERVED" }];
+    }
+    const feedbackSource = hasFeedback(input)
+        ? deriveFeedbackSource(input.attentionReasons)
+        : undefined;
+    if (input.activeWorktreeStatus === "implementing") {
+        return feedbackSource === undefined
+            ? [{ type: "ACTIVE_WORKTREE_STATUS_OBSERVED", status: input.activeWorktreeStatus }]
+            : [{ type: "IMPLEMENTATION_FEEDBACK_OBSERVED", source: feedbackSource }];
+    }
+    if (input.activeWorktreeStatus === "implementation_done") {
+        return feedbackSource === undefined
+            ? [{ type: "ACTIVE_WORKTREE_STATUS_OBSERVED", status: input.activeWorktreeStatus }]
+            : [{ type: "IMPLEMENTATION_FEEDBACK_OBSERVED", source: feedbackSource }];
+    }
+    if (input.activeWorktreeStatus === "implementation_ready") {
+        return [{ type: "ACTIVE_WORKTREE_STATUS_OBSERVED", status: input.activeWorktreeStatus }];
+    }
+    if (input.activeWorktreeStatus === "product_specification") {
+        return [{ type: "ACTIVE_WORKTREE_STATUS_OBSERVED", status: input.activeWorktreeStatus }];
+    }
+    if (input.activeWorktreeStatus === "awaiting_plan_approval" &&
+        activePullRequestHasLabel(input, input.approvalLabel)) {
+        return [{ type: "ACTIVE_PR_PLAN_APPROVAL_OBSERVED" }];
+    }
+    if (input.activeWorktreeStatus === "planning" ||
+        input.activeWorktreeStatus === "awaiting_plan_approval") {
+        return feedbackSource === undefined
+            ? [{ type: "ACTIVE_WORKTREE_STATUS_OBSERVED", status: input.activeWorktreeStatus }]
+            : [{ type: "PLANNING_FEEDBACK_OBSERVED", source: feedbackSource }];
+    }
+    if (activePullRequestHasLabel(input, input.inProgressLabel)) {
+        return feedbackSource === undefined
+            ? [{ type: "ACTIVE_PR_PLANNING_LABEL_OBSERVED" }]
+            : [{ type: "PLANNING_FEEDBACK_OBSERVED", source: feedbackSource }];
+    }
+    if (input.activeWorktreeStatus !== undefined) {
+        if (feedbackSource !== undefined && isPriorPullRequestImplementationFallback(input)) {
+            return [{ type: "IMPLEMENTATION_FEEDBACK_OBSERVED", source: feedbackSource }];
+        }
+        if (feedbackSource !== undefined) {
+            return [{ type: "PLANNING_FEEDBACK_OBSERVED", source: feedbackSource }];
+        }
+        return [{ type: "ACTIVE_WORKTREE_STATUS_OBSERVED", status: input.activeWorktreeStatus }];
+    }
+    return feedbackSource === undefined
+        ? []
+        : [{ type: "WORKSTREAM_COMMENT_ATTENTION_OBSERVED", source: feedbackSource }];
+}
+function activePullRequestHasLabel(input, label) {
+    // Active PR/worktree events intentionally refer only to the selected active projection.
+    return label !== undefined && input.activePullRequestLabels.includes(label);
+}
+function deriveFeedbackSource(reasons) {
+    const hasIssueComment = reasons.some(isIssueCommentFeedback);
+    const hasPullRequestComment = reasons.some(isPullRequestCommentFeedback);
+    if (hasIssueComment && hasPullRequestComment) {
+        return "mixed";
+    }
+    return hasIssueComment ? "issue_comment" : "pr_comment";
+}
+function isIssueCommentFeedback(reason) {
+    return reason === "issue_comment_added" || reason === "issue_comment_edited";
+}
+function isPullRequestCommentFeedback(reason) {
+    return reason === "pr_comment_added" || reason === "pr_comment_edited";
+}
+function hasPhaseSignal(events) {
+    return events.some((event) => event.type !== "WORKSTREAM_INITIALIZED" &&
+        event.type !== "WORKSTREAM_COMMENT_ATTENTION_OBSERVED" &&
+        event.type !== "contextualFeedbackReceived");
+}
+function isPriorPullRequestImplementationFallback(input) {
+    return (input.originType === "pr" &&
+        input.activeWorktreeStatus !== undefined &&
+        (input.previousPhase === "implementation_ready" ||
+            input.previousPhase === "implementing" ||
+            input.previousPhase === "implementation_done" ||
+            input.previousPhase === "implementation_feedback"));
+}

package/dist/src/workflows/workstream-machine/evaluate.js

@@ -0,0 +1,24 @@
+import { createActor } from "xstate";
+import { deriveWorkstreamMachineEvents } from "./derive-events.js";
+import { workstreamMachine } from "./machine.js";
+export function evaluateWorkstreamMachine(input) {
+    const events = deriveWorkstreamMachineEvents(input);
+    const initialSnapshot = input.previousPhase === undefined
+        ? undefined
+        : workstreamMachine.resolveState({
+            value: input.previousPhase,
+            context: input
+        });
+    const actor = createActor(workstreamMachine, initialSnapshot === undefined
+        ? { input }
+        : {
+            input,
+            snapshot: initialSnapshot
+        }).start();
+    for (const event of events) {
+        actor.send(event);
+    }
+    const phase = actor.getSnapshot().value;
+    actor.stop();
+    return phase;
+}

package/dist/src/workflows/workstream-machine/events.js

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