@backburner/cli 0.1.0

package/dist/src/workstreams/plan-breakdown-generator/validate.js

@@ -0,0 +1,212 @@
+export function validateSession(session) {
+    const issues = [];
+    const checkStringArray = (arr, path, fieldName) => {
+        if (!Array.isArray(arr)) {
+            issues.push({ severity: "error", code: `missing-${fieldName}`, message: `${fieldName} must be an array`, path });
+            return false;
+        }
+        let allStrings = true;
+        arr.forEach((item, index) => {
+            if (typeof item !== "string") {
+                issues.push({
+                    severity: "error",
+                    code: `invalid-${fieldName}-element`,
+                    message: `${fieldName} element at index ${index} must be a string`,
+                    path: [...path, index.toString()]
+                });
+                allStrings = false;
+            }
+        });
+        return allStrings;
+    };
+    const checkString = (val, path, fieldName, required = true) => {
+        if (typeof val !== "string") {
+            issues.push({ severity: "error", code: `invalid-${fieldName}`, message: `${fieldName} must be a string`, path });
+            return false;
+        }
+        if (required && !val) {
+            issues.push({ severity: "error", code: `missing-${fieldName}`, message: `${fieldName} is required`, path });
+            return false;
+        }
+        return true;
+    };
+    // Required fields
+    checkString(session.title, ["title"], "title");
+    checkString(session.summary, ["summary"], "summary");
+    checkString(session.recommendedFirstWaveId, ["recommendedFirstWaveId"], "recommended-first-wave");
+    checkString(session.suggestedNextAction, ["suggestedNextAction"], "suggested-next-action");
+    checkString(session.createdAt, ["createdAt"], "createdAt");
+    checkString(session.updatedAt, ["updatedAt"], "updatedAt");
+    checkStringArray(session.graphConcerns, ["graphConcerns"], "graphConcerns");
+    checkStringArray(session.humanDecisionsNeeded, ["humanDecisionsNeeded"], "humanDecisionsNeeded");
+    if (typeof session.tasks !== "object" || session.tasks === null || Array.isArray(session.tasks)) {
+        issues.push({ severity: "error", code: "invalid-tasks", message: "tasks must be an object", path: ["tasks"] });
+    }
+    if (typeof session.waves !== "object" || session.waves === null || Array.isArray(session.waves)) {
+        issues.push({ severity: "error", code: "invalid-waves", message: "waves must be an object", path: ["waves"] });
+    }
+    const taskIds = new Set(Object.keys(session.tasks || {}));
+    if (taskIds.size === 0) {
+        issues.push({ severity: "error", code: "no-tasks", message: "At least one task is required" });
+    }
+    const waveIdsInOrder = new Set();
+    if (checkStringArray(session.waveOrder, ["waveOrder"], "waveOrder")) {
+        for (const waveId of session.waveOrder) {
+            if (waveIdsInOrder.has(waveId)) {
+                issues.push({ severity: "error", code: "duplicate-wave-order", message: `Wave ID ${waveId} appears multiple times in waveOrder`, path: ["waveOrder"] });
+            }
+            waveIdsInOrder.add(waveId);
+        }
+        if (waveIdsInOrder.size === 0) {
+            issues.push({ severity: "error", code: "no-waves", message: "At least one wave is required" });
+        }
+    }
+    const waves = session.waves || {};
+    for (const waveId of Object.keys(waves)) {
+        if (!waveIdsInOrder.has(waveId)) {
+            issues.push({ severity: "error", code: "orphaned-wave", message: `Wave ${waveId} exists but is not in waveOrder`, path: ["waves", waveId] });
+        }
+    }
+    // Task validation
+    for (const [taskId, task] of Object.entries(session.tasks || {})) {
+        if (checkString(task.id, ["tasks", taskId, "id"], "task-id")) {
+            if (task.id !== taskId) {
+                issues.push({ severity: "error", code: "task-id-mismatch", message: `Task entry ${taskId} has mismatched internal ID: ${task.id}`, path: ["tasks", taskId] });
+            }
+        }
+        checkString(task.title, ["tasks", taskId, "title"], "task-title");
+        checkString(task.description, ["tasks", taskId, "description"], "task-description");
+        if (typeof task.risk !== "string") {
+            issues.push({ severity: "error", code: "invalid-risk-type", message: `Task ${taskId} risk must be a string`, path: ["tasks", taskId, "risk"] });
+        }
+        else if (!["low", "medium", "high"].includes(task.risk)) {
+            issues.push({ severity: "error", code: "invalid-risk-value", message: `Task ${taskId} has invalid risk: ${task.risk}`, path: ["tasks", taskId, "risk"] });
+        }
+        const checkRefs = (refs, name) => {
+            if (!checkStringArray(refs, ["tasks", taskId, name], name)) {
+                return;
+            }
+            const seen = new Set();
+            for (const ref of refs) {
+                if (seen.has(ref)) {
+                    issues.push({ severity: "error", code: "duplicate-ref", message: `Task ${taskId} has duplicate reference in ${name}: ${ref}`, path: ["tasks", taskId, name] });
+                }
+                seen.add(ref);
+                if (ref === taskId) {
+                    issues.push({ severity: "error", code: "self-ref", message: `Task ${taskId} has a self-reference in ${name}`, path: ["tasks", taskId, name] });
+                }
+                if (!taskIds.has(ref)) {
+                    issues.push({ severity: "error", code: "unknown-ref", message: `Task ${taskId} references unknown task ID in ${name}: ${ref}`, path: ["tasks", taskId, name] });
+                }
+            }
+        };
+        checkRefs(task.dependsOn, "dependsOn");
+        checkRefs(task.blocks, "blocks");
+        checkRefs(task.canRunInParallelWith, "canRunInParallelWith");
+        // Warnings & More validation
+        if (checkStringArray(task.verification, ["tasks", taskId, "verification"], "verification")) {
+            if (task.verification.length === 0) {
+                issues.push({ severity: "warning", code: "missing-verification", message: `Task ${taskId} has no verification commands`, path: ["tasks", taskId] });
+            }
+        }
+        checkStringArray(task.acceptanceCriteria, ["tasks", taskId, "acceptanceCriteria"], "acceptanceCriteria");
+        checkStringArray(task.filesLikelyInvolved, ["tasks", taskId, "filesLikelyInvolved"], "filesLikelyInvolved");
+    }
+    // Wave validation
+    const tasksInWaves = new Set();
+    if (Array.isArray(session.waveOrder)) {
+        for (const waveId of session.waveOrder) {
+            const wave = waves[waveId];
+            if (!wave) {
+                issues.push({ severity: "error", code: "unknown-wave-order", message: `Wave ID ${waveId} in waveOrder does not exist in waves`, path: ["waveOrder"] });
+                continue;
+            }
+            if (checkString(wave.id, ["waves", waveId, "id"], "wave-id")) {
+                if (wave.id !== waveId) {
+                    issues.push({ severity: "error", code: "wave-id-mismatch", message: `Wave entry ${waveId} has mismatched internal ID: ${wave.id}`, path: ["waves", waveId] });
+                }
+            }
+            checkString(wave.rationale, ["waves", waveId, "rationale"], "wave-rationale");
+            if (checkStringArray(wave.taskIds, ["waves", waveId, "taskIds"], "wave-taskIds")) {
+                if (wave.taskIds.length === 0) {
+                    issues.push({ severity: "error", code: "empty-wave", message: `Wave ${waveId} has no tasks`, path: ["waves", waveId] });
+                }
+                for (const taskId of wave.taskIds) {
+                    if (!taskIds.has(taskId)) {
+                        issues.push({ severity: "error", code: "unknown-wave-task", message: `Wave ${waveId} references unknown task ID: ${taskId}`, path: ["waves", waveId] });
+                    }
+                    if (tasksInWaves.has(taskId)) {
+                        issues.push({ severity: "error", code: "duplicate-task-wave", message: `Task ${taskId} appears in multiple waves`, path: ["waves", waveId] });
+                    }
+                    tasksInWaves.add(taskId);
+                }
+            }
+        }
+    }
+    for (const taskId of taskIds) {
+        if (!tasksInWaves.has(taskId)) {
+            issues.push({ severity: "error", code: "unassigned-task", message: `Task ${taskId} is not assigned to any wave`, path: ["tasks", taskId] });
+        }
+    }
+    if (session.recommendedFirstWaveId && !waveIdsInOrder.has(session.recommendedFirstWaveId)) {
+        issues.push({ severity: "error", code: "invalid-first-wave", message: `recommendedFirstWaveId ${session.recommendedFirstWaveId} does not exist`, path: ["recommendedFirstWaveId"] });
+    }
+    // Wave dependency check. A wave is a dispatch batch, so dependencies must
+    // be satisfied by earlier waves, never by later or same-wave packets.
+    const taskToWaveIndex = new Map();
+    if (Array.isArray(session.waveOrder)) {
+        session.waveOrder.forEach((waveId, index) => {
+            const wave = waves[waveId];
+            if (wave && Array.isArray(wave.taskIds)) {
+                wave.taskIds.forEach((taskId) => taskToWaveIndex.set(taskId, index));
+            }
+        });
+    }
+    for (const [taskId, task] of Object.entries(session.tasks || {})) {
+        const currentWaveIndex = taskToWaveIndex.get(taskId);
+        if (currentWaveIndex === undefined)
+            continue;
+        if (Array.isArray(task.dependsOn)) {
+            for (const depId of task.dependsOn) {
+                const depWaveIndex = taskToWaveIndex.get(depId);
+                if (depWaveIndex !== undefined && depWaveIndex === currentWaveIndex) {
+                    issues.push({
+                        severity: "error",
+                        code: "same-wave-dependency",
+                        message: `Task ${taskId} (Wave ${currentWaveIndex + 1}) depends on ${depId} in the same wave; dependent packets must be split into later waves`,
+                        path: ["tasks", taskId, "dependsOn"]
+                    });
+                }
+                else if (depWaveIndex !== undefined && depWaveIndex > currentWaveIndex) {
+                    issues.push({
+                        severity: "error",
+                        code: "forward-dependency",
+                        message: `Task ${taskId} (Wave ${currentWaveIndex + 1}) depends on ${depId} in a later wave (Wave ${depWaveIndex + 1})`,
+                        path: ["tasks", taskId, "dependsOn"]
+                    });
+                }
+            }
+        }
+    }
+    // File overlap warning
+    const fileToTasks = new Map();
+    for (const [taskId, task] of Object.entries(session.tasks || {})) {
+        if (Array.isArray(task.filesLikelyInvolved)) {
+            for (const file of task.filesLikelyInvolved) {
+                if (!fileToTasks.has(file))
+                    fileToTasks.set(file, []);
+                fileToTasks.get(file).push(taskId);
+            }
+        }
+    }
+    for (const [file, overlappingTaskIds] of fileToTasks.entries()) {
+        if (overlappingTaskIds.length > 3) {
+            issues.push({
+                severity: "warning",
+                code: "heavy-file-overlap",
+                message: `File ${file} is involved in many tasks: ${overlappingTaskIds.join(", ")}`
+            });
+        }
+    }
+    return issues;
+}

package/dist/src/workstreams/plan-breakdown-schema.js

@@ -0,0 +1,175 @@
+export const PLAN_BREAKDOWN_JSON_CONTRACT = `Return exactly one JSON object matching this structure:
+{
+  "title": "Short descriptive title of the overall plan",
+  "summary": "High-level summary of the implementation strategy",
+  "tasks": [
+    {
+      "id": "T1",
+      "title": "Task title",
+      "description": "Detailed description of what to implement",
+      "dependsOn": [],
+      "blocks": [],
+      "canRunInParallelWith": [],
+      "risk": "low | medium | high",
+      "filesLikelyInvolved": ["src/file.ts"],
+      "acceptanceCriteria": ["Criterion 1"],
+      "verification": ["npm test"]
+    }
+  ],
+  "waves": [
+    {
+      "id": "W1",
+      "taskIds": ["T1"],
+      "rationale": "Why these tasks are grouped together"
+    }
+  ],
+  "recommendedFirstWaveId": "W1",
+  "graphConcerns": ["Any potential risks or complexities in the dependency graph"],
+  "humanDecisionsNeeded": ["Questions or choices that require human input"],
+  "suggestedNextAction": "The next concrete step for the orchestrator (e.g., move to implementation)"
+}`;
+export const PLAN_BREAKDOWN_GRAPH_RULES = [
+    "Every task must appear in exactly one wave.",
+    "Every task ID referenced in 'dependsOn', 'blocks', or 'canRunInParallelWith' must exist in the 'tasks' array.",
+    "Every wave must reference existing task IDs.",
+    "The 'recommendedFirstWaveId' must match an existing wave ID.",
+    "Dependencies ('dependsOn') must point only to tasks in earlier waves. A wave is a dispatch batch, so dependent tasks must never be grouped in the same wave.",
+    "All array fields are required; use empty arrays [] if no items exist.",
+    "Do not use null for optional fields; use empty strings or arrays as appropriate."
+];
+export const PLAN_BREAKDOWN_JSON_EXAMPLE_OBJECT = {
+    title: "Add XState Support",
+    summary: "Introduce XState for workstream phase management to improve reliability and observability.",
+    tasks: [
+        {
+            id: "T1",
+            title: "Add xstate dependency",
+            description: "Install xstate and @xstate/test in package.json.",
+            dependsOn: [],
+            blocks: ["T2"],
+            canRunInParallelWith: [],
+            risk: "low",
+            filesLikelyInvolved: ["package.json"],
+            acceptanceCriteria: ["xstate is listed in dependencies", "package-lock.json is updated"],
+            verification: ["npm list xstate"]
+        },
+        {
+            id: "T2",
+            title: "Define workstream machine",
+            description: "Create the state machine definition for workstream phases.",
+            dependsOn: ["T1"],
+            blocks: [],
+            canRunInParallelWith: [],
+            risk: "medium",
+            filesLikelyInvolved: ["src/workflows/workstream-machine.ts"],
+            acceptanceCriteria: ["Machine covers all WORKSTREAM_PHASES", "Transitions are correctly mapped"],
+            verification: ["npm test test/workstream-machine.test.ts"]
+        }
+    ],
+    waves: [
+        {
+            id: "W1",
+            taskIds: ["T1"],
+            rationale: "Initial environment setup."
+        },
+        {
+            id: "W2",
+            taskIds: ["T2"],
+            rationale: "Core logic implementation."
+        }
+    ],
+    recommendedFirstWaveId: "W1",
+    graphConcerns: ["Ensure transition logic matches existing manual phase advancement."],
+    humanDecisionsNeeded: ["Should we migrate existing workstreams immediately?"],
+    suggestedNextAction: "Apply implementation-start label to begin T1."
+};
+export const PLAN_BREAKDOWN_JSON_EXAMPLE = JSON.stringify(PLAN_BREAKDOWN_JSON_EXAMPLE_OBJECT, null, 2);
+export function validatePlanBreakdownResultForPrompt(result) {
+    const errors = [];
+    const taskIds = new Set();
+    for (const task of result.tasks) {
+        if (task.id && taskIds.has(task.id)) {
+            errors.push(`Duplicate task ID: ${task.id}`);
+        }
+        taskIds.add(task.id);
+    }
+    const waveIds = new Set();
+    for (const wave of result.waves) {
+        if (wave.id && waveIds.has(wave.id)) {
+            errors.push(`Duplicate wave ID: ${wave.id}`);
+        }
+        waveIds.add(wave.id);
+    }
+    const tasksInWaves = new Set();
+    if (result.tasks.length === 0) {
+        errors.push("At least one task is required.");
+    }
+    if (result.waves.length === 0) {
+        errors.push("At least one wave is required.");
+    }
+    for (const task of result.tasks) {
+        if (!task.id) {
+            errors.push(`Task has missing ID: ${task.title}`);
+            continue;
+        }
+        const checkArray = (refs, name) => {
+            const seen = new Set();
+            for (const ref of refs) {
+                if (seen.has(ref)) {
+                    errors.push(`Task ${task.id} has duplicate reference in ${name}: ${ref}`);
+                }
+                seen.add(ref);
+                if (ref === task.id) {
+                    errors.push(`Task ${task.id} has a self-reference in ${name}.`);
+                }
+                if (!taskIds.has(ref)) {
+                    errors.push(`Task ${task.id} references unknown task ID in ${name}: ${ref}`);
+                }
+            }
+        };
+        checkArray(task.dependsOn, "dependsOn");
+        checkArray(task.blocks, "blocks");
+        checkArray(task.canRunInParallelWith, "canRunInParallelWith");
+    }
+    for (const wave of result.waves) {
+        if (!wave.id)
+            errors.push(`Wave has missing ID: ${wave.rationale}`);
+        for (const taskId of wave.taskIds) {
+            if (!taskIds.has(taskId)) {
+                errors.push(`Wave ${wave.id} references unknown task ID: ${taskId}`);
+            }
+            if (tasksInWaves.has(taskId)) {
+                errors.push(`Task ${taskId} appears in multiple waves.`);
+            }
+            tasksInWaves.add(taskId);
+        }
+    }
+    for (const taskId of taskIds) {
+        if (taskId && !tasksInWaves.has(taskId)) {
+            errors.push(`Task ${taskId} is not assigned to any wave.`);
+        }
+    }
+    if (result.recommendedFirstWaveId && !waveIds.has(result.recommendedFirstWaveId)) {
+        errors.push(`recommendedFirstWaveId ${result.recommendedFirstWaveId} does not exist.`);
+    }
+    // Wave-based dependency check: dependsOn must be in previous waves.
+    const taskToWaveIndex = new Map();
+    result.waves.forEach((wave, index) => {
+        wave.taskIds.forEach((taskId) => taskToWaveIndex.set(taskId, index));
+    });
+    for (const task of result.tasks) {
+        const currentWaveIndex = taskToWaveIndex.get(task.id);
+        if (currentWaveIndex === undefined)
+            continue;
+        for (const depId of task.dependsOn) {
+            const depWaveIndex = taskToWaveIndex.get(depId);
+            if (depWaveIndex !== undefined && depWaveIndex === currentWaveIndex) {
+                errors.push(`Task ${task.id} (Wave ${currentWaveIndex + 1}) depends on ${depId} in the same wave; dependent tasks must be split into later waves.`);
+            }
+            else if (depWaveIndex !== undefined && depWaveIndex > currentWaveIndex) {
+                errors.push(`Task ${task.id} (Wave ${currentWaveIndex + 1}) depends on ${depId} in a later wave (Wave ${depWaveIndex + 1}).`);
+            }
+        }
+    }
+    return errors;
+}

package/dist/src/workstreams/utils.js

@@ -0,0 +1,15 @@
+import { createHash } from "node:crypto";
+import { slugify } from "../utils/slug.js";
+/**
+ * Returns a URL-safe, filesystem-safe, and git-ref-safe slug for a packet ID.
+ * Packet IDs are agent-produced and may contain characters like spaces, slashes, or colons.
+ *
+ * To prevent collisions between different IDs that slugify to the same string
+ * (e.g. "foo/bar" and "foo bar") or IDs that are truncated, a short stable hash
+ * is appended to the slug.
+ */
+export function getPacketSlug(packetId) {
+    const slug = slugify(packetId);
+    const hash = createHash("sha256").update(packetId).digest("hex").slice(0, 8);
+    return `${slug}-${hash}`;
+}

package/dist/src/workstreams/wave-assessment/checkpoint.js

@@ -0,0 +1,172 @@
+import { createHash } from "node:crypto";
+export function buildWaveAssessmentCheckpointIdentity(preflight, extra) {
+    return {
+        repoKey: preflight.repoKey,
+        workstreamId: preflight.workstreamId,
+        waveId: `wave-${preflight.currentWaveIndex}`,
+        parentPrNumber: preflight.parentPrNumber ?? 0,
+        parentHeadSha: extra?.parentHeadSha ?? preflight.parentHeadSha ?? "unknown",
+        parentIntegrationBranch: preflight.parentIntegrationBranch,
+        defaultBranch: preflight.defaultBranch,
+        planRevision: extra?.planRevision ?? preflight.planRevision ?? "unknown",
+        originalPlanningSessionId: extra?.originalPlanningSessionId ?? preflight.originalPlanningSessionId ?? "unknown",
+        currentWaveIndex: preflight.currentWaveIndex,
+        nextWaveIndex: preflight.nextWaveIndex,
+        completedPacketIds: [...preflight.completedPacketIds],
+        pendingFuturePacketIds: [...preflight.pendingFuturePacketIds],
+        planNodeIds: [
+            ...(extra?.planNodeIds ??
+                preflight.planNodeIds ?? [...preflight.completedPacketIds, ...preflight.pendingFuturePacketIds])
+        ]
+    };
+}
+export function buildWaveAssessmentCheckpoint(identity) {
+    const identityHash = createHash("sha256")
+        .update(stableStringifyIdentity(identity))
+        .digest("hex")
+        .slice(0, 16);
+    const id = [
+        "wave-assessment",
+        truncateIdPart(sanitizeIdPart(identity.repoKey), 40),
+        truncateIdPart(sanitizeIdPart(identity.workstreamId), 60),
+        `wave-${identity.currentWaveIndex}-to-${identity.nextWaveIndex}`,
+        `pr-${identity.parentPrNumber}`,
+        identityHash
+    ].join(":");
+    return {
+        id,
+        sessionId: id,
+        identity
+    };
+}
+export function buildWaveAssessmentCheckpointForPreflight(preflight) {
+    return buildWaveAssessmentCheckpoint(buildWaveAssessmentCheckpointIdentity(preflight));
+}
+export function waveAssessmentCheckpointIdentityMatches(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));
+}
+export function isWaveAssessmentStaleForPreflight(assessment, preflight) {
+    const checkpoint = buildWaveAssessmentCheckpointForPreflight(preflight);
+    return !waveAssessmentCheckpointIdentityMatches(assessment.checkpoint.identity, checkpoint.identity);
+}
+export function decideWaveAssessmentGate(input) {
+    const checkpoint = buildWaveAssessmentCheckpointForPreflight(input.preflight);
+    const { assessment } = input;
+    if (!assessment) {
+        return { status: "gated", reason: "assessment_missing", checkpoint };
+    }
+    if (!waveAssessmentCheckpointIdentityMatches(assessment.checkpoint.identity, checkpoint.identity)) {
+        return {
+            status: "stale",
+            reason: "assessment_checkpoint_stale",
+            checkpoint,
+            assessment
+        };
+    }
+    if (assessment.status !== "finalized") {
+        return {
+            status: "gated",
+            reason: "assessment_not_finalized",
+            checkpoint,
+            assessment
+        };
+    }
+    if (assessment.decision === "replan") {
+        return {
+            status: "gated",
+            reason: "assessment_requires_replan",
+            checkpoint,
+            assessment
+        };
+    }
+    if (assessment.decision === "blocked") {
+        return {
+            status: "gated",
+            reason: "assessment_blocked",
+            checkpoint,
+            assessment
+        };
+    }
+    if (!assessment.postedCommentId) {
+        return {
+            status: "gated",
+            reason: "assessment_comment_missing",
+            checkpoint,
+            assessment
+        };
+    }
+    return {
+        status: "allowed",
+        reason: "assessment_continue_comment_posted",
+        checkpoint,
+        assessment
+    };
+}
+function arraysEqual(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function sanitizeIdPart(value) {
+    return value.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "none";
+}
+function truncateIdPart(value, maxLength) {
+    return value.length <= maxLength ? value : value.slice(0, maxLength);
+}
+function stableStringifyIdentity(identity) {
+    return JSON.stringify({
+        repoKey: identity.repoKey,
+        workstreamId: identity.workstreamId,
+        waveId: identity.waveId,
+        parentPrNumber: identity.parentPrNumber,
+        parentHeadSha: identity.parentHeadSha,
+        parentIntegrationBranch: identity.parentIntegrationBranch,
+        defaultBranch: identity.defaultBranch,
+        planRevision: identity.planRevision,
+        originalPlanningSessionId: identity.originalPlanningSessionId,
+        currentWaveIndex: identity.currentWaveIndex,
+        nextWaveIndex: identity.nextWaveIndex,
+        completedPacketIds: identity.completedPacketIds,
+        pendingFuturePacketIds: identity.pendingFuturePacketIds,
+        planNodeIds: identity.planNodeIds
+    });
+}
+export function applyWaveAssessmentResultsToWorkstreams(input) {
+    if (input.assessments.length === 0) {
+        return input.workstreams;
+    }
+    const assessmentsByWorkstreamId = new Map();
+    for (const assessment of input.assessments) {
+        const list = assessmentsByWorkstreamId.get(assessment.checkpoint.identity.workstreamId) ?? [];
+        list.push(assessment);
+        assessmentsByWorkstreamId.set(assessment.checkpoint.identity.workstreamId, list);
+    }
+    return input.workstreams.map((workstream) => {
+        const assessments = assessmentsByWorkstreamId.get(workstream.id);
+        if (!workstream.packetPlan || !assessments || assessments.length === 0) {
+            return workstream;
+        }
+        const byId = new Map((workstream.packetPlan.waveAssessments ?? []).map((assessment) => [assessment.id, assessment]));
+        for (const assessment of assessments) {
+            byId.set(assessment.id, assessment);
+        }
+        return {
+            ...workstream,
+            packetPlan: {
+                ...workstream.packetPlan,
+                waveAssessments: [...byId.values()].sort((left, right) => left.id.localeCompare(right.id))
+            }
+        };
+    });
+}

package/dist/src/workstreams/wave-assessment/index.js

@@ -0,0 +1,3 @@
+export * from "./store.js";
+export * from "./tools.js";
+export * from "./validate.js";

package/dist/src/workstreams/wave-assessment/session.js

@@ -0,0 +1,84 @@
+import { randomUUID } from "node:crypto";
+export const WAVE_ASSESSMENT_DECISIONS = ["continue", "replan", "blocked"];
+export const WAVE_ASSESSMENT_FINDING_CATEGORIES = [
+    "correctness",
+    "completeness",
+    "drift",
+    "invalid_assumption"
+];
+export function createWaveAssessmentSession(input) {
+    const now = new Date().toISOString();
+    return {
+        ...input,
+        planNodeIds: [...input.planNodeIds],
+        sessionId: input.sessionId,
+        status: "open",
+        summary: "",
+        findings: [],
+        validationIssues: [],
+        timestamps: {
+            createdAt: now,
+            updatedAt: now
+        }
+    };
+}
+export function addWaveAssessmentFinding(session, input) {
+    const now = new Date().toISOString();
+    return {
+        ...session,
+        status: "open",
+        findings: [
+            ...session.findings,
+            {
+                id: randomUUID(),
+                category: input.category,
+                summary: input.summary,
+                details: input.details,
+                affectedPlanNodeIds: [...input.affectedPlanNodeIds],
+                createdAt: now
+            }
+        ],
+        validationIssues: [],
+        timestamps: {
+            ...session.timestamps,
+            updatedAt: now
+        }
+    };
+}
+export function completeWaveAssessmentSession(session, input) {
+    const now = new Date().toISOString();
+    return {
+        ...session,
+        status: "completed",
+        decision: input.decision,
+        summary: input.summary,
+        validationIssues: [],
+        timestamps: {
+            ...session.timestamps,
+            updatedAt: now,
+            finalizedAt: now
+        }
+    };
+}
+export function exportWaveAssessmentSession(session) {
+    if (session.status !== "completed" || !session.decision || !session.timestamps.finalizedAt) {
+        throw new Error(`Wave assessment session ${session.sessionId} is not completed`);
+    }
+    return {
+        sessionId: session.sessionId,
+        workstreamId: session.workstreamId,
+        waveId: session.waveId,
+        parentPrNumber: session.parentPrNumber,
+        assessedParentHeadSha: session.assessedParentHeadSha,
+        originalPlanningSessionId: session.originalPlanningSessionId,
+        currentPlanRevision: session.currentPlanRevision,
+        planNodeIds: [...session.planNodeIds],
+        decision: session.decision,
+        summary: session.summary,
+        findings: session.findings,
+        timestamps: {
+            createdAt: session.timestamps.createdAt,
+            finalizedAt: session.timestamps.finalizedAt
+        }
+    };
+}