yapout 0.3.1 → 0.4.1

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 = (
@@ -291,6 +292,29 @@ def main():
             prompt += f" about {topic}"
         if persona and persona != "tech lead":
             prompt += f" \u2014 be a {persona}"
+    elif action == "compact":
+    elif action == "enrich-bundle":
+        bundle_id = ticket_id
+        prompt = (
+            f'Use yapout to enrich a bundle as a single cohesive unit.\\n'
+            f'\\n'
+            f'1. Call yapout_enrich_bundle with bundleId "{bundle_id}" to claim it and get all findings\\n'
+            f'2. Read the codebase to understand the full scope of the bundle\\n'
+            f'3. Ask me any clarifying questions about the bundle as a whole (not individual findings)\\n'
+            f'4. For each finding, formulate:\\n'
+            f'   - A refined title\\n'
+            f'   - A specific description\\n'
+            f'   - Concrete acceptance criteria\\n'
+            f'   - An implementation brief\\n'
+            f'5. Also formulate bundle-level:\\n'
+            f'   - An overall description of what the bundle delivers\\n'
+            f'   - Combined acceptance criteria\\n'
+            f'   - An architecture/approach brief that covers the full scope\\n'
+            f'6. Call yapout_save_bundle_enrichment with ALL enrichment data at once\\n'
+            f'\\n'
+            f'Treat this as ONE problem, not separate findings. Understand how they relate,\\n'
+            f'identify dependencies, and write briefs that reference each other.'
+        )
     elif action == "compact":
         prompt = "Run yapout_compact to update the project context summary."
     else:
@@ -1063,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) {
@@ -1083,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}`);
+          }
+        }
+      }
+      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.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.";
+      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) }
         ]
       };
     }
@@ -1143,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
       };
     }
   );
@@ -1187,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}`,
@@ -1228,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) => {
@@ -1248,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
@@ -1484,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"),
@@ -1527,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);
@@ -1553,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.";
@@ -1564,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`,
             "",
             "```",
@@ -1577,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,
@@ -1627,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) {
@@ -2055,7 +2456,7 @@ This tool saves the enrichment, then automatically creates the Linear issue with
 - Clarification Q&A as a branded comment (if any)
 - Implementation brief as attachment metadata
 
-The finding transitions: enriching \u2192 enriched \u2192 synced.`,
+The finding transitions: enriching \u2192 enriched \u2192 ready.`,
     {
       findingId: z11.string().describe("The finding ID to enrich (from yapout_get_unenriched_finding)"),
       title: z11.string().describe("Refined finding title \u2014 improve it if the original was vague"),
@@ -2115,7 +2516,7 @@ The finding transitions: enriching \u2192 enriched \u2192 synced.`,
           linearIssueId: finding?.linearIssueId ?? null,
           linearIssueUrl: finding?.linearIssueUrl ?? null,
           compactionHint,
-          message: finding?.linearIssueUrl ? `Finding enriched and synced to Linear: ${finding.linearIssueUrl}` : "Finding enriched and synced to Linear."
+          message: finding?.linearIssueUrl ? `Finding enriched and ready in Linear: ${finding.linearIssueUrl}` : "Finding enriched and ready in Linear."
         };
         if (args.isOversized && args.suggestedSplit?.length) {
           response.warning = `This finding is oversized. Suggested split: ${args.suggestedSplit.join(", ")}`;
@@ -2996,6 +3397,121 @@ When done=true, all findings have been processed.`,
   );
 }
 
+// src/mcp/tools/enrich-bundle.ts
+import { z as z20 } from "zod";
+function registerEnrichBundleTool(server, ctx) {
+  server.tool(
+    "yapout_enrich_bundle",
+    `Claim an entire bundle for enrichment. Returns ALL findings in the bundle at once
+with their relationships, source quotes, and project context.
+
+This is for enriching a bundle as a single cohesive unit \u2014 NOT individual findings.
+The agent should understand the full scope, ask questions about the bundle as a whole,
+then call yapout_save_bundle_enrichment with enrichment data for every finding.
+
+The bundle and all its findings transition to "enriching" status.`,
+    {
+      bundleId: z20.string().describe("The bundle ID to enrich")
+    },
+    async (args) => {
+      try {
+        const result = await ctx.client.mutation(
+          anyApi2.functions.bundles.claimBundleForEnrichment,
+          { bundleId: args.bundleId }
+        );
+        if (!result) {
+          return {
+            content: [{ type: "text", text: "Failed to claim bundle for enrichment." }],
+            isError: true
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2)
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `Error claiming bundle: ${err.message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/mcp/tools/save-bundle-enrichment.ts
+import { z as z21 } from "zod";
+function registerSaveBundleEnrichmentTool(server, ctx) {
+  server.tool(
+    "yapout_save_bundle_enrichment",
+    `Save enrichment for an entire bundle at once. Call this after you've analyzed all
+findings in the bundle as a cohesive unit, read the codebase, and asked any questions.
+
+Provide:
+- Bundle-level: overall description, combined acceptance criteria, implementation brief
+- Per-finding: each finding gets its own refined title, description, acceptance criteria, and brief
+
+The bundle and all findings transition from "enriching" to "enriched".
+Call yapout_sync_bundle_to_linear afterwards to create the Linear project.`,
+    {
+      bundleId: z21.string().describe("The bundle ID"),
+      title: z21.string().optional().describe("Refined bundle title (optional, keeps existing if omitted)"),
+      enrichedDescription: z21.string().describe("Bundle-level description \u2014 the cohesive story of what this bundle delivers"),
+      acceptanceCriteria: z21.array(z21.string()).describe("Bundle-level acceptance criteria"),
+      implementationBrief: z21.string().describe("Bundle-level implementation brief \u2014 overall approach, architecture decisions, key files"),
+      findings: z21.array(z21.object({
+        findingId: z21.string().describe("Finding ID"),
+        title: z21.string().describe("Refined finding title"),
+        enrichedDescription: z21.string().describe("Finding-specific description"),
+        acceptanceCriteria: z21.array(z21.string()).describe("Finding-specific acceptance criteria"),
+        implementationBrief: z21.string().describe("Finding-specific implementation brief")
+      })).describe("Per-finding enrichment data \u2014 one entry per finding in the bundle")
+    },
+    async (args) => {
+      try {
+        await ctx.client.mutation(
+          anyApi2.functions.bundles.saveBundleEnrichment,
+          {
+            bundleId: args.bundleId,
+            title: args.title,
+            enrichedDescription: args.enrichedDescription,
+            acceptanceCriteria: args.acceptanceCriteria,
+            implementationBrief: args.implementationBrief,
+            findings: args.findings.map((f) => ({
+              findingId: f.findingId,
+              title: f.title,
+              enrichedDescription: f.enrichedDescription,
+              acceptanceCriteria: f.acceptanceCriteria,
+              implementationBrief: f.implementationBrief
+            }))
+          }
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                bundleId: args.bundleId,
+                findingsEnriched: args.findings.length,
+                message: `Bundle enriched successfully (${args.findings.length} findings). Call yapout_sync_bundle_to_linear to create the Linear project.`
+              }, null, 2)
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `Error saving bundle enrichment: ${err.message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
 // src/mcp/server.ts
 async function startMcpServer() {
   const cwd = process.cwd();
@@ -3050,6 +3566,8 @@ async function startMcpServer() {
   registerGetLinearProjectsTool(server, ctx);
   registerStartEnrichmentTool(server, ctx);
   registerEnrichNextTool(server, ctx);
+  registerEnrichBundleTool(server, ctx);
+  registerSaveBundleEnrichmentTool(server, ctx);
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }
@@ -3127,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
@@ -3743,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})`)
@@ -3762,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})`));
@@ -3989,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)}`);
   }
@@ -4002,7 +4520,7 @@ Claimed: ${ref} "${ticket.title}"`));
   );
   console.log();
 });
-function formatBrief2(ref, ticket, brief) {
+function formatBrief(ref, ticket, brief) {
   const lines = [
     `# ${ref}: ${ticket.title}`,
     "",
@@ -4141,7 +4659,7 @@ import { Command as Command15 } from "commander";
 import { spawn as spawn2 } from "child_process";
 import { platform as platform2 } from "os";
 import chalk16 from "chalk";
-var VALID_ACTIONS = ["claim", "enrich", "enrich-bulk", "yap", "compact"];
+var VALID_ACTIONS = ["claim", "enrich", "enrich-bulk", "enrich-bundle", "yap", "compact"];
 function parseYapoutUri(raw) {
   const url = new URL(raw);
   const action = url.hostname;
@@ -4151,8 +4669,8 @@ function parseYapoutUri(raw) {
     );
   }
   const ticketId = url.pathname.replace(/^\//, "") || void 0;
-  if ((action === "claim" || action === "enrich") && !ticketId) {
-    throw new Error(`Missing finding ID in URI: ${raw}`);
+  if ((action === "claim" || action === "enrich" || action === "enrich-bundle") && !ticketId) {
+    throw new Error(`Missing ID in URI: ${raw}`);
   }
   return {
     action,
@@ -4167,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 [
@@ -4209,6 +4728,27 @@ function buildPrompt(parsed) {
       }
       return lines.join("\n");
     }
+    case "enrich-bundle":
+      return [
+        `Use yapout to enrich a bundle as a single cohesive unit.`,
+        ``,
+        `1. Call yapout_enrich_bundle with bundleId "${parsed.ticketId}" to claim it and get all findings`,
+        `2. Read the codebase to understand the full scope of the bundle`,
+        `3. Ask me any clarifying questions about the bundle as a whole (not individual findings)`,
+        `4. For each finding, formulate:`,
+        `   - A refined title`,
+        `   - A specific description`,
+        `   - Concrete acceptance criteria`,
+        `   - An implementation brief`,
+        `5. Also formulate bundle-level:`,
+        `   - An overall description of what the bundle delivers`,
+        `   - Combined acceptance criteria`,
+        `   - An architecture/approach brief that covers the full scope`,
+        `6. Call yapout_save_bundle_enrichment with ALL enrichment data at once`,
+        ``,
+        `Treat this as ONE problem, not separate findings. Understand how they relate,`,
+        `identify dependencies, and write briefs that reference each other.`
+      ].join("\n");
     case "yap": {
       const parts = ["Let's have a yap session"];
       if (parsed.topic) parts[0] += ` about ${parsed.topic}`;

package/package.json

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