@codazen/harmonica-mcp 3.2.0 → 3.4.0

package/dist/index.js

@@ -21261,13 +21261,40 @@ var EMPTY_COMPLETION_RESULT = {
 };
 
 // ../../libs/harmonica-services/src/mcp/server-factory.ts
+var DELIVERY_LATITUDE_INSTRUCTIONS = `AGENT DELIVERY LATITUDE (CHECK BEFORE YOU ACT)
+
+Before you open a pull request, request the agent code review, or start watching
+a PR, resolve the delivery policy of the System the work belongs to and act on
+it. The policy hangs off the System and is reached through the Revision you are
+working \u2014 never through the repository, which may host many Systems.
+
+- \`get_revision\` returns the resolved policy as an "Agent Delivery Policy"
+  block, so the answer arrives in a call you were already making.
+- \`get_system_context\` carries the same block for a System you name directly.
+- For a doc-only or governance change that links a decision Note instead of a
+  Revision, \`get_note\` on that Note carries the block.
+
+Three independent toggles \u2014 openPullRequest, requestAgentReview,
+watchPullRequest:
+
+- true: perform the step, do not ask, and say that you did it.
+- false: do NOT perform it and do not ask either \u2014 say the System's policy has
+  it off, then move on. The tools also refuse a false step, including when you
+  pass confirm: true.
+- unset, or unresolvable for any reason: ASK a human. Nothing except an explicit
+  true is a grant, and every combination of the three is legitimate \u2014 never
+  infer one toggle from another.
+
+Re-read the policy before each step rather than caching it, so a human revoking
+a toggle mid-flight takes effect on your next action.`;
 async function createMcpServer(ctx, client, registerTools, registerResources) {
-  let instructions;
+  let guidelines;
   try {
-    instructions = await client.getBeatGuidelines();
+    guidelines = await client.getBeatGuidelines();
   } catch (err) {
     console.warn("[MCP] Failed to load beat guidelines for server instructions:", err);
   }
+  const instructions = [guidelines, DELIVERY_LATITUDE_INSTRUCTIONS].filter(Boolean).join("\n\n");
   const server = new McpServer({
     name: "harmonica",
     version: "0.1.0"
@@ -22524,7 +22551,7 @@ Use get_job_status with jobId="${taskId}" to poll for results, or list_checks to
   };
   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.",
+    "Enqueue a Beat definition quality check across 7 dimensions (Distinctive, Harmonious, Substantial, Durable, Clear, Strategically Aligned, Outcome-Oriented) \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
   );
@@ -25204,6 +25231,124 @@ ${members}${parent}`;
   );
 }
 
+// ../../libs/harmonica-services/src/mcp/tools/feature-flag-tools.ts
+var STAGE_ENUM = external_exports.enum([
+  "local",
+  "staging",
+  "staging-alpha",
+  "staging-beta",
+  "alpha",
+  "beta",
+  "prod"
+]);
+function registerFeatureFlagTools(server, _ctx, client) {
+  server.tool(
+    "list_flags",
+    "List feature flags and their enabled stages. Use check_flag to test a single flag against a specific stage, or get_flag for full detail on one flag.",
+    {
+      includeArchived: external_exports.boolean().optional().describe("Include archived flags. Default false"),
+      search: external_exports.string().optional().describe("Case-insensitive search against flag name and description"),
+      cursor: external_exports.string().optional().describe("Pagination cursor from a prior list_flags result"),
+      limit: external_exports.number().int().min(1).max(100).optional().describe("Flags per page. Default 20")
+    },
+    async ({ includeArchived, search, cursor, limit }) => {
+      try {
+        const page = await client.listFlags({ includeArchived, search, cursor, limit });
+        if (page.flags.length === 0) {
+          return { content: [{ type: "text", text: "No flags found." }] };
+        }
+        return { content: [{ type: "text", text: formatFlagList(page.flags, page.total, page.nextCursor) }] };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Failed to list flags: ${message}` }], isError: true };
+      }
+    }
+  );
+  server.tool(
+    "get_flag",
+    "Get full detail for a single feature flag by name, including its enabled stages and optional change history.",
+    {
+      name: external_exports.string().describe("Flag name"),
+      includeHistory: external_exports.boolean().optional().describe("Include change history entries. Default false")
+    },
+    async ({ name, includeHistory }) => {
+      try {
+        const flag = await client.getFlag(name, { includeHistory });
+        if (!flag) {
+          return { content: [{ type: "text", text: `Flag "${name}" not found.` }] };
+        }
+        return { content: [{ type: "text", text: formatFlag(flag, flag.history) }] };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Failed to get flag: ${message}` }], isError: true };
+      }
+    }
+  );
+  server.tool(
+    "check_flag",
+    "Check whether a feature flag is enabled in a specific stage. Returns a simple enabled/disabled answer.",
+    {
+      name: external_exports.string().describe("Flag name"),
+      stage: STAGE_ENUM.describe("Deployment stage to check against")
+    },
+    async ({ name, stage }) => {
+      try {
+        const enabled = await client.checkFlag(name, stage);
+        const status = enabled ? "enabled" : "disabled";
+        return {
+          content: [{
+            type: "text",
+            text: `Flag "${name}" is **${status}** in stage "${stage}".`
+          }]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Failed to check flag: ${message}` }], isError: true };
+      }
+    }
+  );
+}
+function formatFlag(flag, history) {
+  const archived = flag.archivedAt ? " **(archived)**" : "";
+  const enabled = flag.enabledIn.length > 0 ? flag.enabledIn.join(", ") : "(none)";
+  const parts = [
+    `# Flag: ${flag.name}${archived}`,
+    `**Scope:** ${flag.scope}`,
+    `**Enabled in:** ${enabled}`,
+    flag.description ? `**Description:** ${flag.description}` : null,
+    `**Last updated:** ${flag.updatedAt.slice(0, 10)} by ${flag.updatedBy}`
+  ].filter(Boolean).join("\n");
+  if (!history?.length) return parts;
+  const historyLines = history.map((h) => {
+    const prev = h.previousEnabledIn.length > 0 ? h.previousEnabledIn.join(", ") : "(none)";
+    const next = h.newEnabledIn.length > 0 ? h.newEnabledIn.join(", ") : "(none)";
+    const note = h.note ? ` \u2014 ${h.note}` : "";
+    return `- ${h.updatedAt.slice(0, 10)} ${h.updatedBy}: ${prev} \u2192 ${next}${note}`;
+  }).join("\n");
+  return `${parts}
+
+## Change History
+${historyLines}`;
+}
+function formatFlagList(flags, total, nextCursor) {
+  const rows = flags.map((f) => {
+    const enabled = f.enabledIn.length > 0 ? f.enabledIn.join(", ") : "(none)";
+    const archived = f.archivedAt ? " *(archived)*" : "";
+    return `| ${f.name}${archived} | ${enabled} | ${f.updatedAt.slice(0, 10)} |`;
+  });
+  const table = [
+    `# Feature Flags (${total} total, showing ${flags.length})`,
+    "",
+    "| Name | Enabled In | Updated |",
+    "|---|---|---|",
+    ...rows
+  ].join("\n");
+  if (!nextCursor) return table;
+  return `${table}
+
+More flags available. Pass \`cursor: "${nextCursor}"\` to list_flags to continue.`;
+}
+
 // ../../libs/harmonica-services/src/mcp/tools/layer-tools.ts
 function registerLayerTools(server, ctx, client) {
   server.tool(
@@ -25857,7 +26002,7 @@ var BEAT_QUALITY_DIMENSIONS = [
   "durable",
   "clear",
   "strategicallyAligned",
-  "businessOutcome"
+  "outcomeOriented"
 ];
 var BeatDimensionScoreSchema = external_exports.object({
   dimension: external_exports.enum(BEAT_QUALITY_DIMENSIONS),
@@ -27109,6 +27254,20 @@ var DISMISSED_NOTE_STATUS = "dismissed";
 var NOTE_TYPE_VALUES = ["context", "assumption", "constraint", "guidance", "decision", "document"];
 var NOTE_STATUS_VALUES = ["active", "unvalidated", "validated", "invalidated", "inProgress", "resolved", "superseded", "dismissed"];
 var DECISION_SIGNIFICANCE_VALUES2 = ["strategic", "structural", "implementation"];
+async function deliveryPolicyBlock(client, note) {
+  if (note.noteType !== "decision") return "";
+  try {
+    const resolution = await client.resolveDeliveryPolicyForNote(note.noteId);
+    return `
+
+${formatDeliveryPolicy(
+      resolution.resolved ? resolution.policy : void 0,
+      resolution.resolved ? void 0 : resolution.reason
+    )}`;
+  } catch {
+    return "";
+  }
+}
 function registerNoteTools(server, ctx, client) {
   server.tool(
     "list_notes",
@@ -27179,7 +27338,7 @@ function registerNoteTools(server, ctx, client) {
         const SOURCE_DOC_FETCH_LIMIT = 5e3;
         let allNotesResult;
         try {
-          allNotesResult = await client.listAllProjectNotes(projectId, filters, SOURCE_DOC_FETCH_LIMIT);
+          allNotesResult = await client.listAllSystemNotes(projectId, filters, SOURCE_DOC_FETCH_LIMIT);
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);
           return { content: [{ type: "text", text: `Failed to list project notes: ${message}` }], isError: true };
@@ -27200,7 +27359,7 @@ function registerNoteTools(server, ctx, client) {
       } else {
         let projectNotesResult;
         try {
-          projectNotesResult = await client.listAllProjectNotes(projectId, filters, limit, cursor);
+          projectNotesResult = await client.listAllSystemNotes(projectId, filters, limit, cursor);
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);
           return { content: [{ type: "text", text: `Failed to list project notes: ${message}` }], isError: true };
@@ -27287,7 +27446,7 @@ function registerNoteTools(server, ctx, client) {
     async ({ projectId }) => {
       await assertProjectInOrg(client, projectId, ctx.orgId);
       const DOCUMENT_FETCH_LIMIT = 5e3;
-      const { notes: docs, hasMore: truncated } = await client.listAllProjectNotes(projectId, { noteType: "document" }, DOCUMENT_FETCH_LIMIT);
+      const { notes: docs, hasMore: truncated } = await client.listAllSystemNotes(projectId, { noteType: "document" }, DOCUMENT_FETCH_LIMIT);
       const visibleDocs = docs.filter((d) => d.status !== DISMISSED_NOTE_STATUS);
       const truncationNotice = truncated && visibleDocs.length > 0 ? "\n\n> \u26A0\uFE0F This project has more than 5000 documents. Some documents may not be shown.\n" : "";
       const text = formatDocumentList(visibleDocs) + truncationNotice;
@@ -27325,7 +27484,7 @@ function registerNoteTools(server, ctx, client) {
         if (!note) {
           return { content: [{ type: "text", text: `Note not found: "${noteId}"` }], isError: true };
         }
-        const text = formatNoteDetail(note);
+        const text = formatNoteDetail(note) + await deliveryPolicyBlock(client, note);
         return { content: [{ type: "text", text }] };
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
@@ -28967,7 +29126,7 @@ function formatConsolidationResult(primaryId, primary, archivedBeatIds, notesRea
 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 business outcome score. By default returns a taskId immediately \u2014 set wait=true to block and receive the full report inline.",
+    "Run a portfolio coherence check on a project. Clusters Beats by semantic similarity to surface fragmentation (merge candidates) and checks what fraction of Beats name an outcome their authoriser would recognise. 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.")
@@ -29147,7 +29306,41 @@ function registerPulseReportTools(server, _ctx, client) {
   );
 }
 
+// ../../libs/harmonica-services/src/delivery-policy.decide.ts
+function decideDeliveryStep(resolution, step) {
+  if (!resolution.resolved) return "ask";
+  const value = resolution.policy[step];
+  if (value === true) return "proceed";
+  if (value === false) return "prohibited";
+  return "ask";
+}
+
 // ../../libs/harmonica-services/src/mcp/tools/revision-lifecycle-tools.ts
+async function checkDeliveryStep(client, revisionId, step) {
+  const resolution = await client.resolveDeliveryPolicy(revisionId).catch(() => ({ resolved: false, reason: "unreadable" }));
+  switch (decideDeliveryStep(resolution, step)) {
+    case "prohibited":
+      return {
+        refusal: `Refused: the System's delivery policy prohibits this step.
+
+**System:** ${resolution.resolved ? resolution.systemId : "unknown"}
+**Setting:** \`${step}\` is false
+
+This is a deliberate choice by whoever configured the System, and \`confirm: true\` does not override it. If it is wrong, a human changes it with \`update_system\` (\`agentDeliveryPolicy\`) \u2014 do not work around it.`
+      };
+    case "proceed":
+      return { notice: `Delivery policy for \`${step}\`: granted \u2014 no need to ask.` };
+    // 'ask' is named rather than left to `default:` so a fourth DeliveryDecision
+    // cannot silently inherit this wording. Both notices state the policy rather
+    // than what happened — they are also appended to responses where the action
+    // itself was a no-op (a dry run, or a gating feature flag being off).
+    case "ask":
+    default:
+      return {
+        notice: `Delivery policy for \`${step}\`: ${resolution.resolved ? "not set" : `unresolvable (${resolution.reason})`} \u2014 nothing blocks you, but ask a human before treating this as approved.`
+      };
+  }
+}
 function registerRevisionLifecycleTools(server, ctx, client) {
   server.tool(
     "create_revision",
@@ -29424,6 +29617,10 @@ Accepts the full PR metadata (number, url, branch, state, optional mergeSha). Fi
           return { content: [{ type: "text", text: `Revision not found: "${revisionId}"` }], isError: true };
         }
         await assertBeatInOrg(client, revision.beatId, ctx.orgId);
+        const latitude = await checkDeliveryStep(client, revisionId, "openPullRequest");
+        if ("refusal" in latitude) {
+          return { content: [{ type: "text", text: latitude.refusal }], isError: true };
+        }
         if (!confirm) {
           const shortId = revisionId.split("-").slice(0, 2).join("-");
           const lines2 = [
@@ -29445,6 +29642,7 @@ Accepts the full PR metadata (number, url, branch, state, optional mergeSha). Fi
               );
             }
           }
+          lines2.push("", latitude.notice);
           return { content: [{ type: "text", text: lines2.join("\n") }] };
         }
         const result = await client.createPrForRevision(revisionId);
@@ -29458,7 +29656,9 @@ Accepts the full PR metadata (number, url, branch, state, optional mergeSha). Fi
           `**PR:** #${result.result.prNumber} \u2014 ${result.result.prUrl}`,
           `**Branch:** ${result.result.branch}`,
           "",
-          "The revision stays in `draft`. Transition it to `open` once the PR is marked ready for review."
+          "The revision stays in `draft`. Transition it to `open` once the PR is marked ready for review.",
+          "",
+          latitude.notice
         ];
         return { content: [{ type: "text", text: lines.join("\n") }] };
       } catch (err) {
@@ -29483,11 +29683,17 @@ Accepts the full PR metadata (number, url, branch, state, optional mergeSha). Fi
           return { content: [{ type: "text", text: `Revision not found: "${revisionId}"` }], isError: true };
         }
         await assertBeatInOrg(client, revision.beatId, ctx.orgId);
+        const latitude = await checkDeliveryStep(client, revisionId, "requestAgentReview");
+        if ("refusal" in latitude) {
+          return { content: [{ type: "text", text: latitude.refusal }], isError: true };
+        }
         const result = await client.requestCodeReview({ revisionId, autoMerge, maxIterations, confirm });
         if (!result.success) {
           return { content: [{ type: "text", text: `Failed to request code review (${result.error.code}): ${result.error.message}` }], isError: true };
         }
-        return { content: [{ type: "text", text: result.result.message }] };
+        return { content: [{ type: "text", text: `${result.result.message}
+
+${latitude.notice}` }] };
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         return { content: [{ type: "text", text: `Failed to request code review: ${message}` }], isError: true };
@@ -30166,6 +30372,9 @@ async function resolveSnapshotInput(input) {
   return trimmed;
 }
 function formatImportSummary(result, targetTeamspaceId) {
+  if (!result.counts || result.counts.beats == null) {
+    throw new Error(`Import of system ${result.projectId} completed but returned no counts \u2014 check worker logs for a TransactionCanceledException`);
+  }
   const lines = [
     `Imported system: ${result.projectId}`,
     `  Beats: ${result.counts.beats}`,
@@ -30346,7 +30555,7 @@ function registerProjectLifecycleTools(server, ctx, client) {
         if (system.orgId !== ctx.orgId) {
           return { content: [{ type: "text", text: `System "${systemId}" is not in this organization` }], isError: true };
         }
-        const result = await client.transitionProjectLifecycleState(systemId, targetState, {
+        const result = await client.transitionSystemLifecycleState(systemId, targetState, {
           actor: { type: "human", id: ctx.user.userId, name: ctx.user.name },
           reason,
           decisionNoteId
@@ -30385,9 +30594,7 @@ function normalizeCreateAccountId(accountId) {
 }
 
 // ../../libs/harmonica-services/src/mcp/tools/system-tools.ts
-function accountLine(request, resolved) {
-  const requested = request["accountId"];
-  if (requested === null || requested === "") return "**Account:** (unlinked)";
+function accountLine(_request, resolved) {
   return resolved ? `**Account:** ${resolved}` : "";
 }
 var PROJECT_EMBEDDING_FIELDS = ["title", "description", "strategy"];
@@ -30449,7 +30656,7 @@ function registerProjectTools(server, ctx, client) {
     description: external_exports.string().optional().describe("New system description"),
     strategy: external_exports.string().optional().describe('System strategy markdown \u2014 Org Strategy + System Strategy ("System Coda")'),
     teamspaceId: external_exports.string().nullable().optional().describe("Teamspace ID to associate this system with; pass null to remove the association"),
-    accountId: external_exports.string().nullable().optional().describe("Account that owns this System \u2014 the client or internal org unit. Pass null (or an empty string) to unlink. Reassigning moves the System so it is listed under exactly one Account."),
+    accountId: external_exports.string().min(1).optional().describe("Account that owns this System \u2014 the client or internal org unit. Omit to leave unchanged. A System cannot be unlinked: reassigning moves it so it is listed under exactly one Account."),
     repoOwner: external_exports.string().optional().describe("GitHub repository owner (org or user)"),
     repoName: external_exports.string().optional().describe("GitHub repository name"),
     repoDefaultBranch: external_exports.string().optional().describe('Default branch for code check (defaults to "main")'),
@@ -30469,7 +30676,7 @@ function registerProjectTools(server, ctx, client) {
         return { content: [{ type: "text", text: "No updates provided." }], isError: true };
       }
       await assertProjectInOrg(client, systemId, ctx.orgId);
-      if (nonEmpty["accountId"] === "") nonEmpty["accountId"] = null;
+      if (nonEmpty["accountId"] === "") delete nonEmpty["accountId"];
       if (typeof updates.teamspaceId === "string") {
         const teamspace = await client.getTeamspace(updates.teamspaceId);
         if (!teamspace) {
@@ -30543,7 +30750,7 @@ function registerProjectTools(server, ctx, client) {
     description: external_exports.string().optional().describe("System description"),
     strategy: external_exports.string().optional().describe('System strategy markdown \u2014 Org Strategy + System Strategy ("System Coda")'),
     teamspaceId: external_exports.string().optional().describe("Teamspace ID to associate this system with"),
-    accountId: external_exports.string().optional().describe("Account that owns this System \u2014 the client or internal org unit. Set it at creation so the System appears in the Account's Systems list; omit only for a System that belongs to no Account."),
+    accountId: external_exports.string().min(1).describe("Account that owns this System \u2014 the client or internal org unit. REQUIRED: the Account is the only parent access follows, so a System without one is reachable by nobody."),
     repoOwner: external_exports.string().optional().describe("GitHub repository owner (org or user)"),
     repoName: external_exports.string().optional().describe("GitHub repository name"),
     repoDefaultBranch: external_exports.string().optional().describe('Default branch for code check (defaults to "main")')
@@ -30591,7 +30798,7 @@ function registerProjectTools(server, ctx, client) {
       return { content: [{ type: "text", text: `Failed to create system: ${message}` }], isError: true };
     }
   };
-  server.tool("create_system", "Create a new system in the configured organization. Pass accountId whenever the system belongs to a client \u2014 a system created without it is not listed under any Account.", createSystemSchema, createSystemHandler);
+  server.tool("create_system", "Create a new system in the configured organization. accountId is required \u2014 it is the Account that owns the System, and the only parent access follows.", createSystemSchema, createSystemHandler);
 }
 
 // ../../libs/harmonica-services/src/mcp/tools/teamspace-tools.ts
@@ -31729,6 +31936,7 @@ function registerAllTools(server, ctx, client, profile) {
   registerCadenceScheduleTools(server, ctx, client);
   registerPulseReportTools(server, ctx, client);
   registerDownbeatHarmonyReportTools(server, ctx, client);
+  registerFeatureFlagTools(server, ctx, client);
 }
 
 // ../../libs/harmonica-services/src/mcp/resources/beat-resources.ts
@@ -32091,11 +32299,23 @@ function createHttpClient(config2) {
     },
     updateProject: (projectId, updates) => request("PATCH", `/api/systems/${encodeURIComponent(projectId)}`, updates),
     archiveProject: (projectId) => request("PATCH", `/api/systems/${encodeURIComponent(projectId)}/archive`),
+    getSystemFact: async (projectId) => {
+      const result = await request("GET", `/api/systems/${encodeURIComponent(projectId)}/facts`);
+      return result?.data;
+    },
     getProjectFact: async (projectId) => {
       const result = await request("GET", `/api/systems/${encodeURIComponent(projectId)}/facts`);
       return result?.data;
     },
+    saveSystemFact: (input) => request("PUT", `/api/systems/${encodeURIComponent(String(input.projectId))}/facts`, input),
     saveProjectFact: (input) => request("PUT", `/api/systems/${encodeURIComponent(String(input.projectId))}/facts`, input),
+    transitionSystemLifecycleState: async (projectId, targetState, options) => {
+      return request("POST", `/api/systems/${encodeURIComponent(projectId)}/lifecycle/transitions`, {
+        targetState,
+        reason: options.reason,
+        decisionNoteId: options.decisionNoteId
+      });
+    },
     transitionProjectLifecycleState: async (projectId, targetState, options) => {
       return request("POST", `/api/systems/${encodeURIComponent(projectId)}/lifecycle/transitions`, {
         targetState,
@@ -32296,6 +32516,24 @@ function createHttpClient(config2) {
       const result = await request("GET", `/api/systems/${encodeURIComponent(projectId)}/notes${qs}`);
       return result?.notes ?? [];
     },
+    listAllSystemNotes: async (projectId, filters, limit, cursor) => {
+      const params = new URLSearchParams();
+      if (filters?.noteType) {
+        const types = Array.isArray(filters.noteType) ? filters.noteType : [filters.noteType];
+        types.forEach((t) => params.append("type", t));
+      }
+      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));
+      if (cursor !== void 0) params.set("cursor", cursor);
+      const qs = params.toString() ? `?${params.toString()}` : "";
+      const result = await request("GET", `/api/systems/${encodeURIComponent(projectId)}/notes/all${qs}`);
+      return { notes: result?.notes ?? [], cursor: result?.cursor, hasMore: result?.hasMore ?? false };
+    },
     listAllProjectNotes: async (projectId, filters, limit, cursor) => {
       const params = new URLSearchParams();
       if (filters?.noteType) {
@@ -32405,6 +32643,7 @@ function createHttpClient(config2) {
       return result?.note ?? result;
     },
     // Gaps are deprecated — replaced by assumption Notes. Return empty results.
+    getSystemGaps: async () => [],
     getProjectGaps: async () => [],
     updateInformationGap: async () => false,
     // Revisions
@@ -32971,6 +33210,20 @@ function createHttpClient(config2) {
       );
       return result.score;
     },
+    rankSystemBeatVersions: async (projectId, lens) => {
+      const result = await request(
+        "GET",
+        `/api/systems/${encodeURIComponent(projectId)}/beat-versions/ranked?lens=${encodeURIComponent(lens)}`
+      );
+      return result.ranked ?? [];
+    },
+    rankSystemBeatVersionsWithLeverage: async (projectId, lens) => {
+      const result = await request(
+        "GET",
+        `/api/systems/${encodeURIComponent(projectId)}/beat-versions/ranked?lens=${encodeURIComponent(lens)}&withLeverage=true`
+      );
+      return result.ranked ?? [];
+    },
     rankProjectBeatVersions: async (projectId, lens) => {
       const result = await request(
         "GET",
@@ -33202,7 +33455,9 @@ function createHttpClient(config2) {
       if (!enqueued?.taskId) {
         throw new Error("importSystemSnapshotFromUrl: API did not return a taskId");
       }
-      return pollTaskResult(enqueued.taskId);
+      const importResult = await pollTaskResult(enqueued.taskId);
+      if (importResult == null) throw new Error(`Task ${enqueued.taskId} completed but returned no result \u2014 check worker logs for a TransactionCanceledException`);
+      return importResult;
     },
     // Embedding similarity
     embedProjectEntities: (projectId) => request("POST", `/api/systems/${encodeURIComponent(projectId)}/embeddings/generate`),
@@ -33293,6 +33548,13 @@ function createHttpClient(config2) {
       );
       return { checks: res?.checks ?? [], nextCursor: res?.nextCursor };
     },
+    listLatestSystemChecks: async (projectId) => {
+      const res = await request(
+        "GET",
+        `/api/checks/latest?projectId=${encodeURIComponent(projectId)}`
+      );
+      return res?.checks ?? [];
+    },
     listLatestProjectChecks: async (projectId) => {
       const res = await request(
         "GET",
@@ -33611,6 +33873,17 @@ function createHttpClient(config2) {
       if (!res) return { resolved: false, reason: "revision_not_found" };
       return res;
     },
+    // Mirrors the Revision route. A 404 becomes note_not_found rather than
+    // revision_not_found: reporting the wrong missing entity sends a human
+    // looking for something that was never involved.
+    resolveDeliveryPolicyForNote: async (noteId) => {
+      const res = await request(
+        "GET",
+        `/api/notes/${encodeURIComponent(noteId)}/delivery-policy`
+      );
+      if (!res) return { resolved: false, reason: "note_not_found" };
+      return res;
+    },
     listAccountSystems: async (accountId) => {
       const res = await request("GET", `/api/accounts/${encodeURIComponent(accountId)}/systems`);
       return res?.systems ?? [];
@@ -33996,6 +34269,17 @@ function createHttpClient(config2) {
         `/api/notes/${encodeURIComponent(childNoteId)}/used-by`
       );
       return result?.usedBy;
+    },
+    // Feature flags (B-135 v9) — not available in HTTP transport; the published
+    // npm package has no DynamoDB credentials.
+    listFlags: async () => {
+      throw new Error("Feature flag queries are not available in HTTP transport mode");
+    },
+    getFlag: async () => {
+      throw new Error("Feature flag queries are not available in HTTP transport mode");
+    },
+    checkFlag: async () => {
+      throw new Error("Feature flag queries are not available in HTTP transport mode");
     }
   };
   return client;
@@ -34046,7 +34330,7 @@ function loadConfig() {
   };
 }
 async function main() {
-  console.error(`[harmonica-mcp] v${"3.2.0"} starting\u2026`);
+  console.error(`[harmonica-mcp] v${"3.4.0"} starting\u2026`);
   const config2 = loadConfig();
   const client = createHttpClient({
     apiBaseUrl: config2.apiBaseUrl,

package/package.json

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