@codazen/harmonica-mcp 3.3.0 → 3.5.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"
@@ -25204,6 +25231,208 @@ ${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 };
+      }
+    }
+  );
+  server.tool(
+    "create_flag",
+    "Create or update a feature flag with the specified enabled stages. Idempotent \u2014 calling with an existing flag name replaces its enabledIn list.",
+    {
+      name: external_exports.string().min(1).describe('Flag name (e.g. "rbac:enforcement")'),
+      enabledIn: external_exports.array(STAGE_ENUM).describe("Stages to enable the flag in"),
+      description: external_exports.string().optional().describe("Human-readable description of what this flag gates"),
+      note: external_exports.string().optional().describe("Reason for this change (recorded in change history)")
+    },
+    async ({ name, enabledIn, description, note }) => {
+      if (!ctx.user.email) {
+        return { content: [{ type: "text", text: "Write operations require an authenticated user with a valid email." }], isError: true };
+      }
+      try {
+        const flag = await client.createFlag(name, enabledIn, { description, note, updatedBy: ctx.user.email });
+        return { content: [{ type: "text", text: formatFlag(flag) }] };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Failed to create flag: ${message}` }], isError: true };
+      }
+    }
+  );
+  server.tool(
+    "set_flag",
+    "Update which stages a feature flag is enabled in. Replaces the current enabledIn list entirely.",
+    {
+      name: external_exports.string().min(1).describe("Flag name"),
+      enabledIn: external_exports.array(STAGE_ENUM).describe("New set of stages to enable the flag in. Pass [] to disable everywhere without archiving."),
+      note: external_exports.string().optional().describe("Reason for this change (recorded in change history)")
+    },
+    async ({ name, enabledIn, note }) => {
+      if (!ctx.user.email) {
+        return { content: [{ type: "text", text: "Write operations require an authenticated user with a valid email." }], isError: true };
+      }
+      try {
+        const flag = await client.setFlag(name, enabledIn, { note, updatedBy: ctx.user.email });
+        return { content: [{ type: "text", text: formatFlag(flag) }] };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Failed to set flag: ${message}` }], isError: true };
+      }
+    }
+  );
+  server.tool(
+    "archive_flag",
+    "Archive a feature flag. Clears its enabledIn list and marks it archived so it cannot be re-enabled via set_flag. Use unarchive_flag to restore it.",
+    {
+      name: external_exports.string().min(1).describe("Flag name"),
+      note: external_exports.string().optional().describe("Reason for archiving (recorded in change history)")
+    },
+    async ({ name, note }) => {
+      if (!ctx.user.email) {
+        return { content: [{ type: "text", text: "Write operations require an authenticated user with a valid email." }], isError: true };
+      }
+      try {
+        const flag = await client.archiveFlag(name, { note, updatedBy: ctx.user.email });
+        return { content: [{ type: "text", text: formatFlag(flag) }] };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Failed to archive flag: ${message}` }], isError: true };
+      }
+    }
+  );
+  server.tool(
+    "unarchive_flag",
+    "Restore an archived feature flag to operable state. The flag is re-enabled with an empty enabledIn list \u2014 use set_flag afterward to enable it in specific stages.",
+    {
+      name: external_exports.string().min(1).describe("Flag name"),
+      note: external_exports.string().optional().describe("Reason for restoring (recorded in change history)")
+    },
+    async ({ name, note }) => {
+      if (!ctx.user.email) {
+        return { content: [{ type: "text", text: "Write operations require an authenticated user with a valid email." }], isError: true };
+      }
+      try {
+        const flag = await client.unarchiveFlag(name, { note, updatedBy: ctx.user.email });
+        return { content: [{ type: "text", text: formatFlag(flag) }] };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Failed to unarchive 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}`,
+    flag.archivedAt ? `**Archived:** ${flag.archivedAt.slice(0, 10)} by ${flag.archivedBy}` : null
+  ].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(
@@ -27109,6 +27338,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 +27422,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 +27443,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 +27530,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 +27568,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);
@@ -29147,7 +29390,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 +29701,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 +29726,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 +29740,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 +29767,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 };
@@ -30349,7 +30639,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
@@ -30388,9 +30678,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"];
@@ -30452,7 +30740,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")'),
@@ -30472,7 +30760,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) {
@@ -30546,7 +30834,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")')
@@ -30594,7 +30882,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
@@ -31732,6 +32020,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
@@ -32094,11 +32383,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,
@@ -32299,6 +32600,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) {
@@ -32408,6 +32727,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
@@ -32974,6 +33294,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",
@@ -33298,6 +33632,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",
@@ -33616,6 +33957,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 ?? [];
@@ -34001,6 +34353,29 @@ function createHttpClient(config2) {
         `/api/notes/${encodeURIComponent(childNoteId)}/used-by`
       );
       return result?.usedBy;
+    },
+    // Feature flags (B-135 v9/v10) — 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");
+    },
+    createFlag: async () => {
+      throw new Error("Feature flag writes are not available in HTTP transport mode");
+    },
+    setFlag: async () => {
+      throw new Error("Feature flag writes are not available in HTTP transport mode");
+    },
+    archiveFlag: async () => {
+      throw new Error("Feature flag writes are not available in HTTP transport mode");
+    },
+    unarchiveFlag: async () => {
+      throw new Error("Feature flag writes are not available in HTTP transport mode");
     }
   };
   return client;
@@ -34051,7 +34426,7 @@ function loadConfig() {
   };
 }
 async function main() {
-  console.error(`[harmonica-mcp] v${"3.3.0"} starting\u2026`);
+  console.error(`[harmonica-mcp] v${"3.5.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.3.0",
+  "version": "3.5.0",
   "description": "MCP server for Harmonica — connect any MCP-compatible AI assistant to Harmonica",
   "license": "MIT",
   "bin": {