yapout 0.4.0 → 0.4.2

package/dist/index.js

@@ -239,9 +239,10 @@ def main():
     # Build claude prompt based on action
     if action == "claim":
         prompt = (
-            f'Use yapout to implement ticket "{ticket_id}". '
-            f'Claim it with yapout_claim (use worktree mode), read the brief, '
-            f'implement the changes, run yapout_check, then ship with yapout_ship.'
+            f'Use yapout to implement work item "{ticket_id}". '
+            f'Claim it with yapout_claim using workItemId (use worktree mode), read the brief, '
+            f'implement the changes, run yapout_check, then ship with yapout_ship. '
+            f'The ID may be a bundle or standalone finding \u2014 yapout_claim auto-detects.'
         )
     elif action == "enrich":
         prompt = (
@@ -1086,12 +1087,42 @@ function registerUpdateContextTool(server, ctx) {
 
 // src/mcp/tools/queue.ts
 import { z as z3 } from "zod";
+function formatFinding(f, indent, done) {
+  const ref = f.linearIssueId ? `  ${f.linearIssueId}` : "";
+  const prefix = done ? "\u2713 " : "";
+  return `${indent}${prefix}${f.title}  ${f.type}\xB7${f.priority}${ref}`;
+}
+function formatWorkItem(item, done) {
+  const lines = [];
+  if (item.kind === "bundle") {
+    const count = item.findings.length;
+    const priority = item.findings.length > 0 ? item.findings.map((f) => f.priority).sort((a, b) => {
+      const order = { urgent: 0, high: 1, medium: 2, low: 3 };
+      return (order[a] ?? 3) - (order[b] ?? 3);
+    })[0] : "medium";
+    const prefix = done ? "\u2713 " : "";
+    const prRef = done && item.pr?.githubPrNumber ? `  PR #${item.pr.githubPrNumber}` : "";
+    lines.push(`  ${prefix}\u{1F4E6} ${item.title} (${count} findings) \u2014 ${priority}${prRef}`);
+    for (const f of item.findings) {
+      lines.push(formatFinding(f, "     ", done));
+    }
+  } else {
+    const f = item.findings[0];
+    if (f) {
+      const prRef = done && item.pr?.githubPrNumber ? `  PR #${item.pr.githubPrNumber}` : "";
+      const prefix = done ? "\u2713 " : "";
+      const ref = f.linearIssueId ? `  ${f.linearIssueId}` : "";
+      lines.push(`  ${prefix}${item.title}  ${f.type}\xB7${f.priority}${ref}${prRef}`);
+    }
+  }
+  return lines.join("\n");
+}
 function registerQueueTool(server, ctx) {
   server.tool(
     "yapout_queue",
-    "List findings ready for local implementation. Only returns findings in backlog/unstarted Linear status.",
+    "List work items (bundles and standalone findings) ready for local implementation, plus active and done items.",
     {
-      includeBlocked: z3.boolean().optional().describe("Show blocked findings too (default: false)")
+      includeIds: z3.boolean().optional().describe("Include work item IDs in output (default: false)")
     },
     async (args) => {
       if (!ctx.projectId) {
@@ -1106,55 +1137,84 @@ function registerQueueTool(server, ctx) {
         };
       }
       const data = await ctx.client.query(
-        anyApi2.functions.findings.getQueuedWorkItems,
+        anyApi2.functions.workQueue.getWorkQueue,
         { projectId: ctx.projectId }
       );
       if (!data) {
         return {
           content: [
-            { type: "text", text: "Could not fetch queue." }
+            { type: "text", text: "Could not fetch work queue." }
           ],
           isError: true
         };
       }
-      let ready = data.ready;
-      ready = ready.filter((t) => t.nature !== "operational");
-      const linearIds = ready.map((t) => t.linearIssueId).filter((id) => !!id);
-      if (linearIds.length > 0) {
-        try {
-          const statuses = await ctx.client.action(
-            anyApi2.functions.linearStatusMutations.getIssueStatuses,
-            { projectId: ctx.projectId, linearIssueIds: linearIds }
-          );
-          const statusMap = new Map(
-            statuses.map((s) => [s.linearIssueId, s.statusType])
-          );
-          ready = ready.filter((t) => {
-            if (!t.linearIssueId) return true;
-            const type = statusMap.get(t.linearIssueId);
-            if (!type) return true;
-            return type === "backlog" || type === "unstarted";
-          });
-        } catch {
+      const sections = [];
+      sections.push(`Ready (${data.ready.length}):`);
+      if (data.ready.length === 0) {
+        sections.push("  (none)");
+      } else {
+        for (const item of data.ready) {
+          const line = formatWorkItem(item);
+          if (args.includeIds) {
+            sections.push(`${line}  [${item.id}]`);
+          } else {
+            sections.push(line);
+          }
         }
       }
-      const result = {
-        ready,
-        contextStale: data.contextStale,
-        contextLastUpdated: data.contextLastUpdated
-      };
-      if (args.includeBlocked) {
-        result.blocked = data.blocked;
+      sections.push("");
+      sections.push(`Active (${data.active.length}):`);
+      if (data.active.length === 0) {
+        sections.push("  (none)");
+      } else {
+        for (const item of data.active) {
+          const statusTag = item.status === "failed" ? " \u274C FAILED" : item.status === "review" ? " \u{1F50D} review" : "";
+          const line = formatWorkItem(item);
+          if (args.includeIds) {
+            sections.push(`${line}${statusTag}  [${item.id}]`);
+          } else {
+            sections.push(`${line}${statusTag}`);
+          }
+        }
       }
-      if (data.contextStale) {
-        const daysAgo = data.contextLastUpdated ? Math.round(
-          (Date.now() - data.contextLastUpdated) / 864e5
-        ) : null;
-        result.note = daysAgo ? `Project context was last updated ${daysAgo} days ago. Consider running yapout_compact.` : "Project context has never been generated. Run yapout_compact.";
+      sections.push("");
+      sections.push(`Done (${data.done.length}):`);
+      if (data.done.length === 0) {
+        sections.push("  (none)");
+      } else {
+        for (const item of data.done) {
+          const line = formatWorkItem(item, true);
+          if (args.includeIds) {
+            sections.push(`${line}  [${item.id}]`);
+          } else {
+            sections.push(line);
+          }
+        }
+      }
+      if (data.agentStatus.isActive) {
+        sections.push("");
+        sections.push(`Agent: ${data.agentStatus.agentCount} active, ${data.agentStatus.worktreeCount} worktrees`);
       }
+      const structured = {
+        ready: data.ready.map((item) => ({
+          workItemId: item.id,
+          kind: item.kind,
+          title: item.title,
+          findings: item.findings.map((f) => ({
+            id: f.id,
+            title: f.title,
+            type: f.type,
+            priority: f.priority,
+            linearIssueId: f.linearIssueId
+          }))
+        })),
+        activeCount: data.active.length,
+        doneCount: data.done.length
+      };
       return {
         content: [
-          { type: "text", text: JSON.stringify(result, null, 2) }
+          { type: "text", text: sections.join("\n") },
+          { type: "text", text: "\n---\nStructured data:\n" + JSON.stringify(structured, null, 2) }
         ]
       };
     }
@@ -1166,30 +1226,84 @@ import { z as z4 } from "zod";
 function registerGetBriefTool(server, ctx) {
   server.tool(
     "yapout_get_brief",
-    "Fetch the full implementation context for a finding",
+    "Fetch the full implementation context for a work item (finding or bundle)",
     {
-      findingId: z4.string().describe("The finding ID to get the brief for")
+      findingId: z4.string().optional().describe("The finding ID to get the brief for (deprecated: use workItemId)"),
+      workItemId: z4.string().optional().describe("The work item ID (finding or bundle) to get the brief for")
     },
     async (args) => {
-      const data = await ctx.client.query(
-        anyApi2.functions.findings.getFindingBrief,
-        { findingId: args.findingId }
-      );
-      if (!data) {
+      const itemId = args.workItemId || args.findingId;
+      if (!itemId) {
         return {
           content: [
             {
               type: "text",
-              text: "Finding not found or you don't have access."
+              text: "Must provide workItemId or findingId."
             }
           ],
           isError: true
         };
       }
+      try {
+        const data = await ctx.client.query(
+          anyApi2.functions.findings.getFindingBrief,
+          { findingId: itemId }
+        );
+        if (data) {
+          return {
+            content: [
+              { type: "text", text: JSON.stringify(data, null, 2) }
+            ]
+          };
+        }
+      } catch {
+      }
+      try {
+        const bundle = await ctx.client.query(
+          anyApi2.functions.bundles.getBundle,
+          { bundleId: itemId }
+        );
+        if (bundle) {
+          const result = {
+            kind: "bundle",
+            bundle: {
+              id: bundle._id,
+              title: bundle.title,
+              description: bundle.description,
+              enrichedDescription: bundle.enrichedDescription,
+              acceptanceCriteria: bundle.acceptanceCriteria,
+              implementationBrief: bundle.implementationBrief
+            },
+            findings: bundle.findings.map((f) => ({
+              id: f._id,
+              title: f.title,
+              description: f.description,
+              priority: f.priority,
+              type: f.type,
+              linearIssueId: f.linearIssueId,
+              linearIssueUrl: f.linearIssueUrl,
+              enrichedDescription: f.enrichedDescription,
+              acceptanceCriteria: f.acceptanceCriteria,
+              implementationBrief: f.implementationBrief,
+              dependsOn: f.dependsOn
+            }))
+          };
+          return {
+            content: [
+              { type: "text", text: JSON.stringify(result, null, 2) }
+            ]
+          };
+        }
+      } catch {
+      }
       return {
         content: [
-          { type: "text", text: JSON.stringify(data, null, 2) }
-        ]
+          {
+            type: "text",
+            text: "Work item not found or you don't have access. Provide a valid finding ID or bundle ID."
+          }
+        ],
+        isError: true
       };
     }
   );
@@ -1210,7 +1324,7 @@ function readBranchPrefix(cwd) {
 function slugify(text) {
   return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40);
 }
-function formatBrief(data) {
+function formatFindingBrief(data) {
   const finding = data.finding;
   const sections = [
     `# ${finding.title}`,
@@ -1251,12 +1365,89 @@ function formatBrief(data) {
   }
   return sections.join("\n");
 }
+function formatBundleBrief(bundle, projectContext) {
+  const sections = [
+    `# Bundle: ${bundle.title}`,
+    "",
+    `**${bundle.findings.length} findings**`
+  ];
+  if (bundle.description) {
+    sections.push("", "## Bundle Description", "", bundle.description);
+  }
+  if (bundle.enrichedDescription) {
+    sections.push("", "## Enriched Description", "", bundle.enrichedDescription);
+  }
+  if (bundle.acceptanceCriteria && bundle.acceptanceCriteria.length > 0) {
+    sections.push("", "## Acceptance Criteria");
+    for (const ac of bundle.acceptanceCriteria) {
+      sections.push(`- [ ] ${ac}`);
+    }
+  }
+  if (bundle.implementationBrief) {
+    sections.push("", "## Implementation Brief", "", bundle.implementationBrief);
+  }
+  sections.push("", "---", "", "## Findings (Execution Order)", "");
+  for (let i = 0; i < bundle.findings.length; i++) {
+    const f = bundle.findings[i];
+    const linearRef = f.linearIssueId ? ` (${f.linearIssueId})` : "";
+    const deps = f.dependsOn && f.dependsOn.length > 0 ? `
+**Depends on:** ${f.dependsOn.map((d) => {
+      const dep = bundle.findings.find((bf) => bf._id === d);
+      return dep ? dep.title : d;
+    }).join(", ")}` : "";
+    sections.push(`### ${i + 1}. ${f.title}${linearRef}`);
+    sections.push("");
+    sections.push(`**Priority:** ${f.priority} | **Type:** ${f.type}`);
+    if (f.linearIssueUrl) {
+      sections.push(`**Linear:** ${f.linearIssueUrl}`);
+    }
+    if (deps) sections.push(deps);
+    sections.push("");
+    if (f.enrichedDescription) {
+      sections.push(f.enrichedDescription);
+      sections.push("");
+    } else if (f.description) {
+      sections.push(f.description);
+      sections.push("");
+    }
+    if (f.acceptanceCriteria && f.acceptanceCriteria.length > 0) {
+      sections.push("**Acceptance Criteria:**");
+      for (const ac of f.acceptanceCriteria) {
+        sections.push(`- [ ] ${ac}`);
+      }
+      sections.push("");
+    }
+    if (f.implementationBrief) {
+      sections.push("**Implementation Brief:**");
+      sections.push(f.implementationBrief);
+      sections.push("");
+    }
+  }
+  if (projectContext) {
+    sections.push("---", "", "## Project Context", "", projectContext);
+  }
+  return sections.join("\n");
+}
+async function detectWorkItemKind(client, workItemId) {
+  try {
+    const bundle = await client.query(
+      anyApi2.functions.bundles.getBundle,
+      { bundleId: workItemId }
+    );
+    if (bundle) {
+      return { kind: "bundle", data: bundle };
+    }
+  } catch {
+  }
+  return { kind: "standalone", data: null };
+}
 function registerClaimTool(server, ctx) {
   server.tool(
     "yapout_claim",
-    "Claim a finding for local implementation. Creates a branch (or worktree), writes the brief, and updates status.",
+    "Claim a work item (bundle or standalone finding) for local implementation. Creates a branch (or worktree), writes the brief, and updates status.",
     {
-      findingId: z5.string().describe("The finding ID to claim"),
+      workItemId: z5.string().describe("The work item ID to claim (bundle ID or finding ID from yapout_queue)"),
+      findingId: z5.string().optional().describe("Deprecated: use workItemId instead. If provided, treated as a standalone finding."),
       worktree: z5.boolean().optional().describe("Create a git worktree for parallel work (default: false)")
     },
     async (args) => {
@@ -1271,131 +1462,262 @@ function registerClaimTool(server, ctx) {
           isError: true
         };
       }
-      const briefData = await ctx.client.query(
-        anyApi2.functions.findings.getFindingBrief,
-        { findingId: args.findingId }
-      );
-      if (!briefData) {
+      const itemId = args.workItemId || args.findingId;
+      if (!itemId) {
         return {
           content: [
             {
               type: "text",
-              text: "Finding not found or you don't have access."
+              text: "Must provide workItemId (or deprecated findingId)."
             }
           ],
           isError: true
         };
       }
-      const finding = briefData.finding;
-      const linearIssueId = briefData.linearIssueId;
-      const defaultBranch = briefData.defaultBranch || "main";
-      const prefix = readBranchPrefix(ctx.cwd);
-      const slug = slugify(finding.title);
-      const branchName = linearIssueId ? `${prefix}/${linearIssueId.toLowerCase()}-${slug}` : `${prefix}/${slug}`;
-      const claim = await ctx.client.mutation(
-        anyApi2.functions.findings.claimFindingLocal,
-        { findingId: args.findingId, branchName }
-      );
-      if (linearIssueId && ctx.projectId) {
-        try {
-          await ctx.client.action(
-            anyApi2.functions.linearStatusMutations.moveIssueStatus,
-            {
-              projectId: ctx.projectId,
-              linearIssueId,
-              statusType: "started"
-            }
-          );
-        } catch {
-        }
+      const { kind, data: bundleData } = await detectWorkItemKind(ctx.client, itemId);
+      if (kind === "bundle" && bundleData) {
+        return await claimBundle(ctx, args, itemId, bundleData);
+      } else {
+        return await claimStandalone(ctx, args, itemId);
       }
-      let worktreePath;
-      if (args.worktree) {
-        fetchOrigin(ctx.cwd);
-        worktreePath = createWorktree(
-          ctx.cwd,
-          args.findingId,
-          branchName,
-          defaultBranch
-        );
-        const wtYapoutDir = join7(worktreePath, ".yapout");
-        if (!existsSync6(wtYapoutDir)) mkdirSync6(wtYapoutDir, { recursive: true });
-        const brief2 = formatBrief(briefData);
-        writeFileSync7(join7(wtYapoutDir, "brief.md"), brief2);
-        try {
-          await ctx.client.mutation(
-            anyApi2.functions.pipelineRuns.reportDaemonEvent,
-            {
-              pipelineRunId: claim.pipelineRunId,
-              event: "worktree_created",
-              message: `Worktree: ${worktreePath}`
-            }
-          );
-        } catch {
+    }
+  );
+}
+async function claimStandalone(ctx, args, findingId) {
+  const briefData = await ctx.client.query(
+    anyApi2.functions.findings.getFindingBrief,
+    { findingId }
+  );
+  if (!briefData) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "Finding not found or you don't have access."
         }
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(
-                {
-                  branch: branchName,
-                  worktreePath,
-                  briefPath: `${worktreePath}/.yapout/brief.md`,
-                  brief: formatBrief(briefData),
-                  pipelineRunId: claim.pipelineRunId
-                },
-                null,
-                2
-              )
-            }
-          ]
-        };
+      ],
+      isError: true
+    };
+  }
+  const finding = briefData.finding;
+  const linearIssueId = briefData.linearIssueId;
+  const defaultBranch = briefData.defaultBranch || "main";
+  const prefix = readBranchPrefix(ctx.cwd);
+  const slug = slugify(finding.title);
+  const branchName = linearIssueId ? `${prefix}/${linearIssueId.toLowerCase()}-${slug}` : `${prefix}/${slug}`;
+  const localClaim = await ctx.client.mutation(
+    anyApi2.functions.findings.claimFindingLocal,
+    { findingId, branchName }
+  );
+  const claim = await ctx.client.mutation(
+    anyApi2.functions.workQueue.claimForImplementation,
+    {
+      projectId: ctx.projectId,
+      workItemId: findingId,
+      workItemKind: "standalone"
+    }
+  );
+  if (linearIssueId && ctx.projectId) {
+    try {
+      await ctx.client.action(
+        anyApi2.functions.linearStatusMutations.moveIssueStatus,
+        {
+          projectId: ctx.projectId,
+          linearIssueId,
+          statusType: "started"
+        }
+      );
+    } catch {
+    }
+  }
+  const brief = formatFindingBrief(briefData);
+  if (args.worktree) {
+    return await setupWorktree(ctx, findingId, branchName, defaultBranch, brief, localClaim.pipelineRunId);
+  }
+  fetchOrigin(ctx.cwd);
+  checkoutNewBranch(branchName, defaultBranch, ctx.cwd);
+  writeBrief(ctx.cwd, brief);
+  reportClaimEvents(ctx, localClaim.pipelineRunId, finding.title, branchName);
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(
+          {
+            kind: "standalone",
+            branch: branchName,
+            briefPath: ".yapout/brief.md",
+            brief,
+            pipelineRunId: localClaim.pipelineRunId,
+            executionPlan: claim.executionPlan
+          },
+          null,
+          2
+        )
       }
-      fetchOrigin(ctx.cwd);
-      checkoutNewBranch(branchName, defaultBranch, ctx.cwd);
-      const yapoutDir = join7(ctx.cwd, ".yapout");
-      if (!existsSync6(yapoutDir)) mkdirSync6(yapoutDir, { recursive: true });
-      const brief = formatBrief(briefData);
-      writeFileSync7(join7(yapoutDir, "brief.md"), brief);
+    ]
+  };
+}
+async function claimBundle(ctx, args, bundleId, bundleData) {
+  const defaultBranch = await getDefaultBranchForProject(ctx);
+  const prefix = readBranchPrefix(ctx.cwd);
+  const firstLinearId = bundleData.findings.find((f) => f.linearIssueId)?.linearIssueId;
+  const slug = slugify(bundleData.title);
+  const branchName = firstLinearId ? `${prefix}/${firstLinearId.toLowerCase()}-${slug}` : `${prefix}/bundle-${slug}`;
+  const primaryFinding = bundleData.findings[0];
+  if (!primaryFinding) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "Bundle has no findings."
+        }
+      ],
+      isError: true
+    };
+  }
+  const localClaim = await ctx.client.mutation(
+    anyApi2.functions.findings.claimFindingLocal,
+    { findingId: primaryFinding._id, branchName }
+  );
+  const claim = await ctx.client.mutation(
+    anyApi2.functions.workQueue.claimForImplementation,
+    {
+      projectId: ctx.projectId,
+      workItemId: bundleId,
+      workItemKind: "bundle"
+    }
+  );
+  for (const f of bundleData.findings) {
+    if (f.linearIssueId && ctx.projectId) {
       try {
-        await ctx.client.mutation(
-          anyApi2.functions.pipelineRuns.reportDaemonEvent,
-          {
-            pipelineRunId: claim.pipelineRunId,
-            event: "daemon_claimed",
-            message: `Claimed finding: ${finding.title}`
-          }
-        );
-        await ctx.client.mutation(
-          anyApi2.functions.pipelineRuns.reportDaemonEvent,
+        await ctx.client.action(
+          anyApi2.functions.linearStatusMutations.moveIssueStatus,
           {
-            pipelineRunId: claim.pipelineRunId,
-            event: "branch_created",
-            message: `Branch: ${branchName}`
+            projectId: ctx.projectId,
+            linearIssueId: f.linearIssueId,
+            statusType: "started"
           }
         );
       } catch {
       }
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(
-              {
-                branch: branchName,
-                briefPath: ".yapout/brief.md",
-                brief,
-                pipelineRunId: claim.pipelineRunId
-              },
-              null,
-              2
-            )
-          }
-        ]
-      };
     }
+  }
+  let projectContext;
+  try {
+    const briefData = await ctx.client.query(
+      anyApi2.functions.findings.getFindingBrief,
+      { findingId: primaryFinding._id }
+    );
+    projectContext = briefData?.projectContext;
+  } catch {
+  }
+  const brief = formatBundleBrief(bundleData, projectContext);
+  if (args.worktree) {
+    return await setupWorktree(ctx, bundleId, branchName, defaultBranch, brief, localClaim.pipelineRunId);
+  }
+  fetchOrigin(ctx.cwd);
+  checkoutNewBranch(branchName, defaultBranch, ctx.cwd);
+  writeBrief(ctx.cwd, brief);
+  reportClaimEvents(ctx, localClaim.pipelineRunId, `Bundle: ${bundleData.title}`, branchName);
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(
+          {
+            kind: "bundle",
+            bundleId,
+            bundleTitle: bundleData.title,
+            findingCount: bundleData.findings.length,
+            branch: branchName,
+            briefPath: ".yapout/brief.md",
+            brief,
+            pipelineRunId: localClaim.pipelineRunId,
+            executionPlan: claim.executionPlan
+          },
+          null,
+          2
+        )
+      }
+    ]
+  };
+}
+async function getDefaultBranchForProject(ctx) {
+  try {
+    const data = await ctx.client.query(
+      anyApi2.functions.projects.getProject,
+      { projectId: ctx.projectId }
+    );
+    return data?.githubDefaultBranch || "main";
+  } catch {
+    return "main";
+  }
+}
+async function setupWorktree(ctx, itemId, branchName, defaultBranch, brief, pipelineRunId) {
+  fetchOrigin(ctx.cwd);
+  const worktreePath = createWorktree(
+    ctx.cwd,
+    itemId,
+    branchName,
+    defaultBranch
   );
+  writeBrief(worktreePath, brief);
+  try {
+    await ctx.client.mutation(
+      anyApi2.functions.pipelineRuns.reportDaemonEvent,
+      {
+        pipelineRunId,
+        event: "worktree_created",
+        message: `Worktree: ${worktreePath}`
+      }
+    );
+  } catch {
+  }
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(
+          {
+            branch: branchName,
+            worktreePath,
+            briefPath: `${worktreePath}/.yapout/brief.md`,
+            brief,
+            pipelineRunId
+          },
+          null,
+          2
+        )
+      }
+    ]
+  };
+}
+function writeBrief(dir, brief) {
+  const yapoutDir = join7(dir, ".yapout");
+  if (!existsSync6(yapoutDir)) mkdirSync6(yapoutDir, { recursive: true });
+  writeFileSync7(join7(yapoutDir, "brief.md"), brief);
+}
+async function reportClaimEvents(ctx, pipelineRunId, title, branchName) {
+  try {
+    await ctx.client.mutation(
+      anyApi2.functions.pipelineRuns.reportDaemonEvent,
+      {
+        pipelineRunId,
+        event: "daemon_claimed",
+        message: `Claimed: ${title}`
+      }
+    );
+    await ctx.client.mutation(
+      anyApi2.functions.pipelineRuns.reportDaemonEvent,
+      {
+        pipelineRunId,
+        event: "branch_created",
+        message: `Branch: ${branchName}`
+      }
+    );
+  } catch {
+  }
 }
 
 // src/mcp/tools/event.ts
@@ -1507,20 +1829,24 @@ async function createPullRequest(title, body, branch, base, repoFullName, cwd) {
 
 // src/mcp/tools/ship.ts
 import { join as join8 } from "path";
-import { existsSync as existsSync7, readFileSync as readFileSync6 } from "fs";
-function buildCommitMessage(message, template, finding) {
+import { existsSync as existsSync7, readFileSync as readFileSync5 } from "fs";
+function buildCommitMessage(message, template, finding, allLinearIds) {
   if (message) return message;
   if (template) {
     return template.replace(/\{\{finding\.type\}\}/g, finding.type).replace(/\{\{finding\.title\}\}/g, finding.title).replace(/\{\{finding\.linearIssueId\}\}/g, finding.linearIssueId ?? "draft").replace(/\{\{finding\.id\}\}/g, finding.id ?? "").replace(/\{\{finding\.priority\}\}/g, finding.priority ?? "medium");
   }
   const prefix = finding.type === "bug" ? "fix" : "feat";
+  if (allLinearIds && allLinearIds.length > 1) {
+    const refs = allLinearIds.join(", ");
+    return `${prefix}: ${finding.title} (${refs})`;
+  }
   const ref = finding.linearIssueId ? ` (${finding.linearIssueId})` : "";
   return `${prefix}(${finding.type}): ${finding.title}${ref}`;
 }
 function registerShipTool(server, ctx) {
   server.tool(
     "yapout_ship",
-    "Commit, push, open a PR, and mark the finding as done. Run yapout_check first if post-flight checks are configured.",
+    "Commit, push, open a PR, and mark the work item as done. Run yapout_check first if post-flight checks are configured.",
     {
       message: z7.string().optional().describe("Custom commit message (overrides template)"),
       skipPr: z7.boolean().optional().describe("Just push, don't open a PR"),
@@ -1550,24 +1876,53 @@ function registerShipTool(server, ctx) {
       let findingTitle = branch;
       let findingType = "feature";
       let findingLinearId;
+      let allLinearIds = [];
+      let isBundle = false;
+      let bundleTitle;
       try {
         const briefPath = join8(gitCwd, ".yapout", "brief.md");
         if (existsSync7(briefPath)) {
-          const brief = readFileSync6(briefPath, "utf-8");
-          const titleMatch = brief.match(/^# (.+)$/m);
-          if (titleMatch) findingTitle = titleMatch[1];
-          const typeMatch = brief.match(/\*\*Type:\*\* (\w+)/);
-          if (typeMatch) findingType = typeMatch[1];
-          const linearMatch = brief.match(/\*\*Linear:\*\* .+\/([A-Z]+-\d+)\//);
-          if (linearMatch) findingLinearId = linearMatch[1];
+          const brief = readFileSync5(briefPath, "utf-8");
+          const bundleMatch = brief.match(/^# Bundle: (.+)$/m);
+          if (bundleMatch) {
+            isBundle = true;
+            bundleTitle = bundleMatch[1];
+            findingTitle = bundleTitle;
+            const linearMatches = brief.matchAll(/\(([A-Z]+-\d+)\)/g);
+            for (const match of linearMatches) {
+              if (!allLinearIds.includes(match[1])) {
+                allLinearIds.push(match[1]);
+              }
+            }
+            if (allLinearIds.length > 0) {
+              findingLinearId = allLinearIds[0];
+            }
+            const typeMatch = brief.match(/\*\*Type:\*\* (\w+)/);
+            if (typeMatch) findingType = typeMatch[1];
+          } else {
+            const titleMatch = brief.match(/^# (.+)$/m);
+            if (titleMatch) findingTitle = titleMatch[1];
+            const typeMatch = brief.match(/\*\*Type:\*\* (\w+)/);
+            if (typeMatch) findingType = typeMatch[1];
+            const linearMatch = brief.match(/\*\*Linear:\*\* .+\/([A-Z]+-\d+)\//);
+            if (linearMatch) {
+              findingLinearId = linearMatch[1];
+              allLinearIds = [findingLinearId];
+            }
+          }
         }
       } catch {
       }
-      const commitMsg = buildCommitMessage(args.message, config.commit_template, {
-        title: findingTitle,
-        type: findingType,
-        linearIssueId: findingLinearId
-      });
+      const commitMsg = buildCommitMessage(
+        args.message,
+        config.commit_template,
+        {
+          title: findingTitle,
+          type: findingType,
+          linearIssueId: findingLinearId
+        },
+        allLinearIds.length > 1 ? allLinearIds : void 0
+      );
       stageAll(gitCwd);
       const sha = commit(commitMsg, gitCwd);
       push(branch, gitCwd);
@@ -1576,6 +1931,11 @@ function registerShipTool(server, ctx) {
         branch,
         pushed: true
       };
+      if (isBundle) {
+        result.isBundle = true;
+        result.bundleTitle = bundleTitle;
+        result.linearIssueIds = allLinearIds;
+      }
       if (!config.ship_requires_checks && config.post_flight.length > 0) {
         if (ctx.lastCheckPassedForRun !== args.pipelineRunId) {
           result.warning = "Shipped without running post-flight checks.";
@@ -1587,11 +1947,25 @@ function registerShipTool(server, ctx) {
         try {
           const repoFullName = getRepoFullName(gitCwd);
           const diffStats = getDiffStats(defaultBranch, branch, gitCwd);
-          const prBody = [
+          const prBodyParts = [
             `## Summary`,
-            "",
-            findingTitle,
-            "",
+            ""
+          ];
+          if (isBundle && bundleTitle) {
+            prBodyParts.push(`**Bundle:** ${bundleTitle}`);
+            prBodyParts.push("");
+            if (allLinearIds.length > 0) {
+              prBodyParts.push("**Linear Issues:**");
+              for (const id of allLinearIds) {
+                prBodyParts.push(`- ${id}`);
+              }
+              prBodyParts.push("");
+            }
+          } else {
+            prBodyParts.push(findingTitle);
+            prBodyParts.push("");
+          }
+          prBodyParts.push(
             `## Changes`,
             "",
             "```",
@@ -1600,7 +1974,8 @@ function registerShipTool(server, ctx) {
             "",
             "---",
             `Implemented via [yapout](https://yapout.dev) daemon`
-          ].join("\n");
+          );
+          const prBody = prBodyParts.join("\n");
           const pr = await createPullRequest(
             findingTitle,
             prBody,
@@ -1650,30 +2025,33 @@ function registerShipTool(server, ctx) {
       } catch (err) {
         result.completionError = err.message;
       }
-      if (findingLinearId && ctx.projectId) {
-        try {
-          await ctx.client.action(
-            anyApi2.functions.linearStatusMutations.moveIssueStatus,
-            {
-              projectId: ctx.projectId,
-              linearIssueId: findingLinearId,
-              statusType: "completed"
-            }
-          );
-        } catch {
-        }
-        if (prUrl) {
+      const linearIdsToUpdate = allLinearIds.length > 0 ? allLinearIds : findingLinearId ? [findingLinearId] : [];
+      for (const linearId of linearIdsToUpdate) {
+        if (ctx.projectId) {
           try {
             await ctx.client.action(
-              anyApi2.functions.linearStatusMutations.addLinearComment,
+              anyApi2.functions.linearStatusMutations.moveIssueStatus,
               {
                 projectId: ctx.projectId,
-                linearIssueId: findingLinearId,
-                body: `PR opened: [#${prNumber}](${prUrl})`
+                linearIssueId: linearId,
+                statusType: "completed"
               }
             );
           } catch {
           }
+          if (prUrl) {
+            try {
+              await ctx.client.action(
+                anyApi2.functions.linearStatusMutations.addLinearComment,
+                {
+                  projectId: ctx.projectId,
+                  linearIssueId: linearId,
+                  body: `PR opened: [#${prNumber}](${prUrl})`
+                }
+              );
+            } catch {
+            }
+          }
         }
       }
       if (args.worktreePath) {
@@ -2093,7 +2471,6 @@ The finding transitions: enriching \u2192 enriched \u2192 ready.`,
       ).optional().describe("Only meaningful Q&A from the conversation \u2014 deviations from expected scope, scoping decisions, etc. Omit if you had no questions."),
       isOversized: z11.boolean().optional().describe("Set to true if this finding is too large for a single PR"),
       suggestedSplit: z11.array(z11.string()).optional().describe("If oversized: suggested sub-finding titles for breaking it down"),
-      level: z11.enum(["project", "issue"]).optional().describe("Override the finding's level if enrichment reveals it should be reclassified"),
       nature: z11.enum(["implementable", "operational", "spike"]).optional().describe("Override the finding's nature if enrichment reveals it should be reclassified"),
       sessionId: z11.string().optional().describe("Bulk enrichment session ID (from yapout_start_enrichment). Updates session stats.")
     },
@@ -2110,7 +2487,6 @@ The finding transitions: enriching \u2192 enriched \u2192 ready.`,
             clarifications: args.clarifications,
             isOversized: args.isOversized,
             suggestedSplit: args.suggestedSplit,
-            level: args.level,
             nature: args.nature
           }
         );
@@ -2370,11 +2746,11 @@ Mark a finding as NOT ENRICHED (isEnriched: false or omitted) when:
 This is a quality gate. Do not inflate your assessment \u2014 unenriched findings get enriched properly later. Falsely marking something as enriched skips that process and produces bad findings.
 
 PRESENTING THE FINAL PICTURE:
-When the conversation feels complete, present a summary grouped by project:
+When the conversation feels complete, present a summary grouped by bundles and standalone issues:
 
 "Here's what I've gathered from our conversation:
 
-**[Project Name]** \u2014 [one-line description]
+**[Bundle Name]** \u2014 [one-line description]
   1. [Child issue] \u2014 enriched \u2713
   2. [Child issue] \u2014 enriched \u2713
   3. [Child issue] \u2014 needs enrichment (we didn't discuss scope)
@@ -2390,7 +2766,7 @@ SUBMITTING:
 On confirmation, call yapout_extract_from_yap with the full data.
 
 For each finding, provide:
-- title, description, sourceQuote, type, priority, confidence, level, nature
+- title, description, sourceQuote, type, priority, confidence, nature
 - isEnriched: your honest assessment (see above)
 
 For ENRICHED findings (isEnriched: true), also include:
@@ -2399,8 +2775,8 @@ For ENRICHED findings (isEnriched: true), also include:
 - implementationBrief: (optional) technical context \u2014 files, approach, edge cases. Only include if you read the codebase during the session. The implementing agent reads the codebase anyway.
 - clarifications: relevant Q&A from the conversation that shaped the finding
 
-For PROJECT-level findings, also include:
-- projectDescription: what this body of work accomplishes
+For findings with CHILDREN (bundles), also include:
+- bundleDescription: what this body of work accomplishes
 - suggestedOrder: implementation sequencing ("Phase 1: A, then Phase 2: B+C")
 - children: array of child issues (each with their own enrichment data)
 
@@ -2408,16 +2784,16 @@ For children with DEPENDENCIES, include:
 - dependsOn: array of sibling indices (0-based) that must complete first
 
 Structure:
-- Projects include children inline \u2014 never create child issues as separate top-level findings
+- Findings with children become bundles \u2014 never create child issues as separate top-level findings
 - Standalone issues go at the top level
 - The hierarchy you produce should be the final structure
 
 Call yapout_extract_from_yap with:
 - sessionTitle: descriptive title for this session
 - sessionTranscript: clean summary of the conversation (meeting-notes style)
-- findings: the array (projects with children, standalone issues)
+- findings: the array (bundles with children, standalone issues)
 
-This creates findings (enriched or draft based on your assessment) and project decomposition \u2014 all in one call. Enriched findings appear in the work queue ready for the user to sync to Linear.
+This creates findings (enriched or draft based on your assessment) and bundles \u2014 all in one call. Enriched findings appear in the work queue ready for the user to sync to Linear.
 
 Only fall back to yapout_submit_yap_session if the session was purely exploratory with no clear actionable findings.
 
@@ -2453,7 +2829,7 @@ var childSchema = z15.object({
   title: z15.string().describe("Child issue title"),
   description: z15.string().describe("What needs to be done and why"),
   sourceQuote: z15.string().describe("Relevant excerpt from the conversation"),
-  type: z15.enum(["feature", "bug", "chore"]).describe("Finding category"),
+  type: z15.enum(["feature", "bug", "chore", "spike"]).describe("Finding category"),
   priority: z15.enum(["urgent", "high", "medium", "low"]).describe("Priority level"),
   confidence: z15.number().min(0).max(1).describe("Confidence this is a clear, actionable finding (0-1)"),
   nature: z15.enum(["implementable", "operational", "spike"]).describe("What kind of work"),
@@ -2480,22 +2856,21 @@ function registerExtractFromYapTool(server, ctx) {
           title: z15.string().describe("Finding title"),
           description: z15.string().describe("What needs to be done and why"),
           sourceQuote: z15.string().describe("Relevant excerpt from the conversation"),
-          type: z15.enum(["feature", "bug", "chore"]).describe("Finding category (do not use spike \u2014 use nature instead)"),
+          type: z15.enum(["feature", "bug", "chore", "spike"]).describe("Finding category (do not use spike \u2014 use nature instead)"),
           priority: z15.enum(["urgent", "high", "medium", "low"]).describe("Priority level"),
           confidence: z15.number().min(0).max(1).describe("Your confidence this is a clear, actionable finding (0-1)"),
-          level: z15.enum(["project", "issue"]).describe("project = body of work with children, issue = single unit"),
           nature: z15.enum(["implementable", "operational", "spike"]).describe("implementable = code changes, operational = manual task, spike = needs scoping"),
           sourceFindingId: z15.string().optional().describe("ID of an existing finding this scopes (e.g., scoping a spike)"),
-          // Issue-level enrichment (when level === "issue")
+          // Enrichment data for standalone findings
           isEnriched: z15.boolean().optional().describe("For standalone issues: was this thoroughly discussed? true = enriched, false = draft"),
-          enrichedDescription: z15.string().optional().describe("Clean description for Linear (standalone issues only, required if isEnriched)"),
-          acceptanceCriteria: z15.array(z15.string()).optional().describe("Testable acceptance criteria (standalone issues only, required if isEnriched)"),
-          implementationBrief: z15.string().optional().describe("Technical context (standalone issues only, optional)"),
-          clarifications: z15.array(clarificationSchema).optional().describe("Relevant Q&A from conversation (standalone issues only)"),
-          // Project-level fields (when level === "project")
-          projectDescription: z15.string().optional().describe("What this body of work accomplishes (projects only)"),
-          suggestedOrder: z15.string().optional().describe("Implementation order: 'Phase 1: A, then Phase 2: B+C' (projects only)"),
-          children: z15.array(childSchema).optional().describe("Child issues for project-level decisions")
+          enrichedDescription: z15.string().optional().describe("Clean description for Linear (required if isEnriched)"),
+          acceptanceCriteria: z15.array(z15.string()).optional().describe("Testable acceptance criteria (required if isEnriched)"),
+          implementationBrief: z15.string().optional().describe("Technical context (optional)"),
+          clarifications: z15.array(clarificationSchema).optional().describe("Relevant Q&A from conversation"),
+          // Bundle fields — when a finding has children, a bundle is created
+          bundleDescription: z15.string().optional().describe("What this body of work accomplishes (only for findings with children)"),
+          suggestedOrder: z15.string().optional().describe("Implementation order: 'Phase 1: A, then Phase 2: B+C' (only for findings with children)"),
+          children: z15.array(childSchema).optional().describe("Child issues \u2014 when present, a bundle is created from this finding")
         })
       ).describe("Findings from the conversation. Projects include children inline.")
     },
@@ -2525,8 +2900,8 @@ function registerExtractFromYapTool(server, ctx) {
         let draftCount = 0;
         let totalFindings = 0;
         for (const item of result.items) {
-          if (item.level === "project") {
-            for (const child of item.children ?? []) {
+          if (item.children && item.children.length > 0) {
+            for (const child of item.children) {
               totalFindings++;
               if (child.findingStatus === "enriched") enrichedCount++;
               else draftCount++;
@@ -2576,35 +2951,36 @@ function registerExtractFromYapTool(server, ctx) {
   );
 }
 
-// src/mcp/tools/save-project-enrichment.ts
+// src/mcp/tools/decompose-finding.ts
 import { z as z16 } from "zod";
-function registerSaveProjectEnrichmentTool(server, ctx) {
+function registerDecomposeFindingTool(server, ctx) {
   server.tool(
-    "yapout_save_project_enrichment",
-    `Save the decomposition of a project-level finding into implementable child issues.
+    "yapout_decompose_finding",
+    `Decompose a finding into a bundle with child issues.
 
-Call this after enriching a finding with level: "project". The agent should have:
+Call this when enrichment reveals a finding is too large for a single PR.
+The agent should have:
 1. Read the codebase extensively
 2. Asked the user scoping questions
 3. Produced a set of child issues with dependencies
 
-This tool creates child findings in yapout, transitions the original
-finding to "decomposed", and returns the child finding IDs for subsequent Linear sync.
+This tool creates a bundle in yapout, assigns child findings to it, and
+archives the original finding. Returns the bundle ID and child finding IDs.
 
 Each child issue's implementation brief must be detailed enough to stand alone as a
 full spec \u2014 schema changes, files to modify, edge cases, and acceptance criteria.`,
     {
-      findingId: z16.string().describe("The project-level finding being decomposed (from yapout_get_unenriched_finding)"),
-      projectDescription: z16.string().describe("Description for the project \u2014 what this body of work accomplishes"),
+      findingId: z16.string().describe("The finding being decomposed (from yapout_get_unenriched_finding)"),
+      bundleDescription: z16.string().describe("Description for the bundle \u2014 what this body of work accomplishes"),
       suggestedOrder: z16.string().describe("Human-readable implementation order (e.g. 'Phase 1: A, then Phase 2: B+C in parallel, then Phase 3: D')"),
-      linearProjectId: z16.string().optional().describe("Existing Linear project ID to associate child issues with. Omit to skip Linear project association \u2014 issues will be synced without a project."),
+      linearProjectId: z16.string().optional().describe("Existing Linear project ID to associate with. Omit to skip Linear project association."),
       issues: z16.array(
         z16.object({
           title: z16.string().describe("Child issue title"),
           description: z16.string().describe("What needs to be done and why"),
           acceptanceCriteria: z16.array(z16.string()).describe("Testable acceptance criteria"),
           implementationBrief: z16.string().describe("Full spec: files to modify, schema changes, edge cases, approach"),
-          type: z16.enum(["feature", "bug", "chore"]).describe("Category of work"),
+          type: z16.enum(["feature", "bug", "chore", "spike"]).describe("Category of work"),
           priority: z16.enum(["urgent", "high", "medium", "low"]).describe("Priority level"),
           dependsOn: z16.array(z16.number()).describe("Indices (0-based) of issues in this array that must be completed first")
         })
@@ -2624,10 +3000,10 @@ full spec \u2014 schema changes, files to modify, edge cases, and acceptance cri
       }
       try {
         const result = await ctx.client.mutation(
-          anyApi2.functions.localPipeline.saveProjectEnrichment,
+          anyApi2.functions.localPipeline.decomposeIntoBundle,
           {
             findingId: args.findingId,
-            projectDescription: args.projectDescription,
+            bundleDescription: args.bundleDescription,
             suggestedOrder: args.suggestedOrder,
             linearProjectId: args.linearProjectId,
             issues: args.issues
@@ -2640,10 +3016,12 @@ full spec \u2014 schema changes, files to modify, edge cases, and acceptance cri
               text: JSON.stringify(
                 {
                   findingId: result.findingId,
-                  status: "decomposed",
+                  bundleId: result.bundleId,
+                  status: "archived",
+                  archivedReason: "decomposed",
                   childFindingIds: result.childFindingIds,
                   suggestedOrder: result.suggestedOrder,
-                  message: `Project decomposed into ${result.childFindingIds.length} child issues. Original finding marked as decomposed. Child findings are in draft status \u2014 enrich and sync each one individually, or approve them for the user to review.`
+                  message: `Finding decomposed into bundle with ${result.childFindingIds.length} child issues. Original finding archived. Child findings are in draft status \u2014 enrich and sync each one individually, or approve them for the user to review.`
                 },
                 null,
                 2
@@ -2656,7 +3034,7 @@ full spec \u2014 schema changes, files to modify, edge cases, and acceptance cri
           content: [
             {
               type: "text",
-              text: `Error saving project enrichment: ${err.message}`
+              text: `Error decomposing finding: ${err.message}`
             }
           ],
           isError: true
@@ -3183,7 +3561,7 @@ async function startMcpServer() {
   registerSubmitYapSessionTool(server, ctx);
   registerStartYapTool(server, ctx);
   registerExtractFromYapTool(server, ctx);
-  registerSaveProjectEnrichmentTool(server, ctx);
+  registerDecomposeFindingTool(server, ctx);
   registerMarkDuplicateTool(server, ctx);
   registerGetLinearProjectsTool(server, ctx);
   registerStartEnrichmentTool(server, ctx);
@@ -3267,7 +3645,7 @@ var cleanCommand = new Command9("clean").description("Remove worktrees for compl
 import { Command as Command10 } from "commander";
 import { resolve as resolve7 } from "path";
 import {
-  readFileSync as readFileSync7,
+  readFileSync as readFileSync6,
   writeFileSync as writeFileSync9,
   existsSync as existsSync10,
   unlinkSync as unlinkSync3
@@ -3883,7 +4261,7 @@ var LOG_FILE = join11(getYapoutDir(), "watch.log");
 var watchCommand = new Command10("watch").description("Watch for work and spawn Claude Code agents").option("--bg", "Run in background (detached)").option("--stop", "Stop the background watcher").option("--status", "Check if watcher is running").option("--force", "Force kill on Ctrl+C (don't wait for agents)").action(async (opts) => {
   if (opts.status) {
     if (existsSync10(PID_FILE)) {
-      const pid = parseInt(readFileSync7(PID_FILE, "utf-8").trim(), 10);
+      const pid = parseInt(readFileSync6(PID_FILE, "utf-8").trim(), 10);
       if (isProcessRunning(pid)) {
         console.log(
           chalk11.green("Watcher is running") + chalk11.dim(` (PID ${pid})`)
@@ -3902,7 +4280,7 @@ var watchCommand = new Command10("watch").description("Watch for work and spawn
       console.log(chalk11.dim("No watcher running"));
       return;
     }
-    const pid = parseInt(readFileSync7(PID_FILE, "utf-8").trim(), 10);
+    const pid = parseInt(readFileSync6(PID_FILE, "utf-8").trim(), 10);
     try {
       process.kill(pid, "SIGTERM");
       console.log(chalk11.green(`Stopped watcher (PID ${pid})`));
@@ -4129,7 +4507,7 @@ Claimed: ${ref} "${ticket.title}"`));
   );
   if (brief) {
     const briefPath = join12(workDir, ".yapout", "brief.md");
-    const briefContent = formatBrief2(ref, ticket, brief);
+    const briefContent = formatBrief(ref, ticket, brief);
     writeFileSync10(briefPath, briefContent);
     console.log(`Brief: ${chalk13.cyan(briefPath)}`);
   }
@@ -4142,7 +4520,7 @@ Claimed: ${ref} "${ticket.title}"`));
   );
   console.log();
 });
-function formatBrief2(ref, ticket, brief) {
+function formatBrief(ref, ticket, brief) {
   const lines = [
     `# ${ref}: ${ticket.title}`,
     "",
@@ -4307,9 +4685,10 @@ function buildPrompt(parsed) {
   switch (parsed.action) {
     case "claim":
       return [
-        `Use yapout to implement ticket "${parsed.ticketId}".`,
-        `Claim it with yapout_claim (use worktree mode), read the brief,`,
-        `implement the changes, run yapout_check, then ship with yapout_ship.`
+        `Use yapout to implement work item "${parsed.ticketId}".`,
+        `Claim it with yapout_claim using workItemId (use worktree mode), read the brief,`,
+        `implement the changes, run yapout_check, then ship with yapout_ship.`,
+        `The ID may be a bundle or standalone finding \u2014 yapout_claim auto-detects.`
       ].join(" ");
     case "enrich":
       return [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yapout",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "yapout CLI — link local repos, authenticate, and manage projects",
   "type": "module",
   "bin": {