@codazen/harmonica-mcp 2.1.0 → 3.0.0

package/dist/index.js

@@ -21526,6 +21526,17 @@ async function assertProjectInOrg(client, projectId, orgId) {
     );
   }
 }
+async function assertRevisionInProject(client, revisionId, projectId) {
+  const revision = await client.getRevision(revisionId);
+  if (!revision) {
+    throw new Error(`Revision not found: "${revisionId}"`);
+  }
+  if (revision.projectId !== projectId) {
+    throw new Error(
+      `Revision "${revisionId}" does not belong to project "${projectId}". Access denied.`
+    );
+  }
+}
 async function assertBeatInOrg(client, beatId, orgId) {
   const beat = await client.getBeat(beatId);
   if (!beat) {
@@ -22421,11 +22432,18 @@ function registerBeatPlanningTools(server, ctx, client) {
 
 // ../../libs/harmonica-services/src/mcp/check.constants.ts
 var CHECK_MAX_SCORES = {
+  beat_coda_quality: 5,
+  // Legacy name for beat_coda_quality — kept until every caller passes the new name (N-4E09-6779).
   beat_quality: 5,
+  beat_version_quality: 5,
+  // Legacy name for beat_version_quality — kept until every caller passes the new name.
   plan_quality: 5,
   build_quality: 5,
+  // Retired from the taxonomy (B-308 v3) — kept so historical records still
+  // render with the right denominator.
   pii_scan: 100,
   portfolio_coherence: 5,
+  revision_quality: 5,
   drop_quality: 5
 };
 
@@ -22467,8 +22485,8 @@ ${d.rationale}${d.suggestions?.length ? `
 \u2022 ${d.suggestions.join("\n\u2022 ")}` : ""}`
   ).join("\n\n");
   return [
-    `## Beat Quality Check \u2014 ${check2.targetId}`,
-    `**Overall Score:** ${check2.overallScore}/${CHECK_MAX_SCORES.beat_quality}`,
+    `## Beat Coda Quality Check \u2014 ${check2.targetId}`,
+    `**Overall Score:** ${check2.overallScore}/${CHECK_MAX_SCORES.beat_coda_quality}`,
     `**Summary:** ${check2.summary}`,
     check2.topSuggestion ? `**Top Suggestion:** ${check2.topSuggestion}` : "",
     "",
@@ -22476,35 +22494,46 @@ ${d.rationale}${d.suggestions?.length ? `
   ].filter(Boolean).join("\n");
 }
 function registerBeatQualityTools(server, ctx, client) {
-  server.tool(
-    "check_beat_quality",
-    "Enqueue a Beat quality check across 6 dimensions (Distinctive, Harmonious, Substantial, Durable, Clear, Strategically Aligned). By default returns a jobId immediately (fire-and-forget) \u2014 use get_job_status or list_checks to retrieve results. Set wait=true to block until the check completes and receive the scorecard inline. WARNING: wait=true holds the MCP session open for 30\u201360s per check \u2014 for bulk operations (more than one Beat), omit wait and poll get_job_status separately to avoid session exhaustion.",
-    {
-      beatId: external_exports.string().describe("The beat ID (e.g., TF-B-001)"),
-      projectId: external_exports.string().describe("The project ID"),
-      wait: external_exports.boolean().optional().describe("If true, block until the check completes and return the scorecard inline. Default: false (returns taskId immediately).")
-    },
-    async ({ beatId, projectId, wait }) => {
-      try {
-        await assertBeatInOrg(client, beatId, ctx.orgId);
-        const { taskId } = await client.checkBeatQuality(projectId, beatId);
-        if (!wait) {
-          return {
-            content: [{
-              type: "text",
-              text: `Quality check enqueued for ${beatId}.
+  const schema = {
+    beatId: external_exports.string().describe("The beat ID (e.g., TF-B-001)"),
+    projectId: external_exports.string().describe("The project ID"),
+    wait: external_exports.boolean().optional().describe("If true, block until the check completes and return the scorecard inline. Default: false (returns taskId immediately).")
+  };
+  const handler = async ({ beatId, projectId, wait }) => {
+    try {
+      await assertBeatInOrg(client, beatId, ctx.orgId);
+      const { taskId } = await client.checkBeatQuality(projectId, beatId);
+      if (!wait) {
+        return {
+          content: [{
+            type: "text",
+            text: `Quality check enqueued for ${beatId}.
 Job ID: ${taskId}
 
 Use get_job_status with jobId="${taskId}" to poll for results, or list_checks to retrieve the completed scorecard once done.`
-            }]
-          };
-        }
-        const check2 = await pollForCheck(client, taskId);
-        return { content: [{ type: "text", text: formatScorecard(check2) }] };
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return { content: [{ type: "text", text: `Quality check failed: ${message}` }], isError: true };
+          }]
+        };
       }
+      const check2 = await pollForCheck(client, taskId);
+      return { content: [{ type: "text", text: formatScorecard(check2) }] };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return { content: [{ type: "text", text: `Quality check failed: ${message}` }], isError: true };
+    }
+  };
+  server.tool(
+    "check_beat_coda_quality",
+    "Enqueue a Beat definition quality check across 7 dimensions (Distinctive, Harmonious, Substantial, Durable, Clear, Strategically Aligned, Business Outcome) \u2014 grades the Beat's Coda and directing context, persisted as beat_coda_quality. By default returns a jobId immediately (fire-and-forget) \u2014 use get_job_status or list_checks to retrieve results. Set wait=true to block until the check completes and receive the scorecard inline. WARNING: wait=true holds the MCP session open for 30\u201360s per check \u2014 for bulk operations (more than one Beat), omit wait and poll get_job_status separately to avoid session exhaustion.",
+    schema,
+    handler
+  );
+  server.tool(
+    "check_beat_quality",
+    "DEPRECATED \u2014 renamed to check_beat_coda_quality (the check grades the Beat's definition: its Coda and directing context). This alias runs the same check and persists it as beat_coda_quality. Prefer check_beat_coda_quality.",
+    schema,
+    async (args) => {
+      console.warn("[deprecated-tool] check_beat_quality invoked \u2014 use check_beat_coda_quality (N-4E09-6779)");
+      return handler(args);
     }
   );
 }
@@ -22747,7 +22776,8 @@ function formatNoteSummary(note) {
   const crit = note.criticality != null ? ` (criticality: ${note.criticality.toFixed(2)})` : "";
   const scope = note.beatId ? ` [Beat: ${note.beatId}]` : "";
   const rev = note.revisionId ? ` [Rev: ${note.revisionId}]` : "";
-  return `- **${type}** (${note.noteId})${status}${crit}${scope}${rev}: ${note.content}`;
+  const bv = note.beatVersionId ? ` [BV: ${note.beatVersionId}]` : "";
+  return `- **${type}** (${note.noteId})${status}${crit}${scope}${rev}${bv}: ${note.content}`;
 }
 function formatNoteList(notes) {
   if (notes.length === 0) {
@@ -22805,6 +22835,9 @@ function formatNoteDetail(note) {
   if (note.revisionId) {
     parts.push(`**Revision:** ${note.revisionId}`);
   }
+  if (note.beatVersionId) {
+    parts.push(`**Beat Version:** ${note.beatVersionId}`);
+  }
   if (note.assumptionMeta) {
     parts.push("", "### Assumption Details");
     parts.push(`- Confidence: ${note.assumptionMeta.confidence}`);
@@ -23360,7 +23393,7 @@ function registerBeatVersionTools(server, ctx, client) {
   );
   server.tool(
     "create_beat_version",
-    "Create a new Beat Version for an existing Beat. A Beat Version is a shippable increment \u2014 one planned delivery of the Beat's capability. Starts at active status (binary: active | archived). Run check_plan_quality on the Beat Version BEFORE creating its first Revision \u2014 the first Revision is gated on a recent, passing plan_quality check.",
+    "Create a new Beat Version for an existing Beat. A Beat Version is a shippable increment \u2014 one planned delivery of the Beat's capability. Starts at active status (binary: active | archived). Run check_beat_version_quality on the Beat Version BEFORE creating its first Revision \u2014 the first Revision is gated on a recent, passing beat_version_quality check.",
     {
       beatId: external_exports.string().describe("The Beat ID to create the Beat Version on"),
       title: external_exports.string().min(1).max(300).describe("What this Beat Version delivers (concise, outcome-focused)"),
@@ -23417,7 +23450,7 @@ function registerBeatVersionTools(server, ctx, client) {
           `**Status:** ${beatVersion.status}`,
           `**Version:** v${beatVersion.versionNumber}`,
           "",
-          `Next step: Run check_plan_quality on this Beat Version before creating its first Revision (the first Revision is gated on a passing plan_quality check).`
+          `Next step: Run check_beat_version_quality on this Beat Version before creating its first Revision (the first Revision is gated on a passing beat_version_quality check).`
         ];
         return { content: [{ type: "text", text: lines.join("\n") }] };
       } catch (err) {
@@ -23428,7 +23461,7 @@ function registerBeatVersionTools(server, ctx, client) {
   );
   server.tool(
     "update_beat_version",
-    "Update a Beat Version's content fields (title, description, scope, assignees, etc.). Does NOT change lifecycle state \u2014 use transition_beat_version for that. Editing the Beat Version after a plan_quality check will invalidate the check \u2014 re-run before creating its first Revision.",
+    "Update a Beat Version's content fields (title, description, scope, assignees, etc.). Does NOT change lifecycle state \u2014 use transition_beat_version for that. Editing the Beat Version after a beat_version_quality check will invalidate the check \u2014 re-run before creating its first Revision.",
     {
       beatVersionId: external_exports.string().describe("The Beat Version ID (e.g., bv-abc123)"),
       title: external_exports.string().min(1).max(300).optional().describe("New title"),
@@ -23481,9 +23514,9 @@ 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.",
+    "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_coda_quality check (run check_beat_coda_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)"),
+      beatId: external_exports.string().describe("The Beat ID to decompose (must have a Coda and a passing beat_coda_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 }) => {
@@ -23499,7 +23532,7 @@ function registerBeatVersionTools(server, ctx, client) {
           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 creating its first Revision (the first Revision is gated on a passing plan_quality check).");
+        lines.push("", "Run check_beat_version_quality on each Beat Version before creating its first Revision (the first Revision is gated on a passing beat_version_quality check).");
         return { content: [{ type: "text", text: lines.join("\n") }] };
       } catch (err) {
         if (err instanceof BeatQualityGateError) {
@@ -23536,7 +23569,7 @@ function registerBeatVersionTools(server, ctx, client) {
   );
   server.tool(
     "transition_beat_version",
-    'Transition a Beat Version between binary statuses: active \u2194 archived. Archiving requires a reason; reviving an archived Beat Version back to active does not. Pipeline position ("where is this?") is derived from child Revisions and the Drop, not from status. plan_quality is now enforced at first-Revision creation, not on any Beat Version transition.',
+    'Transition a Beat Version between binary statuses: active \u2194 archived. Archiving requires a reason; reviving an archived Beat Version back to active does not. Pipeline position ("where is this?") is derived from child Revisions and the Drop, not from status. beat_version_quality is now enforced at first-Revision creation, not on any Beat Version transition.',
     {
       beatVersionId: external_exports.string().describe("The Beat Version ID (e.g., bv-abc123)"),
       targetState: external_exports.enum(BEAT_VERSION_STATUSES).describe("The target status (active | archived)"),
@@ -23673,12 +23706,41 @@ function registerCadenceScheduleTools(server, _ctx, client) {
   );
 }
 
+// ../../libs/harmonica-services/src/check-target-validation.ts
+function isBeatVersionTargetId(targetId) {
+  return /^bv-\S/.test(targetId);
+}
+function beatVersionQualityTargetError(targetId) {
+  if (typeof targetId !== "string") {
+    return "beat_version_quality requires a Beat Version ID (bv-\u2026), but no targetId was provided.";
+  }
+  if (targetId.startsWith("rev-")) {
+    return "beat_version_quality targets a Beat Version, not a Revision \u2014 pass a Beat Version ID (bv-\u2026). Revisions inherit their parent Beat Version's plan and grade; run beat_version_quality on the parent Beat Version, or build_quality for a build-readiness grade.";
+  }
+  if (!isBeatVersionTargetId(targetId)) {
+    return `beat_version_quality requires a Beat Version ID (bv-\u2026), got '${targetId}'.`;
+  }
+  return null;
+}
+function isRevisionTargetId(targetId) {
+  return /^rev-\S/.test(targetId);
+}
+function revisionQualityTargetError(targetId) {
+  if (typeof targetId !== "string" || !isRevisionTargetId(targetId)) {
+    return `revision_quality runs only on Revisions (rev-*); got "${targetId ?? ""}". For a Beat Version, run beat_version_quality on the Beat Version.`;
+  }
+  return null;
+}
+
 // ../../libs/harmonica-services/src/build-quality/target-validation.ts
 function buildQualityTargetError(targetId) {
+  if (typeof targetId !== "string") {
+    return "build_quality requires a Beat Version ID (bv-\u2026), but no targetId was provided.";
+  }
   if (targetId.startsWith("rev-")) {
     return "build_quality now targets a Beat Version, not a Revision \u2014 pass a Beat Version ID (bv-\u2026). The check moved to the Beat Version so it grades the planned capability against the codebase and runs even when there are no Revisions yet.";
   }
-  if (!/^bv-\S/.test(targetId)) {
+  if (!isBeatVersionTargetId(targetId)) {
     return `build_quality requires a Beat Version ID (bv-\u2026), got '${targetId}'.`;
   }
   return null;
@@ -23713,7 +23775,7 @@ function registerCheckTools(server, ctx, client) {
       beatId: external_exports.string().optional().describe("List checks for this specific beat"),
       beatVersionId: external_exports.string().optional().describe("List checks for this specific beat version"),
       revisionId: external_exports.string().optional().describe("List checks for this specific revision"),
-      checkType: external_exports.enum(["beat_quality", "plan_quality", "build_quality", "pii_scan", "portfolio_coherence"]).optional().describe("Filter by check type")
+      checkType: external_exports.enum(["beat_coda_quality", "beat_quality", "beat_version_quality", "plan_quality", "build_quality", "pii_scan", "portfolio_coherence"]).optional().describe("Filter by check type. beat_quality is the DEPRECATED alias of beat_coda_quality. plan_quality is the DEPRECATED alias of beat_version_quality. pii_scan is RETIRED from the taxonomy (PII detection moved to the Scan family, N-4E09-6809) \u2014 it is still accepted here so historical records stay readable, but no new pii_scan checks are written.")
     },
     async ({ projectId, beatId, beatVersionId, revisionId, checkType }) => {
       try {
@@ -23840,10 +23902,10 @@ function registerCheckTools(server, ctx, client) {
   );
   server.tool(
     "run_check",
-    "Run a check on a Beat or Beat Version. beat_quality: 6-dimension Beat quality (1-5), target a beatId. plan_quality: 6-dimension plan quality (1-5), target a Beat Version (bv-*). build_quality: 8-dimension engineering assessment (1-5), target a Beat Version (bv-*) \u2014 build_quality moved from the Revision to the Beat Version, so it grades the planned capability against the codebase and runs even when the Beat Version has no Revisions yet.",
+    "Run a check on a Beat or Beat Version. beat_coda_quality: 7-dimension Beat definition quality (1-5) \u2014 grades the Coda and directing context, target a beatId (beat_quality is its DEPRECATED alias and persists under the new name). beat_version_quality: 7-dimension plan quality (1-5) including completeness, target a Beat Version (bv-*) \u2014 plan_quality is its DEPRECATED alias. build_quality: 9-dimension engineering assessment (1-5), target a Beat Version (bv-*) \u2014 build_quality moved from the Revision to the Beat Version, so it grades the planned capability against the codebase and runs even when the Beat Version has no Revisions yet.",
     {
-      checkType: external_exports.enum(["beat_quality", "plan_quality", "build_quality"]).describe("Type of check to run"),
-      targetId: external_exports.string().describe("The target entity ID \u2014 a beatId for beat_quality, or a Beat Version ID (bv-*) for plan_quality and build_quality"),
+      checkType: external_exports.enum(["beat_coda_quality", "beat_quality", "beat_version_quality", "plan_quality", "build_quality"]).describe("Type of check to run. beat_quality is the deprecated alias of beat_coda_quality. plan_quality is the deprecated alias of beat_version_quality."),
+      targetId: external_exports.string().describe("The target entity ID \u2014 a beatId for beat_coda_quality, or a Beat Version ID (bv-*) for beat_version_quality and build_quality"),
       projectId: external_exports.string().describe("The project ID"),
       branch: external_exports.string().optional().describe("Override the git branch for code checks (default: project default branch)"),
       localPath: external_exports.string().optional().describe("Absolute path to an already-cloned local copy of the repo \u2014 skips git clone entirely (useful for large repos or offline use)")
@@ -23851,11 +23913,9 @@ function registerCheckTools(server, ctx, client) {
     async ({ checkType, targetId, projectId, branch, localPath }) => {
       try {
         await assertProjectInOrg(client, projectId, ctx.orgId);
-        if (checkType === "build_quality") {
-          const targetError = buildQualityTargetError(targetId);
-          if (targetError) {
-            return { content: [{ type: "text", text: targetError }], isError: true };
-          }
+        const targetError = checkType === "build_quality" ? buildQualityTargetError(targetId) : checkType === "beat_version_quality" || checkType === "plan_quality" ? beatVersionQualityTargetError(targetId) : null;
+        if (targetError) {
+          return { content: [{ type: "text", text: targetError }], isError: true };
         }
         const opts = branch || localPath ? { branch, localPath } : void 0;
         const task = await client.runCheck(projectId, checkType, targetId, opts);
@@ -23876,10 +23936,13 @@ function registerCheckTools(server, ctx, client) {
   );
 }
 var CHECK_TYPE_DISPLAY = {
-  beat_quality: "Quality",
-  plan_quality: "Plan Quality",
+  beat_coda_quality: "Coda Quality",
+  beat_quality: "Coda Quality",
+  beat_version_quality: "Beat Version Quality",
+  plan_quality: "Beat Version Quality",
   build_quality: "Build Quality",
-  pii_scan: "PII Scan",
+  // Retired (B-308 v3) — label retained so historical records never render unlabeled.
+  pii_scan: "PII Scan (retired)",
   portfolio_coherence: "Portfolio Coherence"
 };
 function formatCheck(a) {
@@ -24047,6 +24110,11 @@ function registerDeliverableGroupTools(server, ctx, client) {
           content: [{ type: "text", text: `DeliverableGroup not found: ${deliverableGroupId}` }]
         };
       }
+      if (g.orgId !== ctx.orgId) {
+        throw new Error(
+          `DeliverableGroup "${deliverableGroupId}" does not belong to the configured organization. Access denied.`
+        );
+      }
       const lines = [
         `ID: ${g.deliverableGroupId}`,
         `Code: ${g.groupCode}`,
@@ -24055,6 +24123,10 @@ function registerDeliverableGroupTools(server, ctx, client) {
         `Status: ${g.status}`,
         `VU Rate: ${g.vuRate}`,
         g.description ? `Description: ${g.description}` : null,
+        g.deliverables ? `Deliverables:
+${g.deliverables}` : null,
+        g.acceptanceCriteria ? `Acceptance Criteria:
+${g.acceptanceCriteria}` : null,
         g.parentGroupId ? `Parent Group: ${g.parentGroupId}` : null,
         g.proposedAt ? `Proposed: ${g.proposedAt}` : null,
         g.approvedAt ? `Approved: ${g.approvedAt}` : null,
@@ -24220,51 +24292,6 @@ function registerDeliverableGroupTools(server, ctx, client) {
       return { content: [{ type: "text", text }] };
     }
   );
-  server.tool(
-    "assign_beat_version_to_deliverable_group",
-    'Assign a Beat Version to a DeliverableGroup (the Work Plan / WBS link). A Beat Version belongs to at most one group; assigning moves it if it was in another group. Use to answer "put this feature increment under this SOW/phase".',
-    {
-      deliverableGroupId: external_exports.string().describe("The DeliverableGroup ID"),
-      beatVersionId: external_exports.string().describe("The Beat Version ID to place in the group")
-    },
-    async ({ deliverableGroupId, beatVersionId }) => {
-      await assertDeliverableGroupInOrg(client, deliverableGroupId, ctx.orgId);
-      const bv = await client.getBeatVersion(beatVersionId);
-      if (!bv) {
-        return { content: [{ type: "text", text: `Beat Version not found: ${beatVersionId}` }] };
-      }
-      await assertProjectInOrg(client, bv.projectId, ctx.orgId);
-      const ok = await client.setBeatVersionDeliverableGroup(deliverableGroupId, beatVersionId);
-      if (!ok) {
-        return { content: [{ type: "text", text: `Beat Version not found: ${beatVersionId}` }] };
-      }
-      return {
-        content: [{ type: "text", text: `Assigned Beat Version ${beatVersionId} to DeliverableGroup ${deliverableGroupId}.` }]
-      };
-    }
-  );
-  server.tool(
-    "clear_beat_version_deliverable_group",
-    'Remove a Beat Version from a DeliverableGroup (clears its Work Plan link). The Beat Version must currently belong to the named group. Use to answer "take this increment out of this SOW/phase".',
-    {
-      deliverableGroupId: external_exports.string().describe("The DeliverableGroup ID the Beat Version currently belongs to"),
-      beatVersionId: external_exports.string().describe("The Beat Version ID to remove from the group")
-    },
-    async ({ deliverableGroupId, beatVersionId }) => {
-      await assertDeliverableGroupInOrg(client, deliverableGroupId, ctx.orgId);
-      const bv = await client.getBeatVersion(beatVersionId);
-      if (!bv) {
-        return { content: [{ type: "text", text: `Beat Version not found: ${beatVersionId}` }] };
-      }
-      if (bv.deliverableGroupId !== deliverableGroupId) {
-        return { content: [{ type: "text", text: `Beat Version ${beatVersionId} is not a member of DeliverableGroup ${deliverableGroupId}.` }] };
-      }
-      await client.clearBeatVersionDeliverableGroup(deliverableGroupId, beatVersionId);
-      return {
-        content: [{ type: "text", text: `Cleared Beat Version ${beatVersionId} from DeliverableGroup ${deliverableGroupId}.` }]
-      };
-    }
-  );
   server.tool(
     "assign_drop_to_deliverable_group",
     `Link a Drop to a DeliverableGroup so it appears on the parent Movement's timed-release axis (the Drops shown on the Movement overview). A Drop belongs to at most one group; linking moves it if it was in another group. Use to answer "put this release under this SOW/phase" or "add a Drop to this Movement".`,
@@ -24290,17 +24317,20 @@ function registerDeliverableGroupTools(server, ctx, client) {
   );
   server.tool(
     "list_deliverable_group_beat_versions",
-    'List the Beat Versions assigned to a DeliverableGroup (its Work Plan). Use to answer "what feature increments are scoped under this SOW/phase?"',
+    'List the Beat Versions linked to a DeliverableGroup via its work items (Work Plan). Use to answer "what feature increments are scoped under this SOW/phase?"',
     {
       deliverableGroupId: external_exports.string().describe("The DeliverableGroup ID")
     },
     async ({ deliverableGroupId }) => {
       await assertDeliverableGroupInOrg(client, deliverableGroupId, ctx.orgId);
-      const items = await client.listDeliverableGroupBeatVersions(deliverableGroupId);
-      if (items.length === 0) {
-        return { content: [{ type: "text", text: "No beat versions in this group." }] };
-      }
-      const hydrated = await Promise.all(items.map((b) => client.getBeatVersion(b.beatVersionId)));
+      const workItems = await client.listTrackWorkItems(deliverableGroupId);
+      const bvIds = [...new Set(
+        workItems.map((wi) => wi.beatVersionId).filter((id) => id !== void 0)
+      )];
+      if (bvIds.length === 0) {
+        return { content: [{ type: "text", text: "No beat versions linked via work items in this group." }] };
+      }
+      const hydrated = await Promise.all(bvIds.map((id) => client.getBeatVersion(id)));
       const text = hydrated.filter((bv) => bv !== void 0).map((bv) => `[${bv.beatVersionId}] v${bv.versionNumber} \u2014 ${bv.title} (${bv.status})`).join("\n");
       return { content: [{ type: "text", text }] };
     }
@@ -24421,7 +24451,7 @@ function formatDownbeatHarmonyReport(r) {
 function registerDownbeatHarmonyReportTools(server, _ctx, client) {
   server.tool(
     "get_downbeat_harmony_report",
-    "Get the Downbeat Harmony Report: a read-only qualification advisor that extends the Pulse report's per-Beat signals (increments since Downbeat, edited-goal drift, relational drift) with a Measure/convergence mismatch check, and returns which open Beats under an Account qualify for a Downbeat this cycle \u2014 citing exactly which signal(s) triggered each one. Never anchors a Downbeat; the caller decides whether to accept and calls set_downbeat per qualifying Beat themselves.",
+    "Get the Downbeat Harmony Report: a read-only qualification advisor that extends the Pulse report's per-Beat signals (increments since Downbeat, edited-goal drift, relational drift) with a work-item/convergence mismatch check, and returns which open Beats under an Account qualify for a Downbeat this cycle \u2014 citing exactly which signal(s) triggered each one. Never anchors a Downbeat; the caller decides whether to accept and calls set_downbeat per qualifying Beat themselves.",
     {
       accountId: external_exports.string().describe("The Account ID"),
       asOf: external_exports.string().datetime().optional().describe("ISO 8601 timestamp used only to stamp the report header. The underlying signals always reflect current state. Defaults to the current time.")
@@ -24615,7 +24645,15 @@ function registerDropQualityTools(server, ctx, client) {
 
 // ../../libs/harmonica-services/src/mcp/tools/drop-tools.ts
 var DROP_STATES = ["draft", "open", "released", "rolled_back", "cancelled"];
-var FEATURE_FLAG_STAGES = ["local", "staging", "prod"];
+var FEATURE_FLAG_STAGES = [
+  "local",
+  "staging",
+  "staging-alpha",
+  "staging-beta",
+  "alpha",
+  "beta",
+  "prod"
+];
 var featureFlagBindingSchema = external_exports.object({
   scope: external_exports.string().min(1).max(100).describe('Feature-flag scope, e.g. "harmonica"'),
   name: external_exports.string().min(1).max(200).describe("Feature-flag name within the scope"),
@@ -25329,166 +25367,6 @@ ${formatLayerDetail(layer)}` }] };
   );
 }
 
-// ../../libs/harmonica-services/src/mcp/tools/measure-tools.ts
-var VU_ENUM = ["XS", "S", "M", "L", "XL"];
-function vu(valueUnit) {
-  return valueUnit ?? "(hidden)";
-}
-function registerMeasureTools(server, _ctx, client) {
-  server.tool(
-    "list_track_measures",
-    'List all Measures under a Track (DeliverableGroup). A Measure is the atomic unit of planned work carrying a Value Unit estimate. Recognition cues: "what work is planned on this track", "list the measures" \u2192 list_track_measures.',
-    {
-      trackId: external_exports.string().describe("The Track (DeliverableGroup) ID")
-    },
-    async ({ trackId }) => {
-      const measures = await client.listTrackMeasures(trackId);
-      const text = measures.length === 0 ? "No measures found." : measures.map((m) => `[${m.measureId}] ${m.measureCode} \u2014 ${m.title} (VU: ${vu(m.valueUnit)})`).join("\n");
-      return { content: [{ type: "text", text }] };
-    }
-  );
-  server.tool(
-    "list_beat_version_measures",
-    'List the Measures linked to a Beat Version \u2014 answers "which planned work advances this Beat Version".',
-    {
-      beatVersionId: external_exports.string().describe("The Beat Version ID (e.g., bv-abc123)")
-    },
-    async ({ beatVersionId }) => {
-      const measures = await client.listBeatVersionMeasures(beatVersionId);
-      const text = measures.length === 0 ? "No measures found." : measures.map((m) => `[${m.measureId}] ${m.measureCode} \u2014 ${m.title} (VU: ${vu(m.valueUnit)})`).join("\n");
-      return { content: [{ type: "text", text }] };
-    }
-  );
-  server.tool(
-    "get_measure",
-    "Get a Measure by ID. Returns title, Value Unit estimate (if visible), Track, and any linked Beat Version.",
-    {
-      measureId: external_exports.string().describe("The measure ID (e.g., me-abc123)")
-    },
-    async ({ measureId }) => {
-      const m = await client.getMeasure(measureId);
-      if (!m) {
-        return { content: [{ type: "text", text: `Measure not found: ${measureId}` }] };
-      }
-      const lines = [
-        `ID: ${m.measureId}`,
-        `Code: ${m.measureCode}`,
-        `Title: ${m.title}`,
-        `Track: ${m.trackId}`,
-        `Value Unit: ${vu(m.valueUnit)}`,
-        m.beatVersionId ? `Beat Version: ${m.beatVersionId}` : null,
-        m.createdBy ? `Created By: ${m.createdBy}` : null,
-        `Created: ${m.createdAt}`,
-        `Updated: ${m.updatedAt}`
-      ].filter(Boolean).join("\n");
-      return { content: [{ type: "text", text: lines }] };
-    }
-  );
-  server.tool(
-    "create_measure",
-    "Create a Measure under a Track (DeliverableGroup). A Measure is the atomic unit of planned work with a Value Unit estimate \u2014 it is NOT a Beat. Optionally link it to a Beat Version at creation.",
-    {
-      trackId: external_exports.string().describe("The Track (DeliverableGroup) ID this Measure belongs to"),
-      title: external_exports.string().min(1).max(300).describe('Measure title (e.g. "Login form validation")'),
-      valueUnit: external_exports.enum(VU_ENUM).describe("Value Unit label estimate (t-shirt size XS\u2013XL)"),
-      beatVersionId: external_exports.string().min(1).max(128).optional().describe("Optional Beat Version to link at creation. Must exist."),
-      createdBy: external_exports.string().optional().describe("Optional creator identity for audit")
-    },
-    async ({ trackId, title, valueUnit, beatVersionId, createdBy }) => {
-      const m = await client.createMeasure({
-        trackId,
-        title,
-        valueUnit,
-        ...beatVersionId !== void 0 && { beatVersionId },
-        ...createdBy !== void 0 && { createdBy }
-      });
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Created Measure: [${m.measureId}] ${m.measureCode} \u2014 ${m.title} (VU: ${vu(m.valueUnit)})`
-          }
-        ]
-      };
-    }
-  );
-  server.tool(
-    "update_measure",
-    "Update mutable content fields on a Measure (title, valueUnit). To change the Beat Version link use link_measure_to_beat_version / unlink_measure_from_beat_version instead.",
-    {
-      measureId: external_exports.string().describe("The measure ID"),
-      title: external_exports.string().min(1).max(300).optional().describe("New title"),
-      valueUnit: external_exports.enum(VU_ENUM).optional().describe("New Value Unit estimate")
-    },
-    async ({ measureId, title, valueUnit }) => {
-      const hasUpdates = title !== void 0 || valueUnit !== void 0;
-      if (!hasUpdates) {
-        return {
-          content: [{ type: "text", text: `No updates provided for Measure: ${measureId}` }],
-          isError: true
-        };
-      }
-      const m = await client.updateMeasure(measureId, {
-        ...title !== void 0 && { title },
-        ...valueUnit !== void 0 && { valueUnit }
-      });
-      if (!m) {
-        return {
-          content: [{ type: "text", text: `Measure not found: ${measureId}` }],
-          isError: true
-        };
-      }
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Updated Measure: [${m.measureId}] ${m.measureCode} \u2014 ${m.title} (VU: ${vu(m.valueUnit)})`
-          }
-        ]
-      };
-    }
-  );
-  server.tool(
-    "link_measure_to_beat_version",
-    "Soft-link a Measure to a single Beat Version (the internal capability it advances). Replaces any existing link.",
-    {
-      measureId: external_exports.string().describe("The measure ID"),
-      beatVersionId: external_exports.string().describe("The Beat Version ID to link (e.g., bv-abc123). Must exist.")
-    },
-    async ({ measureId, beatVersionId }) => {
-      const m = await client.linkMeasureToBeatVersion(measureId, beatVersionId);
-      if (!m) {
-        return {
-          content: [{ type: "text", text: `Measure not found: ${measureId}` }],
-          isError: true
-        };
-      }
-      return {
-        content: [{ type: "text", text: `Linked Measure ${m.measureId} \u2192 Beat Version ${beatVersionId}` }]
-      };
-    }
-  );
-  server.tool(
-    "unlink_measure_from_beat_version",
-    "Remove a Measure's soft link to its Beat Version. No-op-safe: the Measure remains under its Track.",
-    {
-      measureId: external_exports.string().describe("The measure ID")
-    },
-    async ({ measureId }) => {
-      const m = await client.unlinkMeasureFromBeatVersion(measureId);
-      if (!m) {
-        return {
-          content: [{ type: "text", text: `Measure not found: ${measureId}` }],
-          isError: true
-        };
-      }
-      return {
-        content: [{ type: "text", text: `Unlinked Measure ${m.measureId} from its Beat Version` }]
-      };
-    }
-  );
-}
-
 // ../../libs/harmonica-services/src/mcp/tools/membership-tools.ts
 function registerMembershipTools(server, ctx, client) {
   server.tool(
@@ -25913,7 +25791,8 @@ var PLAN_QUALITY_DIMENSIONS = [
   "testable",
   "traceable",
   "assignable",
-  "riskAware"
+  "riskAware",
+  "completeness"
 ];
 var PlanDimensionScoreSchema = external_exports.object({
   dimension: external_exports.enum(PLAN_QUALITY_DIMENSIONS),
@@ -25928,6 +25807,27 @@ var PlanQualityLLMResponseSchema = external_exports.object({
   topSuggestion: external_exports.string()
 });
 
+// ../../libs/harmonica-schemas/src/revision-quality.ts
+var REVISION_QUALITY_DIMENSIONS = [
+  "scoped",
+  "traceable",
+  "testable",
+  "reviewReady",
+  "nonDuplicating"
+];
+var RevisionDimensionScoreSchema = external_exports.object({
+  dimension: external_exports.enum(REVISION_QUALITY_DIMENSIONS),
+  label: external_exports.string(),
+  score: external_exports.number().min(1).max(5),
+  rationale: external_exports.string(),
+  suggestions: external_exports.array(external_exports.string())
+});
+var RevisionQualityLLMResponseSchema = external_exports.object({
+  dimensions: external_exports.array(RevisionDimensionScoreSchema).min(1),
+  summary: external_exports.string(),
+  topSuggestion: external_exports.string()
+});
+
 // ../../libs/harmonica-schemas/src/beat-quality.ts
 var BEAT_QUALITY_DIMENSIONS = [
   "distinctive",
@@ -26741,23 +26641,6 @@ var MovementApiSchema = external_exports.object({
   updatedAt: external_exports.string()
 }).passthrough();
 var MovementsResponseSchema = external_exports.object({ movements: external_exports.array(MovementApiSchema) }).passthrough();
-var ValueUnitEstimateSchema = external_exports.enum(["XS", "S", "M", "L", "XL"]);
-var MeasureApiSchema = external_exports.object({
-  measureId: external_exports.string(),
-  measureCode: external_exports.string(),
-  trackId: external_exports.string(),
-  teamspaceId: external_exports.string(),
-  orgId: external_exports.string(),
-  title: external_exports.string(),
-  valueUnit: ValueUnitEstimateSchema.optional(),
-  beatVersionId: external_exports.string().optional(),
-  createdBy: external_exports.string().optional(),
-  version: external_exports.number().optional(),
-  createdAt: external_exports.string(),
-  updatedAt: external_exports.string()
-}).passthrough();
-var MeasuresResponseSchema = external_exports.object({ measures: external_exports.array(MeasureApiSchema) }).passthrough();
-var MeasureResponseSchema = external_exports.object({ measure: MeasureApiSchema }).passthrough();
 var WorkItemStatusSchema = external_exports.enum(["not_started", "in_progress", "blocked", "done"]);
 var WORK_ITEM_EFFORT_SIZES = [
   "XS",
@@ -26930,7 +26813,6 @@ var WorkPlanBeatVersionApiSchema = external_exports.object({
   versionNumber: external_exports.number(),
   title: external_exports.string(),
   status: BeatVersionStatusSchema,
-  deliverableGroupId: external_exports.string().nullish(),
   // Derived Value Units (VU = Δf × W), read-only. 0 when the BV has no confirmed
   // value-velocity inputs. Computed server-side from the parent Beat's weight.
   // `.default(0)` tolerates a rolling deploy where an older API omits the field —
@@ -26942,6 +26824,19 @@ var WorkPlanBeatVersionApiSchema = external_exports.object({
 var DeliverableGroupBeatVersionsResponseSchema = external_exports.object({
   beatVersions: external_exports.array(WorkPlanBeatVersionApiSchema)
 }).passthrough();
+var RevisionClaimActorSchema = external_exports.union([
+  external_exports.object({ kind: external_exports.literal("user"), userId: external_exports.string() }),
+  external_exports.object({ kind: external_exports.literal("agent"), agentId: external_exports.string(), projectId: external_exports.string() })
+]);
+var RevisionClaimSchema = external_exports.object({
+  claimId: external_exports.string(),
+  status: external_exports.enum(["active", "archived"]),
+  actor: RevisionClaimActorSchema,
+  scope: external_exports.object({ type: external_exports.literal("revision"), revisionId: external_exports.string() })
+}).passthrough();
+var RevisionClaimsResponseSchema = external_exports.object({
+  claims: external_exports.array(RevisionClaimSchema)
+}).passthrough();
 
 // ../../libs/harmonica-services/src/mcp/tools/note-element-tools.ts
 var parentKindSchema = external_exports.enum(["notebook", "note"]);
@@ -27114,13 +27009,14 @@ var DECISION_SIGNIFICANCE_VALUES2 = ["strategic", "structural", "implementation"
 function registerNoteTools(server, ctx, client) {
   server.tool(
     "list_notes",
-    "List Notes for a project. Without beatId: returns all notes (project-level + beat-level). With beatId: returns only notes scoped to that beat. Filterable by type, status, revisionId, and significance. Use offset/limit to paginate beat-scoped results; use cursor for project-wide results.",
+    "List Notes for a project. Without beatId: returns all notes (project-level + beat-level). With beatId: returns only notes scoped to that beat. Filterable by type, status, revisionId, beatVersionId, and significance. Use offset/limit to paginate beat-scoped results; use cursor for project-wide results.",
     {
       projectId: external_exports.string().describe("The project ID"),
       beatId: external_exports.string().optional().describe("Scope to a specific beat (omit for all project notes)"),
       noteType: external_exports.union([external_exports.enum(NOTE_TYPE_VALUES), external_exports.array(external_exports.enum(NOTE_TYPE_VALUES)).min(1)]).optional().describe('Filter by note type \u2014 single value or array for multi-select (e.g. ["constraint", "assumption"])'),
       status: external_exports.enum(NOTE_STATUS_VALUES).optional().describe("Filter by status"),
       revisionId: external_exports.string().optional().describe("Filter to notes scoped to a specific revision"),
+      beatVersionId: external_exports.string().optional().describe("Filter to notes scoped to a specific Beat Version (planning increment)"),
       sourceDocumentNoteId: external_exports.string().optional().describe("Filter to notes extracted from a specific document (matches sourceSubmissionId)"),
       significance: external_exports.enum(DECISION_SIGNIFICANCE_VALUES2).optional().describe("Filter decision Notes by significance tier (strategic | structural | implementation). Notes without a significance value are treated as implementation."),
       offset: external_exports.coerce.number().int().min(0).default(0).describe("Notes to skip for pagination (applies to beat-scoped and source-document-filtered results only)"),
@@ -27128,7 +27024,7 @@ function registerNoteTools(server, ctx, client) {
       cursor: external_exports.string().optional().describe("Opaque pagination cursor from a previous response \u2014 use for project-wide note pagination (no beatId)"),
       orderBy: external_exports.enum(["newest", "oldest"]).optional().describe("Sort order \u2014 newest or oldest first. Applies to beat-scoped queries (beatId provided); omit to use DynamoDB scan order.")
     },
-    async ({ projectId, beatId, noteType, status, revisionId, sourceDocumentNoteId, significance, offset = 0, limit = 100, cursor, orderBy }) => {
+    async ({ projectId, beatId, noteType, status, revisionId, beatVersionId, sourceDocumentNoteId, significance, offset = 0, limit = 100, cursor, orderBy }) => {
       if (Array.isArray(noteType) && noteType.length === 0) {
         return { content: [{ type: "text", text: "noteType must not be an empty array \u2014 omit it to return all types." }], isError: true };
       }
@@ -27149,6 +27045,7 @@ function registerNoteTools(server, ctx, client) {
         noteType,
         status,
         revisionId,
+        beatVersionId,
         significance
       };
       let page;
@@ -27344,13 +27241,14 @@ function registerNoteTools(server, ctx, client) {
       content: external_exports.string().describe("The note content"),
       beatId: external_exports.string().optional().describe("Beat ID if this note is beat-scoped (requires projectId)"),
       revisionId: external_exports.string().optional().describe("Revision ID if this note is revision-scoped (requires projectId)"),
+      beatVersionId: external_exports.string().optional().describe("Beat Version ID if this note governs a specific planning increment (requires beatId)"),
       rationale: external_exports.string().optional().describe("Why this note exists"),
       confidence: external_exports.coerce.number().min(0).max(1).optional().describe("Confidence level for assumptions (0-1)"),
       affectsBeats: external_exports.array(external_exports.string()).optional().describe("Beat IDs this note impacts"),
       dependsOnNotes: external_exports.array(external_exports.string()).optional().describe("Note IDs this note depends on (child \u2192 parent links for consolidation)"),
       significance: external_exports.enum(DECISION_SIGNIFICANCE_VALUES2).optional().describe("Significance tier for decision Notes (strategic | structural | implementation). Defaults to implementation when unset. Only meaningful on noteType=decision.")
     },
-    async ({ projectId, teamspaceId, movementId, noteType, content, beatId, revisionId, rationale, confidence, affectsBeats, dependsOnNotes, significance }) => {
+    async ({ projectId, teamspaceId, movementId, noteType, content, beatId, revisionId, beatVersionId, rationale, confidence, affectsBeats, dependsOnNotes, significance }) => {
       try {
         if ([projectId, teamspaceId, movementId].filter(Boolean).length > 1) {
           return { content: [{ type: "text", text: "Specify at most one of projectId, teamspaceId, or movementId." }], isError: true };
@@ -27366,6 +27264,7 @@ function registerNoteTools(server, ctx, client) {
             projectId,
             beatId,
             revisionId,
+            beatVersionId,
             noteType,
             content,
             rationale,
@@ -28670,10 +28569,10 @@ async function pollForCheck3(client, taskId) {
       if (!task.result) throw new Error(`Task ${taskId} completed with no result`);
       return task.result;
     }
-    if (task.status === "failed") throw new Error(`Plan quality check failed: ${task.error ?? "unknown error"}`);
+    if (task.status === "failed") throw new Error(`Beat version quality check failed: ${task.error ?? "unknown error"}`);
     await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS3));
   }
-  throw new Error(`Plan quality check timed out after ${POLL_TIMEOUT_MS3 / 1e3}s`);
+  throw new Error(`Beat version quality check timed out after ${POLL_TIMEOUT_MS3 / 1e3}s`);
 }
 function formatScorecard2(check2) {
   const bar = (score, max) => "\u2588".repeat(score) + "\u2591".repeat(max - score);
@@ -28683,8 +28582,8 @@ ${d.rationale}${d.suggestions?.length ? `
 \u2022 ${d.suggestions.join("\n\u2022 ")}` : ""}`
   ).join("\n\n");
   return [
-    `## Plan Quality Check \u2014 ${check2.targetId}`,
-    `**Overall Score:** ${check2.overallScore}/${CHECK_MAX_SCORES.plan_quality}`,
+    `## Beat Version Quality Check \u2014 ${check2.targetId}`,
+    `**Overall Score:** ${check2.overallScore}/${CHECK_MAX_SCORES.beat_version_quality}`,
     `**Summary:** ${check2.summary}`,
     check2.topSuggestion ? `**Top Suggestion:** ${check2.topSuggestion}` : "",
     "",
@@ -28692,44 +28591,59 @@ ${d.rationale}${d.suggestions?.length ? `
   ].filter(Boolean).join("\n");
 }
 function registerPlanQualityTools(server, ctx, client) {
-  server.tool(
-    "check_plan_quality",
-    "Enqueue a plan quality check across 6 dimensions (Scoped, Directional, Testable, Traceable, Assignable, Risk-aware) on a Beat Version. plan_quality is a Beat-Version-only check \u2014 run it on a Beat Version before creating its first Revision (the first Revision is gated on a passing BV plan_quality check). For a Revision, run check_build_quality instead. By default returns a jobId immediately (fire-and-forget) \u2014 use get_job_status or list_checks to retrieve results. Set wait=true to block until the check completes and receive the scorecard inline. WARNING: wait=true holds the MCP session open for 30\u201360s per check \u2014 for bulk operations, omit wait and poll get_job_status separately to avoid session exhaustion.",
-    {
-      beatVersionId: external_exports.string().describe("The Beat Version ID (e.g., bv-abc123). plan_quality targets Beat Versions only."),
-      projectId: external_exports.string().describe("The project ID"),
-      wait: external_exports.boolean().optional().describe("If true, block until the check completes and return the scorecard inline. Default: false (returns taskId immediately).")
-    },
-    async ({ beatVersionId, projectId, wait }) => {
-      try {
-        if (!beatVersionId?.startsWith("bv-")) {
-          return {
-            content: [{
-              type: "text",
-              text: `Plan quality check failed: plan_quality runs only on Beat Versions (bv-*); got "${beatVersionId}". For a Revision, run check_build_quality on the Revision, or run check_plan_quality on its parent Beat Version.`
-            }],
-            isError: true
-          };
-        }
-        await assertProjectInOrg(client, projectId, ctx.orgId);
-        const task = await client.runCheck(projectId, "plan_quality", beatVersionId);
-        if (!wait) {
-          return {
-            content: [{
-              type: "text",
-              text: `Plan quality check enqueued for ${beatVersionId}.
+  const schema = {
+    beatVersionId: external_exports.string().describe("The Beat Version ID (e.g., bv-abc123). beat_version_quality targets Beat Versions only."),
+    projectId: external_exports.string().describe("The project ID"),
+    // The completeness dimension probes the codebase, so this tool accepts the
+    // same repo overrides as run_check — without them the probe could only ever
+    // read the default branch from this surface.
+    branch: external_exports.string().optional().describe("Override the git branch the completeness dimension probes (default: the branch of an open child Revision, else the project default branch)"),
+    localPath: external_exports.string().optional().describe("Absolute path to an already-cloned local copy of the repo \u2014 the completeness probe reads it instead of cloning"),
+    wait: external_exports.boolean().optional().describe("If true, block until the check completes and return the scorecard inline. Default: false (returns taskId immediately).")
+  };
+  const handler = async ({ beatVersionId, projectId, branch, localPath, wait }) => {
+    try {
+      const targetError = beatVersionQualityTargetError(beatVersionId ?? "");
+      if (targetError) {
+        return {
+          content: [{ type: "text", text: `Beat version quality check failed: ${targetError}` }],
+          isError: true
+        };
+      }
+      await assertProjectInOrg(client, projectId, ctx.orgId);
+      const opts = branch || localPath ? { branch, localPath } : void 0;
+      const task = await client.runCheck(projectId, "beat_version_quality", beatVersionId, opts);
+      if (!wait) {
+        return {
+          content: [{
+            type: "text",
+            text: `Beat version quality check enqueued for ${beatVersionId}.
 Job ID: ${task.taskId}
 
 Use get_job_status with jobId="${task.taskId}" to poll for results, or list_checks to retrieve the completed scorecard once done.`
-            }]
-          };
-        }
-        const check2 = await pollForCheck3(client, task.taskId);
-        return { content: [{ type: "text", text: formatScorecard2(check2) }] };
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return { content: [{ type: "text", text: `Plan quality check failed: ${message}` }], isError: true };
+          }]
+        };
       }
+      const check2 = await pollForCheck3(client, task.taskId);
+      return { content: [{ type: "text", text: formatScorecard2(check2) }] };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return { content: [{ type: "text", text: `Beat version quality check failed: ${message}` }], isError: true };
+    }
+  };
+  server.tool(
+    "check_beat_version_quality",
+    "Enqueue a Beat Version quality check across 7 dimensions (Scoped, Directional, Testable, Traceable, Assignable, Risk-aware, Completeness) on a Beat Version. beat_version_quality is a Beat-Version-only check \u2014 run it on a Beat Version before creating its first Revision (the first Revision is gated on a passing BV beat_version_quality check). For a Revision, run check_build_quality instead. By default returns a jobId immediately (fire-and-forget) \u2014 use get_job_status or list_checks to retrieve results. Set wait=true to block until the check completes and receive the scorecard inline. WARNING: wait=true holds the MCP session open for 30\u201360s per check \u2014 for bulk operations, omit wait and poll get_job_status separately to avoid session exhaustion.",
+    schema,
+    handler
+  );
+  server.tool(
+    "check_plan_quality",
+    "DEPRECATED \u2014 renamed to check_beat_version_quality (the check grades the Beat Version's planning increment: its plan dimensions and completeness against the codebase). This alias runs the same check and persists it as beat_version_quality. Prefer check_beat_version_quality.",
+    schema,
+    async (args) => {
+      console.warn("[deprecated-tool] check_plan_quality invoked \u2014 use check_beat_version_quality");
+      return handler(args);
     }
   );
 }
@@ -29499,6 +29413,103 @@ Error code: PR_NOT_DRAFT (the PR is already ready for review or was never a draf
   );
 }
 
+// ../../libs/harmonica-services/src/mcp/tools/revision-quality-tools.ts
+var POLL_INTERVAL_MS5 = 4e3;
+var POLL_TIMEOUT_MS5 = 18e4;
+var POLL_MAX_CONSECUTIVE_ERRORS5 = 3;
+async function pollForCheck5(client, taskId) {
+  const deadline = Date.now() + POLL_TIMEOUT_MS5;
+  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_ERRORS5)
+        throw new Error(`getTask failed ${consecutiveErrors} consecutive times: ${err instanceof Error ? err.message : String(err)}`);
+      await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS5));
+      continue;
+    }
+    if (!task) {
+      consecutiveErrors++;
+      if (consecutiveErrors >= POLL_MAX_CONSECUTIVE_ERRORS5)
+        throw new Error(`Task ${taskId} not found after ${consecutiveErrors} consecutive attempts`);
+      await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS5));
+      continue;
+    }
+    consecutiveErrors = 0;
+    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(`Revision quality check failed: ${task.error ?? "unknown error"}`);
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS5));
+  }
+  throw new Error(`Revision quality check timed out after ${POLL_TIMEOUT_MS5 / 1e3}s`);
+}
+function formatScorecard3(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");
+  return [
+    `## Revision Quality Check \u2014 ${check2.targetId}`,
+    `**Overall Score:** ${check2.overallScore}/${CHECK_MAX_SCORES.revision_quality}`,
+    `*(Advisory \u2014 no lifecycle gate reads this score)*`,
+    `**Summary:** ${check2.summary}`,
+    check2.topSuggestion ? `**Top Suggestion:** ${check2.topSuggestion}` : "",
+    "",
+    dims
+  ].filter(Boolean).join("\n");
+}
+function registerRevisionQualityTools(server, ctx, client) {
+  server.tool(
+    "check_revision_quality",
+    "Run a five-dimension PR-readiness check on a Revision (Scoped, Traceable, Testable, Review-ready, Non-duplicating). Advisory only \u2014 no lifecycle transition or creation path gates on this score. By default returns a jobId immediately (fire-and-forget) \u2014 use get_job_status or list_checks to retrieve results. Set wait=true to block until the check completes and receive the scorecard inline. WARNING: wait=true holds the MCP session open for 30\u201360s \u2014 for bulk operations, omit wait and poll get_job_status separately.",
+    {
+      revisionId: external_exports.string().describe("The Revision ID (e.g., rev-abc123). revision_quality targets Revisions only."),
+      projectId: external_exports.string().describe("The project ID"),
+      wait: external_exports.boolean().optional().describe("If true, block until the check completes and return the scorecard inline. Default: false (returns taskId immediately).")
+    },
+    async ({ revisionId, projectId, wait }) => {
+      try {
+        const targetError = revisionQualityTargetError(revisionId);
+        if (targetError) {
+          return {
+            content: [{ type: "text", text: `Revision quality check failed: ${targetError}` }],
+            isError: true
+          };
+        }
+        await assertProjectInOrg(client, projectId, ctx.orgId);
+        await assertRevisionInProject(client, revisionId, projectId);
+        const task = await client.runCheck(projectId, "revision_quality", revisionId);
+        if (!wait) {
+          return {
+            content: [{
+              type: "text",
+              text: `Revision quality check enqueued for ${revisionId}.
+Job ID: ${task.taskId}
+
+Use get_job_status with jobId="${task.taskId}" to poll for results, or list_checks to retrieve the completed scorecard once done.
+
+*(Advisory check \u2014 score does not gate any lifecycle transition.)*`
+            }]
+          };
+        }
+        const check2 = await pollForCheck5(client, task.taskId);
+        return { content: [{ type: "text", text: formatScorecard3(check2) }] };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Revision quality check failed: ${message}` }], isError: true };
+      }
+    }
+  );
+}
+
 // ../../libs/harmonica-services/src/mcp/tools/session-tools.ts
 var SESSION_STATUSES = ["active", "idle", "closed"];
 var SESSION_MESSAGE_MAX_LENGTH = 8e3;
@@ -29770,7 +29781,7 @@ var import_node_os = require("node:os");
 var import_node_path = require("node:path");
 
 // ../../libs/harmonica-services/src/system-snapshot.constants.ts
-var SNAPSHOT_VERSION = 4;
+var SNAPSHOT_VERSION = 6;
 
 // ../../libs/harmonica-services/src/mcp/tools/snapshot-tools.ts
 function registerSnapshotTools(server, ctx, client) {
@@ -29780,10 +29791,10 @@ function registerSnapshotTools(server, ctx, client) {
     { systemId: external_exports.string().describe("The system ID to export") },
     async ({ systemId }) => {
       await assertProjectInOrg(client, systemId, ctx.orgId);
-      const result = await client.exportProjectSnapshot(systemId);
+      const result = await client.exportSystemSnapshot(systemId);
       if (typeof result === "string") {
         if (!result.startsWith("https://")) {
-          throw new Error(`exportProjectSnapshot returned an unexpected string value (expected an https:// presigned URL): ${result.slice(0, 80)}`);
+          throw new Error(`exportSystemSnapshot returned an unexpected string value (expected an https:// presigned URL): ${result.slice(0, 80)}`);
         }
         return {
           content: [{
@@ -29821,6 +29832,10 @@ function registerSnapshotTools(server, ctx, client) {
         `  Layers: ${snapshot.layers?.length ?? 0}`,
         `  Tracks: ${snapshot.tracks?.length ?? 0}`,
         `  Work Items: ${snapshot.workItems?.length ?? 0}`,
+        `  Movements: ${snapshot.movements?.length ?? 0}`,
+        `  Bars: ${snapshot.bars?.length ?? 0}`,
+        `  Notebooks: ${snapshot.notebooks?.length ?? 0}`,
+        `  Accounts: ${(snapshot.account ? 1 : 0) + (snapshot.accounts?.length ?? 0)}`,
         "",
         "Use import_system_snapshot with this file path to import into another environment."
       ];
@@ -29834,9 +29849,12 @@ function registerSnapshotTools(server, ctx, client) {
       snapshot: external_exports.string().describe("S3 presigned URL (https://...), file path, or inline JSON string"),
       targetTeamspaceId: external_exports.string().min(1).optional().describe(
         "Remap all teamspace references (Drops, Deliverables, Project record) to this teamspace ID in the target environment. Required when the source and target environments use different teamspace UUIDs. When omitted and the snapshot contains Drops or Deliverables, a warning is included in the import summary."
+      ),
+      targetOrgId: external_exports.string().min(1).optional().describe(
+        "Import all records under this org ID instead of the caller's org. Required when syncing from production to a local environment where the org UUID differs. When omitted, the caller's org ID is used."
       )
     },
-    async ({ snapshot: snapshotInput, targetTeamspaceId }) => {
+    async ({ snapshot: snapshotInput, targetTeamspaceId, targetOrgId }) => {
       const isProduction = process.env.NODE_ENV === "production";
       const importAllowed = process.env.ALLOW_SYSTEM_IMPORT === "true";
       if (isProduction && !importAllowed) {
@@ -29849,7 +29867,7 @@ function registerSnapshotTools(server, ctx, client) {
         };
       }
       const trimmed = snapshotInput.trim();
-      const importOptions = { targetOrgId: ctx.orgId, targetUserId: ctx.user.userId, targetTeamspaceId };
+      const importOptions = { targetOrgId: targetOrgId ?? ctx.orgId, targetUserId: ctx.user.userId, targetTeamspaceId };
       if (trimmed.startsWith("https://")) {
         if (isPrivateHost(trimmed)) {
           throw new Error("Snapshot URL must point to a public host \u2014 private, link-local, and loopback addresses are not permitted.");
@@ -29919,7 +29937,8 @@ function normalizeSnapshot(raw) {
     trackSystemIndex: raw.trackSystemIndex ?? anyRaw["trackProjectIndex"] ?? [],
     trackTeamspaceIndex: raw.trackTeamspaceIndex ?? [],
     workItems: raw.workItems ?? [],
-    workItemIndex: raw.workItemIndex ?? []
+    workItemIndex: raw.workItemIndex ?? [],
+    accounts: raw.accounts ?? []
   };
 }
 async function resolveSnapshotInput(input) {
@@ -29946,7 +29965,11 @@ function formatImportSummary(result, targetTeamspaceId) {
     `  Teamspaces: ${result.counts.teamspaces ?? 0}`,
     `  Layers: ${result.counts.layers ?? 0}`,
     `  Tracks: ${result.counts.tracks ?? 0}`,
-    `  Work Items: ${result.counts.workItems ?? 0}`
+    `  Work Items: ${result.counts.workItems ?? 0}`,
+    `  Movements: ${result.counts.movements ?? 0}`,
+    `  Bars: ${result.counts.bars ?? 0}`,
+    `  Notebooks: ${result.counts.notebooks ?? 0}`,
+    `  Accounts: ${result.counts.accounts ?? 0}`
   ];
   if (result.errors.length > 0) {
     lines.push("", `Errors (${result.errors.length}):`);
@@ -31440,6 +31463,7 @@ function registerAllTools(server, ctx, client, profile) {
   registerSnapshotTools(server, ctx, client);
   registerBeatQualityTools(server, ctx, client);
   registerPlanQualityTools(server, ctx, client);
+  registerRevisionQualityTools(server, ctx, client);
   registerPortfolioCoherenceTools(server, ctx, client);
   registerDropQualityTools(server, ctx, client);
   registerBeatReframeTools(server, ctx, client);
@@ -31467,7 +31491,6 @@ function registerAllTools(server, ctx, client, profile) {
   registerNotebookTools(server, ctx, client);
   registerAccountTools(server, ctx, client);
   registerMovementTools(server, ctx, client);
-  registerMeasureTools(server, ctx, client);
   registerWorkItemTools(server, ctx, client);
   registerBarTools(server, ctx, client);
   registerCadenceScheduleTools(server, ctx, client);
@@ -31674,7 +31697,7 @@ function createHttpClient(config2) {
     }
     return result.edge;
   }
-  const POLL_INTERVAL_MS5 = 4e3;
+  const POLL_INTERVAL_MS6 = 4e3;
   async function pollTaskResult(taskId) {
     const deadline = Date.now() + LONG_RUNNING_TIMEOUT_MS;
     while (Date.now() < deadline) {
@@ -31684,7 +31707,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_MS5));
+      await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS6));
     }
     throw new Error(`Task ${taskId} timed out after ${LONG_RUNNING_TIMEOUT_MS}ms`);
   }
@@ -32010,6 +32033,7 @@ function createHttpClient(config2) {
       }
       if (filters?.status) params.set("status", filters.status);
       if (filters?.revisionId) params.set("revisionId", filters.revisionId);
+      if (filters?.beatVersionId) params.set("beatVersionId", filters.beatVersionId);
       if (filters?.excludeChildren) params.set("excludeChildren", "true");
       if (filters?.significance) params.set("significance", filters.significance);
       if (filters?.limit !== void 0) params.set("limit", String(filters.limit));
@@ -32025,6 +32049,7 @@ function createHttpClient(config2) {
       }
       if (filters?.status) params.set("status", filters.status);
       if (filters?.revisionId) params.set("revisionId", filters.revisionId);
+      if (filters?.beatVersionId) params.set("beatVersionId", filters.beatVersionId);
       if (filters?.excludeChildren) params.set("excludeChildren", "true");
       if (filters?.significance) params.set("significance", filters.significance);
       if (filters?.limit !== void 0) params.set("limit", String(filters.limit));
@@ -32041,6 +32066,7 @@ function createHttpClient(config2) {
       if (filters?.excludeNoteType) params.set("excludeType", filters.excludeNoteType);
       if (filters?.status) params.set("status", filters.status);
       if (filters?.revisionId) params.set("revisionId", filters.revisionId);
+      if (filters?.beatVersionId) params.set("beatVersionId", filters.beatVersionId);
       if (filters?.excludeChildren) params.set("excludeChildren", "true");
       if (filters?.significance) params.set("significance", filters.significance);
       if (limit !== void 0) params.set("limit", String(limit));
@@ -32059,6 +32085,7 @@ function createHttpClient(config2) {
       }
       if (filters?.status) params.set("status", filters.status);
       if (filters?.revisionId) params.set("revisionId", filters.revisionId);
+      if (filters?.beatVersionId) params.set("beatVersionId", filters.beatVersionId);
       if (filters?.excludeChildren) params.set("excludeChildren", "true");
       if (filters?.significance) params.set("significance", filters.significance);
       const qs = params.toString() ? `?${params.toString()}` : "";
@@ -32902,7 +32929,7 @@ function createHttpClient(config2) {
       return request("GET", `/api/subscriptions/entity/${encodeURIComponent(entityId)}`, void 0);
     },
     // Project Snapshot — export runs as a background task to avoid Lambda timeout
-    exportProjectSnapshot: async (projectId) => {
+    exportSystemSnapshot: async (projectId) => {
       const pid = encodeURIComponent(projectId);
       const enqueued = await request("POST", `/api/systems/${pid}/export`, {});
       if (!enqueued?.taskId) throw new Error("Export enqueue failed: no taskId returned");
@@ -33148,22 +33175,10 @@ function createHttpClient(config2) {
       const res = await request("GET", `/api/deliverable-groups/${encodeURIComponent(deliverableGroupId)}/drops`);
       return res?.drops ?? [];
     },
-    listDeliverableGroupBeatVersions: async (deliverableGroupId) => {
-      const res = await request("GET", `/api/deliverable-groups/${encodeURIComponent(deliverableGroupId)}/beat-versions`);
-      return res?.beatVersions ?? [];
-    },
-    setBeatVersionDeliverableGroup: async (deliverableGroupId, beatVersionId) => {
-      const res = await request("POST", `/api/deliverable-groups/${encodeURIComponent(deliverableGroupId)}/beat-versions`, { beatVersionId });
-      return res?.success === true;
-    },
     setDropDeliverableGroup: async (deliverableGroupId, dropId) => {
       const res = await request("POST", `/api/deliverable-groups/${encodeURIComponent(deliverableGroupId)}/drops`, { dropId });
       return res?.success === true;
     },
-    clearBeatVersionDeliverableGroup: async (deliverableGroupId, beatVersionId) => {
-      const res = await request("DELETE", `/api/deliverable-groups/${encodeURIComponent(deliverableGroupId)}/beat-versions/${encodeURIComponent(beatVersionId)}`);
-      return res?.success === true;
-    },
     // Movements (B-242 / teamspace-scoped SOW container)
     createMovement: async (input) => {
       const { teamspaceId, title, description, accountId } = input;
@@ -33209,73 +33224,6 @@ function createHttpClient(config2) {
       if (!parsed.success) throw new Error(`Unexpected movements list shape from API: ${parsed.error.message}`);
       return parsed.data.movements;
     },
-    // Measures (Measure exposure layer — atomic Work Plan unit under a Track).
-    // valueUnit is server-stripped for non-admins (N-4E09-6509) — the schema
-    // makes it optional; consumers must treat its absence as "not permitted".
-    createMeasure: async (input) => {
-      const { trackId, title, valueUnit, beatVersionId, createdBy } = input;
-      const body = {
-        title,
-        valueUnit,
-        ...beatVersionId !== void 0 && { beatVersionId },
-        ...createdBy !== void 0 && { createdBy }
-      };
-      const res = await request(
-        "POST",
-        `/api/deliverable-groups/${encodeURIComponent(trackId)}/measures`,
-        body
-      );
-      if (res === void 0) throw new Error(`Track ${trackId} not found`);
-      const parsed = MeasureApiSchema.safeParse(res.measure);
-      if (!parsed.success) throw new Error(`Unexpected Measure shape from API: ${parsed.error.message}`);
-      return parsed.data;
-    },
-    getMeasure: async (measureId) => {
-      const res = await request("GET", `/api/measures/${encodeURIComponent(measureId)}`);
-      if (res === void 0) return void 0;
-      const parsed = MeasureApiSchema.safeParse(res.measure);
-      if (!parsed.success) throw new Error(`Unexpected Measure shape from API: ${parsed.error.message}`);
-      return parsed.data;
-    },
-    updateMeasure: async (measureId, updates) => {
-      const res = await request("PATCH", `/api/measures/${encodeURIComponent(measureId)}`, updates);
-      if (res === void 0) return void 0;
-      const parsed = MeasureApiSchema.safeParse(res.measure);
-      if (!parsed.success) throw new Error(`Unexpected Measure shape from API: ${parsed.error.message}`);
-      return parsed.data;
-    },
-    listTrackMeasures: async (trackId) => {
-      const res = await request("GET", `/api/deliverable-groups/${encodeURIComponent(trackId)}/measures`);
-      if (res === void 0) throw new Error(`Track ${trackId} not found`);
-      const parsed = MeasuresResponseSchema.safeParse(res);
-      if (!parsed.success) throw new Error(`Unexpected measures list shape from API: ${parsed.error.message}`);
-      return parsed.data.measures;
-    },
-    listBeatVersionMeasures: async (beatVersionId) => {
-      const res = await request("GET", `/api/beat-versions/${encodeURIComponent(beatVersionId)}/measures`);
-      if (res === void 0) throw new Error(`Beat Version ${beatVersionId} not found`);
-      const parsed = MeasuresResponseSchema.safeParse(res);
-      if (!parsed.success) throw new Error(`Unexpected measures list shape from API: ${parsed.error.message}`);
-      return parsed.data.measures;
-    },
-    linkMeasureToBeatVersion: async (measureId, beatVersionId) => {
-      const res = await request(
-        "POST",
-        `/api/measures/${encodeURIComponent(measureId)}/beat-version`,
-        { beatVersionId }
-      );
-      if (res === void 0) return void 0;
-      const parsed = MeasureApiSchema.safeParse(res.measure);
-      if (!parsed.success) throw new Error(`Unexpected Measure shape from API: ${parsed.error.message}`);
-      return parsed.data;
-    },
-    unlinkMeasureFromBeatVersion: async (measureId) => {
-      const res = await request("DELETE", `/api/measures/${encodeURIComponent(measureId)}/beat-version`);
-      if (res === void 0) return void 0;
-      const parsed = MeasureApiSchema.safeParse(res.measure);
-      if (!parsed.success) throw new Error(`Unexpected Measure shape from API: ${parsed.error.message}`);
-      return parsed.data;
-    },
     // WorkItems (WorkItem exposure layer — owned, statused unit of operational work under a Track)
     createWorkItem: async (input) => {
       const { trackId, title, owner, committedEstimateHours, effortSize, valueUnits, costPerValueUnit, createdBy, beatVersionId } = input;
@@ -33828,7 +33776,7 @@ function loadConfig() {
   };
 }
 async function main() {
-  console.error(`[harmonica-mcp] v${"2.1.0"} starting\u2026`);
+  console.error(`[harmonica-mcp] v${"3.0.0"} starting\u2026`);
   const config2 = loadConfig();
   const client = createHttpClient({
     apiBaseUrl: config2.apiBaseUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codazen/harmonica-mcp",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "MCP server for Harmonica — connect any MCP-compatible AI assistant to Harmonica",
   "license": "MIT",
   "bin": {