@codazen/harmonica-mcp 0.27.0 → 0.28.0

package/dist/index.js

@@ -21518,63 +21518,6 @@ Poll progress with: get_task_status({ taskId: "${task.taskId}" })`
 
 // ../../libs/harmonica-services/src/mcp/tools/beat-composer-tools.ts
 function registerBeatComposerTools(server, ctx, client) {
-  server.tool(
-    "compose_revisions",
-    "Compose delivery Revisions from a Beat's Coda (description) \u2014 creates concept-status Revisions for progressive delivery. IMPORTANT: If the Beat already has active revisions, this returns the existing ones instead of creating duplicates. Use list_revisions first to check current state. Use transition_revision to move revisions forward.",
-    {
-      beatId: external_exports.string().describe("The beat ID"),
-      drafts: external_exports.array(external_exports.object({
-        title: external_exports.string().describe("Title for this revision"),
-        description: external_exports.string().describe("What this revision delivers"),
-        changeSummary: external_exports.string().describe("Brief summary of the change"),
-        tags: external_exports.array(external_exports.string()).optional().describe("Tags for categorization"),
-        priority: external_exports.coerce.number().optional().describe("Priority (lower = higher priority)"),
-        estimatedEffort: external_exports.string().optional().describe('Estimated effort (e.g., "S", "M", "L")')
-      })).min(1).describe("Revision drafts to scaffold"),
-      force: external_exports.boolean().optional().describe("Bypass idempotency guard \u2014 create new revisions even if active ones exist. Use when intentionally adding revisions alongside existing ones.")
-    },
-    async ({ beatId, drafts, force }) => {
-      try {
-        console.error("[MCP:ScaffoldRevisions] beatId=%s draftCount=%d actor=%s force=%s", beatId, drafts.length, ctx.user.userId, force ?? false);
-        await assertBeatInOrg(client, beatId, ctx.orgId);
-        const result = await client.composeRevisions(beatId, drafts, ctx.user.userId, { force });
-        const { revisions, alreadyExisted } = result;
-        if (alreadyExisted) {
-          console.error("[MCP:ScaffoldRevisions] returning %d existing revisions beatId=%s", revisions.length, beatId);
-          const lines2 = [
-            `# Beat ${beatId} already has ${revisions.length} active Revision(s) \u2014 no new ones created`,
-            "",
-            "Use update_revision or transition_revision to modify existing revisions, or archive/reject them first if you need to start fresh.",
-            ""
-          ];
-          for (const r of revisions) {
-            lines2.push(`## ${r.revisionId} \u2014 ${r.title} [${r.status}]`);
-            lines2.push(`- **Description:** ${r.description}`);
-            lines2.push("");
-          }
-          return { content: [{ type: "text", text: lines2.join("\n") }] };
-        }
-        console.error(
-          "[MCP:ScaffoldRevisions] created %d revisions beatId=%s ids=%s",
-          revisions.length,
-          beatId,
-          revisions.map((r) => r.revisionId).join(",")
-        );
-        const lines = [`# Scaffolded ${revisions.length} Revisions for ${beatId}`, ""];
-        for (const r of revisions) {
-          lines.push(`## ${r.revisionId} \u2014 ${r.title} [${r.status}]`);
-          lines.push(`- **Description:** ${r.description}`);
-          lines.push(`- **Change:** ${r.changeSummary}`);
-          lines.push("");
-        }
-        return { content: [{ type: "text", text: lines.join("\n") }] };
-      } catch (err) {
-        console.error("[MCP:ScaffoldRevisions] beatId=%s error=%s", beatId, err instanceof Error ? err.message : String(err));
-        const message = err instanceof Error ? err.message : String(err);
-        return { content: [{ type: "text", text: `Failed to scaffold revisions: ${message}` }], isError: true };
-      }
-    }
-  );
   server.tool(
     "record_beat_merge",
     "Record that Beats were merged \u2014 the surviving Beat absorbs others. Creates an Activity record for audit trail.",
@@ -22446,9 +22389,24 @@ function registerBeatTools(server, ctx, client) {
           reason: `Beat "${title}" created via MCP`,
           actorId: ctx.user.email
         });
+        let similarityWarning = "";
+        try {
+          const similar = await client.findSimilarBeats(beat.beatId, projectId, { threshold: 0.7, limit: 5 });
+          if (similar.length > 0) {
+            const rows = similar.map((r) => `- **${r.entityId}** (score: ${r.score.toFixed(2)}): ${r.snippet.replace(/[\n\r]/g, " ")}`).join("\n");
+            similarityWarning = `
+
+---
+
+\u26A0 **Similar Beats detected** \u2014 consider adding a Beat Version to an existing Beat instead of creating a new one:
+
+${rows}`;
+          }
+        } catch {
+        }
         return { content: [{ type: "text", text: `Beat created.
 
-${formatBeatDetail(beat)}` }] };
+${formatBeatDetail(beat)}${similarityWarning}` }] };
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         return { content: [{ type: "text", text: `Failed to create beat: ${message}` }], isError: true };
@@ -22604,6 +22562,26 @@ var LIFECYCLE_STATES = [
 ];
 var PR_LIFECYCLE_STATES = ["draft", "open"];
 
+// ../../libs/harmonica-services/src/mcp/errors.ts
+var BeatQualityGateError = class extends Error {
+  code = "beat_quality_gate_failed";
+  failure;
+  constructor(failure) {
+    super(failure.message);
+    this.failure = failure;
+  }
+};
+var PlanVersionsIdempotencyError = class extends Error {
+  code = "plan_versions_already_exist";
+  existingBeatVersionIds;
+  constructor(existingBeatVersionIds) {
+    super(
+      `Beat already has ${existingBeatVersionIds.length} planned Beat Version(s). Pass force=true to plan again.`
+    );
+    this.existingBeatVersionIds = existingBeatVersionIds;
+  }
+};
+
 // ../../libs/harmonica-services/src/mcp/tools/beat-version-tools.ts
 function registerBeatVersionTools(server, ctx, client) {
   server.tool(
@@ -22774,6 +22752,61 @@ function registerBeatVersionTools(server, ctx, client) {
       }
     }
   );
+  server.tool(
+    "plan_beat_versions",
+    "Agent-decompose a composed Beat into 2-5 planning-state Beat Versions on the path to the Coda. Uses the Beat's Coda, project strategy, sibling Beats, Notes, and codebase grep as context. Requires a recent passing beat_quality check (run check_beat_quality first if needed). Idempotent: refuses when planned BVs already exist on the Beat unless force=true is set.",
+    {
+      beatId: external_exports.string().describe("The Beat ID to decompose (must have a Coda and a passing beat_quality check)"),
+      force: external_exports.boolean().optional().describe("Bypass the idempotency guard and plan additional Beat Versions even when prior planned BVs are still active")
+    },
+    async ({ beatId, force }) => {
+      try {
+        await assertBeatInOrg(client, beatId, ctx.orgId);
+        const actorId = ctx.user.email ?? ctx.user.userId;
+        const beatVersions = await client.planBeatVersions(beatId, actorId, { force });
+        const lines = [
+          `Planned ${beatVersions.length} Beat Version${beatVersions.length === 1 ? "" : "s"} for ${beatId}:`,
+          ""
+        ];
+        for (const bv of beatVersions) {
+          lines.push(`- **${bv.beatVersionId}** v${bv.versionNumber} [${bv.status}]: ${bv.title}`);
+          if (bv.changeSummary) lines.push(`  Change: ${bv.changeSummary}`);
+        }
+        lines.push("", "Run check_plan_quality on each Beat Version before transitioning to building.");
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      } catch (err) {
+        if (err instanceof BeatQualityGateError) {
+          const remedy = err.failure.remedy ? `
+
+**Remedy:** ${err.failure.remedy}` : "";
+          return {
+            content: [{
+              type: "text",
+              text: `Beat Quality gate failed (${err.failure.reason}): ${err.failure.message}${remedy}`
+            }],
+            isError: true
+          };
+        }
+        if (err instanceof PlanVersionsIdempotencyError) {
+          return {
+            content: [{
+              type: "text",
+              text: [
+                `${err.message}`,
+                "",
+                `Existing planned Beat Versions: ${err.existingBeatVersionIds.join(", ")}`,
+                "",
+                "Pass `force: true` if you intentionally want to plan additional Beat Versions on top of the existing ones."
+              ].join("\n")
+            }],
+            isError: true
+          };
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Failed to plan Beat Versions: ${message}` }], isError: true };
+      }
+    }
+  );
   server.tool(
     "transition_beat_version",
     "Transition a Beat Version to a new lifecycle state. The planning \u2192 building transition requires a passing plan_quality check (score \u2265 3, not stale). Use skip_quality_check only for reconciling already-shipped work.",
@@ -22825,7 +22858,8 @@ var CHECK_MAX_SCORES = {
   beat_quality: 5,
   plan_quality: 5,
   build_quality: 5,
-  pii_scan: 100
+  pii_scan: 100,
+  portfolio_coherence: 5
 };
 
 // ../../libs/harmonica-services/src/mcp/tools/check-tools.ts
@@ -22856,7 +22890,7 @@ function registerCheckTools(server, ctx, client) {
       projectId: external_exports.string().describe("The project ID"),
       beatId: external_exports.string().optional().describe("List checks for this specific beat"),
       revisionId: external_exports.string().optional().describe("List checks for this specific revision"),
-      checkType: external_exports.enum(["beat_quality", "plan_quality", "build_quality", "pii_scan"]).optional().describe("Filter by check type")
+      checkType: external_exports.enum(["beat_quality", "plan_quality", "build_quality", "pii_scan", "portfolio_coherence"]).optional().describe("Filter by check type")
     },
     async ({ projectId, beatId, revisionId, checkType }) => {
       try {
@@ -22869,7 +22903,8 @@ function registerCheckTools(server, ctx, client) {
           checks = await client.listBeatChecks(beatId, projectId, checkType);
           scope = `beat ${beatId}`;
         } else {
-          checks = await client.listProjectChecks(projectId, checkType);
+          const result = await client.listProjectChecks(projectId, checkType, { limit: 200 });
+          checks = result.checks;
           scope = `project ${projectId}`;
         }
         if (checks.length === 0) {
@@ -22918,7 +22953,8 @@ var CHECK_TYPE_DISPLAY = {
   beat_quality: "Quality",
   plan_quality: "Plan Quality",
   build_quality: "Build Quality",
-  pii_scan: "PII Scan"
+  pii_scan: "PII Scan",
+  portfolio_coherence: "Portfolio Coherence"
 };
 function formatCheck(a) {
   const typeLabel = CHECK_TYPE_DISPLAY[a.checkType] ?? a.checkType;
@@ -24582,6 +24618,253 @@ Use get_task_status with taskId="${task.taskId}" to poll for results, or list_ch
   );
 }
 
+// ../../libs/harmonica-services/src/mcp/tools/portfolio-coherence-tools.ts
+var POLL_INTERVAL_MS3 = 4e3;
+var POLL_TIMEOUT_MS3 = 18e4;
+var POLL_MAX_CONSECUTIVE_ERRORS3 = 3;
+async function pollForCheck3(client, taskId) {
+  const deadline = Date.now() + POLL_TIMEOUT_MS3;
+  let consecutiveErrors = 0;
+  while (Date.now() < deadline) {
+    const [task, err] = await client.getTask(taskId).then(
+      (t) => [t, null],
+      (e) => [null, e]
+    );
+    if (err) {
+      consecutiveErrors++;
+      if (consecutiveErrors >= POLL_MAX_CONSECUTIVE_ERRORS3) {
+        throw new Error(`getTask failed ${consecutiveErrors} times: ${err instanceof Error ? err.message : String(err)}`);
+      }
+      await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS3));
+      continue;
+    }
+    consecutiveErrors = 0;
+    if (!task) throw new Error(`Task ${taskId} not found`);
+    if (task.status === "completed") {
+      if (!task.result) throw new Error(`Task ${taskId} completed with no result`);
+      return task.result;
+    }
+    if (task.status === "failed") throw new Error(`Portfolio coherence check failed: ${task.error ?? "unknown error"}`);
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS3));
+  }
+  throw new Error(`Portfolio coherence check timed out after ${POLL_TIMEOUT_MS3 / 1e3}s`);
+}
+function formatReport(check2) {
+  const bar = (score, max) => "\u2588".repeat(score) + "\u2591".repeat(max - score);
+  const dims = check2.dimensions.map(
+    (d) => `**${d.label}** ${bar(d.score, d.maxScore)} ${d.score}/${d.maxScore}
+${d.rationale}${d.suggestions?.length ? `
+\u2022 ${d.suggestions.join("\n\u2022 ")}` : ""}`
+  ).join("\n\n");
+  const snapshot = check2.targetSnapshot;
+  const totalBeats = snapshot?.totalBeats;
+  const mergeCandidates = snapshot?.mergeCandidateGroups;
+  const parts = [
+    `## Portfolio Coherence \u2014 ${check2.targetId}`,
+    `**Overall Score:** ${check2.overallScore}/5${totalBeats !== void 0 ? ` | **Beats analyzed:** ${totalBeats}` : ""}`,
+    `**Summary:** ${check2.summary}`,
+    check2.topSuggestion ? `**Top Suggestion:** ${check2.topSuggestion}` : "",
+    "",
+    dims
+  ].filter(Boolean);
+  if (mergeCandidates?.length) {
+    const groupLines = mergeCandidates.map((g, i) => `${i + 1}. [${(g.beatIds ?? []).join(", ")}] \u2014 ${Math.round((g.avgSimilarity ?? 0) * 100)}% similarity`).join("\n");
+    parts.push(`
+## Merge Candidate Groups (${mergeCandidates.length})
+${groupLines}`);
+  }
+  return parts.join("\n");
+}
+function formatConsolidationPreview(primaryId, primary, duplicates, rationale) {
+  const archiveLines = duplicates.map((d) => `- \`${d.beat.beatId}\` \u2014 "${d.beat.title}" [${d.beat.beatStatus ?? "composing"}]`).join("\n");
+  const inflightBvs = duplicates.flatMap((d) => d.inflightBvs);
+  const bvWarning = inflightBvs.length > 0 ? [
+    "",
+    `**\u26A0 In-flight Beat Versions (reassign manually after merge):**`,
+    ...inflightBvs.map((bv) => `- \`${bv.beatVersionId}\` \u2014 "${bv.title}" [${bv.status}]`)
+  ].join("\n") : "";
+  return [
+    `## Consolidation Preview \u2014 Dry Run`,
+    "",
+    `**Primary (survives):** \`${primaryId}\` \u2014 "${primary.title}" [${primary.beatStatus ?? "composing"}]`,
+    "",
+    `**To archive (${duplicates.length}):**`,
+    archiveLines,
+    "",
+    `**Rationale:** ${rationale}`,
+    ...bvWarning ? [bvWarning] : [],
+    "",
+    "---",
+    "Re-call `consolidate_beats` with `confirm: true` to execute this merge."
+  ].join("\n");
+}
+function formatConsolidationResult(primaryId, primary, archivedBeatIds, notesReassigned, inflightBvs) {
+  const bvSection = inflightBvs.length > 0 ? [
+    "",
+    `**In-flight Beat Versions \u2014 reassign manually:**`,
+    ...inflightBvs.map(
+      (bv) => `- \`${bv.beatVersionId}\` \u2014 "${bv.title}" [${bv.status}] \u2192 use \`update_beat_version\` to move to \`${primaryId}\``
+    )
+  ].join("\n") : "";
+  return [
+    `## Merge Complete`,
+    "",
+    `**Primary:** \`${primaryId}\` \u2014 "${primary.title}"`,
+    `**Archived:** ${archivedBeatIds.length} Beat${archivedBeatIds.length !== 1 ? "s" : ""}${archivedBeatIds.length > 0 ? ` \u2014 [${archivedBeatIds.join(", ")}]` : ""}`,
+    `**Notes reassigned:** ${notesReassigned}`,
+    ...bvSection ? [bvSection] : [],
+    "",
+    archivedBeatIds.length > 0 ? "Merge event recorded. Run `check_portfolio_coherence` to verify the cluster is resolved." : "\u26A0 No beats were archived \u2014 check logs for archive failures. Re-run after resolving."
+  ].join("\n");
+}
+function registerPortfolioCoherenceTools(server, ctx, client) {
+  server.tool(
+    "check_portfolio_coherence",
+    "Run a portfolio coherence check on a project. Clusters Beats by semantic similarity to surface fragmentation (merge candidates) and checks what fraction of Beats have a VP-readable buyer abstraction score. By default returns a taskId immediately \u2014 set wait=true to block and receive the full report inline.",
+    {
+      projectId: external_exports.string().min(1).describe("The project ID"),
+      wait: external_exports.boolean().optional().describe("Block until the check completes and return the report inline. Default: false.")
+    },
+    async ({ projectId, wait }) => {
+      try {
+        await assertProjectInOrg(client, projectId, ctx.orgId);
+        const { taskId } = await client.runCheck(projectId, "portfolio_coherence", projectId);
+        if (!wait) {
+          return {
+            content: [{
+              type: "text",
+              text: [
+                `Portfolio coherence check enqueued for ${projectId}.`,
+                `Task ID: ${taskId}`,
+                "",
+                `Use get_task_status with taskId="${taskId}" to poll, or list_checks with projectId="${projectId}" and checkType="portfolio_coherence" to view results.`
+              ].join("\n")
+            }]
+          };
+        }
+        const check2 = await pollForCheck3(client, taskId);
+        return { content: [{ type: "text", text: formatReport(check2) }] };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Portfolio coherence check failed: ${message}` }], isError: true };
+      }
+    }
+  );
+  server.tool(
+    "consolidate_beats",
+    "Consolidate a fragmented Beat cluster \u2014 identified by check_portfolio_coherence \u2014 into a single VP-level capability. By default (confirm omitted or false) returns a dry-run preview: surviving Beat, Beats to archive, Notes to reassign, and any in-flight Beat Versions. Set confirm=true to execute the merge.",
+    {
+      projectId: external_exports.string().min(1).describe("The project ID \u2014 all beatIds must belong to this project"),
+      beatIds: external_exports.array(external_exports.string().min(1)).min(2).max(50).describe("All Beat IDs in the cluster (including the one that will survive)"),
+      primaryBeatId: external_exports.string().min(1).optional().describe("Beat ID that survives \u2014 defaults to beatIds[0] if omitted"),
+      rationale: external_exports.string().max(2e3).optional().describe("Why these Beats are being merged \u2014 auto-generated if omitted"),
+      confirm: external_exports.boolean().optional().describe("false/omitted = preview; true = execute the merge")
+    },
+    async ({ projectId, beatIds, primaryBeatId, rationale, confirm }) => {
+      let archivedBeatIds = [];
+      let totalNotesReassigned = 0;
+      try {
+        await assertProjectInOrg(client, projectId, ctx.orgId);
+        const uniqueBeatIds = [...new Set(beatIds)];
+        const resolvedPrimaryId = primaryBeatId ?? uniqueBeatIds[0];
+        if (!uniqueBeatIds.includes(resolvedPrimaryId)) {
+          return {
+            content: [{ type: "text", text: `primaryBeatId "${resolvedPrimaryId}" is not in beatIds \u2014 include it in the cluster or omit to use beatIds[0].` }],
+            isError: true
+          };
+        }
+        const duplicateBeatIds = uniqueBeatIds.filter((id) => id !== resolvedPrimaryId);
+        if (duplicateBeatIds.length === 0) {
+          return {
+            content: [{ type: "text", text: `No duplicates \u2014 all beatIds resolve to "${resolvedPrimaryId}" after deduplication. Include at least one distinct duplicate Beat ID.` }],
+            isError: true
+          };
+        }
+        const allProjectBeats = await client.listProjectBeats(projectId);
+        const beatMap = new Map(allProjectBeats.map((b) => [b.beatId, b]));
+        const primaryBeat = beatMap.get(resolvedPrimaryId);
+        if (!primaryBeat) {
+          return { content: [{ type: "text", text: `Primary Beat "${resolvedPrimaryId}" not found in project "${projectId}".` }], isError: true };
+        }
+        const missingIds = duplicateBeatIds.filter((id) => !beatMap.has(id));
+        if (missingIds.length > 0) {
+          return { content: [{ type: "text", text: `Beat(s) not found in project "${projectId}": ${missingIds.join(", ")}` }], isError: true };
+        }
+        const dupBvResults = await Promise.allSettled(
+          duplicateBeatIds.map(
+            (id) => client.listBeatVersions(projectId, { beatId: id, includeTerminal: false })
+          )
+        );
+        const bvRejected = dupBvResults.filter((r) => r.status === "rejected");
+        if (bvRejected.length > 0) {
+          console.error("[consolidate_beats] listBeatVersions partial failure:", bvRejected.map((r) => r.reason instanceof Error ? r.reason.message : r.reason));
+        }
+        const duplicates = duplicateBeatIds.map((id, i) => ({
+          beat: beatMap.get(id),
+          inflightBvs: dupBvResults[i]?.status === "fulfilled" ? dupBvResults[i].value : []
+        }));
+        const resolvedRationale = rationale ?? `Merge ${duplicateBeatIds.length} overlapping Beat${duplicateBeatIds.length !== 1 ? "s" : ""} into "${primaryBeat.title}" \u2014 consolidating duplicate value proposition.`;
+        if (!confirm) {
+          return { content: [{ type: "text", text: formatConsolidationPreview(resolvedPrimaryId, primaryBeat, duplicates, resolvedRationale) }] };
+        }
+        for (const { beat } of duplicates) {
+          const archiveResult = await client.updateBeatStatus(beat.beatId, "archived", {
+            actor: { type: "human", id: ctx.user.userId, name: ctx.user.name, email: ctx.user.email },
+            reason: `Merged into ${resolvedPrimaryId}: ${resolvedRationale}`
+          });
+          if (!archiveResult.success) {
+            console.error("[consolidate_beats] archive failed for %s: %s", beat.beatId, archiveResult.error?.message ?? "unknown");
+            continue;
+          }
+          archivedBeatIds.push(beat.beatId);
+          try {
+            const notes = await client.listBeatNotes(beat.beatId);
+            for (const note of notes) {
+              try {
+                const reassigned = await client.reassignNote(note.noteId, resolvedPrimaryId, resolvedRationale, ctx.user.userId);
+                if (reassigned !== void 0) {
+                  totalNotesReassigned++;
+                } else {
+                  console.error("[consolidate_beats] reassignNote returned undefined for %s", note.noteId);
+                }
+              } catch (err) {
+                console.error("[consolidate_beats] note reassign failed %s: %s", note.noteId, err instanceof Error ? err.message : err);
+              }
+            }
+          } catch (err) {
+            console.error("[consolidate_beats] listBeatNotes failed for %s: %s", beat.beatId, err instanceof Error ? err.message : err);
+          }
+        }
+        if (archivedBeatIds.length > 0) {
+          await client.recordMergeEvent(resolvedPrimaryId, archivedBeatIds, resolvedRationale, ctx.user.userId);
+        }
+        const inflightBvs = duplicates.flatMap((d) => d.inflightBvs);
+        return { content: [{ type: "text", text: formatConsolidationResult(resolvedPrimaryId, primaryBeat, archivedBeatIds, totalNotesReassigned, inflightBvs) }] };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (archivedBeatIds.length > 0) {
+          return {
+            content: [{
+              type: "text",
+              text: [
+                `## Merge Partially Complete`,
+                "",
+                `**Archived:** ${archivedBeatIds.length} Beat${archivedBeatIds.length !== 1 ? "s" : ""} \u2014 [${archivedBeatIds.join(", ")}]`,
+                `**Notes reassigned:** ${totalNotesReassigned}`,
+                "",
+                `\u26A0 Merge interrupted before completion: ${message}`,
+                "Run `check_portfolio_coherence` to verify current state."
+              ].join("\n")
+            }],
+            isError: true
+          };
+        }
+        return { content: [{ type: "text", text: `consolidate_beats failed: ${message}` }], isError: true };
+      }
+    }
+  );
+}
+
 // ../../libs/harmonica-services/src/mcp/tools/project-lifecycle-tools.ts
 function registerProjectLifecycleTools(server, ctx, client) {
   server.tool(
@@ -25655,7 +25938,7 @@ ${JSON.stringify(task.result, null, 2)}
   );
   server.tool(
     "draft_coda",
-    "Generate and apply a Coda (description) for a Beat that has a title but no description. Uses project context, sibling Beats, related Notes, and codebase grep to write a resolved expression of the capability. The Coda is applied directly to the Beat, making it eligible for compose_beat. An activity is logged so the Beat owner can review and edit. Returns a task ID \u2014 use get_task_status to track progress.",
+    "Generate and apply a Coda (description) for a Beat that has a title but no description. Uses project context, sibling Beats, related Notes, and codebase grep to write a resolved expression of the capability. The Coda is applied directly to the Beat, making it eligible for plan_beat_versions once a beat_quality check passes. An activity is logged so the Beat owner can review and edit. Returns a task ID \u2014 use get_task_status to track progress.",
     {
       projectId: external_exports.string().describe("The project ID"),
       beatId: external_exports.string().describe("The beat ID (must have a title but no description)")
@@ -25756,107 +26039,109 @@ ${JSON.stringify(task.result, null, 2)}
     }
   );
   server.tool(
-    "validate_work_items",
-    "Validate active workItem Notes against the codebase. Checks if work items are already implemented (resolved), no longer relevant (dismissed), or still needed (active). Active items get a solution plan for the implementation agent. Returns a task ID \u2014 use get_task_status to track progress.",
+    "implement_revision",
+    "Trigger an agent session to implement a Revision. The agent reads the Revision spec and beat-level Notes, writes code, commits, pushes a branch named agent/rev-{id}-{title}, and creates a draft PR with the Revision ID pre-populated in the PR body. Returns a task ID \u2014 use get_task_status to track progress. Requires agentCapabilities.implementation enabled on the project.",
     {
-      projectId: external_exports.string().describe("The project ID"),
-      noteIds: external_exports.array(external_exports.string()).optional().describe("Specific note IDs to validate. If omitted, validates all active work items.")
+      revisionId: external_exports.string().min(1).describe("The Revision ID to implement (e.g., rev-abc123)"),
+      projectId: external_exports.string().min(1).describe("The project ID")
     },
-    async ({ projectId, noteIds }) => {
+    async ({ revisionId, projectId }) => {
       try {
         await assertProjectInOrg(client, projectId, ctx.orgId);
-        const task = await client.validateWorkItems(projectId, noteIds);
+        const task = await client.implementRevision(revisionId, projectId, {
+          name: ctx.user.name,
+          email: ctx.user.email
+        });
         return {
           content: [{
             type: "text",
             text: [
-              "Work item validation queued.",
+              "Revision implementation session queued.",
               "",
-              `**Project:** ${projectId}`,
-              `**Scope:** ${noteIds ? `${noteIds.length} specific items` : "All active work items"}`,
+              `**Revision:** ${revisionId}`,
               `**Task ID:** ${task.taskId}`,
               `**Status:** ${task.status}`,
               "",
-              "The validator will grep the codebase for evidence, then classify each item.",
-              "Use `get_task_status` with the task ID to check progress."
+              "The agent will read the Revision spec and beat-level Notes, implement the code, and create a draft PR.",
+              "Use `get_task_status` with the task ID to check progress and see the result (branch, PR URL, tool count, duration)."
             ].join("\n")
           }]
         };
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return { content: [{ type: "text", text: `Failed to start validation: ${message}` }], isError: true };
+        return { content: [{ type: "text", text: `Failed to start revision implementation: ${message}` }], isError: true };
       }
     }
   );
   server.tool(
-    "plan_revision_batch",
-    "Autonomously generate work items for planning Revisions. If revisionIds are omitted, discovers all planning Revisions with no scoped work items and plans them all. Uses codebase-aware agent sessions when available, LLM-only fallback otherwise. Returns a task ID \u2014 use get_task_status to track progress.",
+    "validate_work_items",
+    "Validate active workItem Notes against the codebase. Checks if work items are already implemented (resolved), no longer relevant (dismissed), or still needed (active). Active items get a solution plan for the implementation agent. Returns a task ID \u2014 use get_task_status to track progress.",
     {
       projectId: external_exports.string().describe("The project ID"),
-      revisionIds: external_exports.array(external_exports.string()).optional().describe("Specific revision IDs to plan. If omitted, auto-discovers all unplanned planning revisions.")
+      noteIds: external_exports.array(external_exports.string()).optional().describe("Specific note IDs to validate. If omitted, validates all active work items.")
     },
-    async ({ projectId, revisionIds }) => {
+    async ({ projectId, noteIds }) => {
       try {
         await assertProjectInOrg(client, projectId, ctx.orgId);
-        const task = await client.planRevisionBatch(projectId, revisionIds);
+        const task = await client.validateWorkItems(projectId, noteIds);
         return {
           content: [{
             type: "text",
             text: [
-              "Revision batch planning queued.",
+              "Work item validation queued.",
               "",
               `**Project:** ${projectId}`,
-              `**Scope:** ${revisionIds ? `${revisionIds.length} specific revision(s)` : "All unplanned planning revisions"}`,
+              `**Scope:** ${noteIds ? `${noteIds.length} specific items` : "All active work items"}`,
               `**Task ID:** ${task.taskId}`,
               `**Status:** ${task.status}`,
               "",
-              "The agent will generate work items for each revision. Revisions stay in planning \u2014 review work items before advancing to building.",
+              "The validator will grep the codebase for evidence, then classify each item.",
               "Use `get_task_status` with the task ID to check progress."
             ].join("\n")
           }]
         };
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return { content: [{ type: "text", text: `Failed to start revision batch planning: ${message}` }], isError: true };
+        return { content: [{ type: "text", text: `Failed to start validation: ${message}` }], isError: true };
       }
     }
   );
   server.tool(
-    "compose_beat",
-    "Autonomously advance a Beat from composing to composed. Reads the Beat's Coda, project strategy, sibling Beats, existing Notes, and greps the codebase for context \u2014 then enriches the Beat description (acceptance criteria, scope, success criteria) and scaffolds delivery Revisions. Returns a task ID \u2014 use get_task_status to track progress.",
+    "plan_revision_batch",
+    "Autonomously generate work items for planning Revisions. If revisionIds are omitted, discovers all planning Revisions with no scoped work items and plans them all. Uses codebase-aware agent sessions when available, LLM-only fallback otherwise. Returns a task ID \u2014 use get_task_status to track progress.",
     {
       projectId: external_exports.string().describe("The project ID"),
-      beatId: external_exports.string().describe("The beat ID to compose (must be in composing status with a Coda set)")
+      revisionIds: external_exports.array(external_exports.string()).optional().describe("Specific revision IDs to plan. If omitted, auto-discovers all unplanned planning revisions.")
     },
-    async ({ projectId, beatId }) => {
+    async ({ projectId, revisionIds }) => {
       try {
         await assertProjectInOrg(client, projectId, ctx.orgId);
-        const task = await client.composeBeat(projectId, beatId);
+        const task = await client.planRevisionBatch(projectId, revisionIds);
         return {
           content: [{
             type: "text",
             text: [
-              "Beat composition session queued.",
+              "Revision batch planning queued.",
               "",
-              `**Beat:** ${beatId}`,
               `**Project:** ${projectId}`,
+              `**Scope:** ${revisionIds ? `${revisionIds.length} specific revision(s)` : "All unplanned planning revisions"}`,
               `**Task ID:** ${task.taskId}`,
               `**Status:** ${task.status}`,
               "",
-              "The agent will gather context, enrich the Beat description, and scaffold delivery Revisions.",
-              "Use `get_task_status` with the task ID to check progress and see the result."
+              "The agent will generate work items for each revision. Revisions stay in planning \u2014 review work items before advancing to building.",
+              "Use `get_task_status` with the task ID to check progress."
             ].join("\n")
           }]
         };
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return { content: [{ type: "text", text: `Failed to start beat composition: ${message}` }], isError: true };
+        return { content: [{ type: "text", text: `Failed to start revision batch planning: ${message}` }], isError: true };
       }
     }
   );
   server.tool(
     "run_triage",
-    "Run the autonomous triage loop for a project. Analyzes next actions, validates work items against the codebase, auto-executes safe actions (draft_coda, compose_beat, plan_revision_batch, validate_work_items), and escalates items that need human judgment. Requires agentCapabilities.triage enabled on the project. Returns a task ID \u2014 use get_task_status to track progress.",
+    "Run the autonomous triage loop for a project. Analyzes next actions, validates work items against the codebase, auto-executes safe actions (draft_coda, plan_revision_batch, validate_work_items), and escalates items that need human judgment. Requires agentCapabilities.triage enabled on the project. Returns a task ID \u2014 use get_task_status to track progress.",
     {
       projectId: external_exports.string().describe("The project ID")
     },
@@ -25945,6 +26230,7 @@ function registerAllTools(server, ctx, client) {
   registerSnapshotTools(server, ctx, client);
   registerBeatQualityTools(server, ctx, client);
   registerPlanQualityTools(server, ctx, client);
+  registerPortfolioCoherenceTools(server, ctx, client);
   registerBeatReframeTools(server, ctx, client);
   registerBeatPlanningTools(server, ctx, client);
   registerRevisionLifecycleTools(server, ctx, client);
@@ -26043,6 +26329,13 @@ var ApiError = class extends Error {
     this.name = "ApiError";
   }
 };
+function safeParseErrorBody(body) {
+  try {
+    return JSON.parse(body);
+  } catch {
+    return void 0;
+  }
+}
 function createHttpClient(config2) {
   const url = new URL(config2.apiBaseUrl);
   const isLocalhost = url.hostname === "localhost" || url.hostname === "127.0.0.1";
@@ -26084,7 +26377,7 @@ function createHttpClient(config2) {
     }
     return void 0;
   }
-  const POLL_INTERVAL_MS3 = 4e3;
+  const POLL_INTERVAL_MS4 = 4e3;
   async function pollTaskResult(taskId) {
     const deadline = Date.now() + LONG_RUNNING_TIMEOUT_MS;
     while (Date.now() < deadline) {
@@ -26094,7 +26387,7 @@ function createHttpClient(config2) {
       );
       if (task?.status === "completed") return task.result;
       if (task?.status === "failed") throw new Error(`Task failed: ${task.error ?? "unknown error"}`);
-      await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS3));
+      await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS4));
     }
     throw new Error(`Task ${taskId} timed out after ${LONG_RUNNING_TIMEOUT_MS}ms`);
   }
@@ -26596,14 +26889,31 @@ function createHttpClient(config2) {
       const result = await request("GET", `/api/projects/${encodeURIComponent(projectId)}/beats/${encodeURIComponent(beatId)}/history`);
       return result?.timeline ?? [];
     },
-    // Beat Composer
-    composeRevisions: async (beatId, drafts, triggeredBy, options) => {
-      const result = await request("POST", `/api/beats/${encodeURIComponent(beatId)}/scaffold-revisions`, { drafts, triggeredBy, force: options?.force });
-      return {
-        revisions: result.revisions,
-        alreadyExisted: result.alreadyExisted ?? false
-      };
+    // Plan Beat Versions (agent decomposition of a Beat into waypoint BVs)
+    planBeatVersions: async (beatId, _actorId, options) => {
+      const force = options?.force ? "?force=true" : "";
+      try {
+        const result = await request(
+          "POST",
+          `/api/beats/${encodeURIComponent(beatId)}/plan-versions${force}`,
+          {}
+        );
+        if (!result) throw new Error(`Beat not found: ${beatId}`);
+        return result.beatVersions;
+      } catch (err) {
+        if (err instanceof ApiError) {
+          const parsed = safeParseErrorBody(err.body);
+          if (err.status === 422 && parsed?.code === "beat_quality_gate_failed" && parsed.gate) {
+            throw new BeatQualityGateError(parsed.gate);
+          }
+          if (err.status === 409 && parsed?.code === "plan_versions_already_exist" && Array.isArray(parsed.existingBeatVersionIds)) {
+            throw new PlanVersionsIdempotencyError(parsed.existingBeatVersionIds);
+          }
+        }
+        throw err;
+      }
     },
+    // Beat Composer
     recordMergeEvent: async () => {
       throw new Error("Beat merge not supported via HTTP client yet");
     },
@@ -26664,6 +26974,15 @@ function createHttpClient(config2) {
       if (!result?.taskId) throw new Error("Implementation enqueue failed: no taskId returned");
       return { taskId: result.taskId, taskType: "work_item_implementation", status: result.status ?? "pending", projectId, createdAt: (/* @__PURE__ */ new Date()).toISOString() };
     },
+    implementRevision: async (revisionId, projectId, triggeredBy) => {
+      const result = await request(
+        "POST",
+        `/api/projects/${encodeURIComponent(projectId)}/revisions/${encodeURIComponent(revisionId)}/implement`,
+        triggeredBy ? { triggeredBy } : {}
+      );
+      if (!result?.taskId) throw new Error("Revision implementation enqueue failed: no taskId returned");
+      return { taskId: result.taskId, taskType: "revision_implementation", status: result.status ?? "pending", projectId, createdAt: (/* @__PURE__ */ new Date()).toISOString() };
+    },
     validateWorkItems: async (projectId, noteIds) => {
       const result = await request(
         "POST",
@@ -26673,15 +26992,6 @@ function createHttpClient(config2) {
       if (!result?.taskId) throw new Error("Validation enqueue failed: no taskId returned");
       return { taskId: result.taskId, taskType: "work_item_validation", status: result.status ?? "pending", projectId, createdAt: (/* @__PURE__ */ new Date()).toISOString() };
     },
-    composeBeat: async (projectId, beatId) => {
-      const result = await request(
-        "POST",
-        `/api/projects/${encodeURIComponent(projectId)}/beats/${encodeURIComponent(beatId)}/compose`,
-        {}
-      );
-      if (!result?.taskId) throw new Error("Compose beat enqueue failed: no taskId returned");
-      return { taskId: result.taskId, taskType: "compose_beat", status: result.status ?? "pending", projectId, createdAt: (/* @__PURE__ */ new Date()).toISOString() };
-    },
     planRevisionBatch: async (projectId, revisionIds) => {
       const result = await request(
         "POST",
@@ -26833,10 +27143,17 @@ function createHttpClient(config2) {
       const res = await request("GET", `/api/checks/${encodeURIComponent(checkId)}`);
       return res.check;
     },
-    listProjectChecks: async (projectId, checkType) => {
-      const qs = checkType ? `?type=${encodeURIComponent(checkType)}` : "";
-      const res = await request("GET", `/api/projects/${encodeURIComponent(projectId)}/checks${qs}`);
-      return res.checks;
+    listProjectChecks: async (projectId, checkType, options) => {
+      const params = new URLSearchParams();
+      if (checkType) params.set("type", checkType);
+      if (options?.limit !== void 0) params.set("limit", String(options.limit));
+      if (options?.cursor) params.set("cursor", options.cursor);
+      const qs = params.toString() ? `?${params.toString()}` : "";
+      const res = await request(
+        "GET",
+        `/api/projects/${encodeURIComponent(projectId)}/checks${qs}`
+      );
+      return { checks: res?.checks ?? [], nextCursor: res?.nextCursor };
     },
     listBeatChecks: async (beatId, projectId, checkType) => {
       const qs = checkType ? `?type=${encodeURIComponent(checkType)}` : "";
@@ -27089,7 +27406,7 @@ function loadConfig() {
   };
 }
 async function main() {
-  console.error(`[harmonica-mcp] v${"0.27.0"} starting\u2026`);
+  console.error(`[harmonica-mcp] v${"0.28.0"} starting\u2026`);
   const config2 = loadConfig();
   const client = createHttpClient({
     apiBaseUrl: config2.apiBaseUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codazen/harmonica-mcp",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "MCP server for Harmonica — connect Claude to your Harmonica projects",
   "license": "MIT",
   "bin": {