metheus-governance-mcp-cli 0.2.8 → 0.2.10

package/README.md

@@ -17,7 +17,7 @@ Compatibility note: legacy command alias `metheus-governance-mcp` is still suppo
 ## Install
 
 ```bash
-npm install -g metheus-governance-mcp-cli
+npm install -g metheus-governance-mcp-cli@latest
 ```
 
 ## One command bootstrap (recommended)
@@ -61,6 +61,8 @@ Local bootstrap tools exposed by proxy:
 - `project.summary`
 - `project.describe` (alias)
 - `project.get` (alias)
+- `ctxpack.merge.brief`
+- `ctxpack.merge.execute`
 
 These tools accept `project_id` and return:
 
@@ -74,6 +76,12 @@ These tools accept `project_id` and return:
 - newer server version -> update local cache
 - workspace path -> follows active client workspace/root when provided by Codex/Claude
 
+Ctxpack merge safety flow:
+- call `ctxpack.merge.brief` first
+- review who changed what (`created_by`, `changed_paths`, metadata summary)
+- get explicit owner decision in chat
+- then call `ctxpack.merge.execute` with `owner_confirmation`
+
 Manual ctxpack pull/update:
 
 ```bash

package/cli.mjs

@@ -140,11 +140,41 @@ function firstNonEmptyString(values) {
   return "";
 }
 
+function extractWorkspaceCandidateFromFolders(rawFolders) {
+  if (!Array.isArray(rawFolders)) return "";
+  for (const folder of rawFolders) {
+    if (typeof folder === "string") {
+      const direct = firstNonEmptyString([fileURIToLocalPath(folder), folder]);
+      if (direct) return resolveWorkspaceDir(direct);
+      continue;
+    }
+    if (!folder || typeof folder !== "object" || Array.isArray(folder)) continue;
+    const uriValue = firstNonEmptyString([
+      folder.uri,
+      folder.root_uri,
+      folder.rootUri,
+      folder.path,
+      folder.root_path,
+      folder.rootPath,
+    ]);
+    const candidate = firstNonEmptyString([fileURIToLocalPath(uriValue), uriValue]);
+    if (candidate) return resolveWorkspaceDir(candidate);
+  }
+  return "";
+}
+
 function extractWorkspaceCandidateFromRequest(requestObj, toolArgs) {
   const params = safeObject(requestObj?.params);
   const meta = safeObject(params._meta);
+  const workspaceFromFolders = firstNonEmptyString([
+    extractWorkspaceCandidateFromFolders(params.workspace_folders),
+    extractWorkspaceCandidateFromFolders(params.workspaceFolders),
+    extractWorkspaceCandidateFromFolders(meta.workspace_folders),
+    extractWorkspaceCandidateFromFolders(meta.workspaceFolders),
+  ]);
   const args = safeObject(toolArgs);
   const rawCandidate = firstNonEmptyString([
+    workspaceFromFolders,
     args.workspace_dir,
     args.workspaceDir,
     params.workspace_dir,
@@ -172,10 +202,12 @@ function extractWorkspaceCandidateFromEnv() {
   const rawCandidate = firstNonEmptyString([
     process.env.METHEUS_WORKSPACE_DIR,
     process.env.CLAUDE_WORKSPACE_DIR,
+    process.env.CLAUDE_WORKSPACE_URI,
     process.env.CLAUDE_PROJECT_DIR,
     process.env.CODEX_WORKSPACE_DIR,
     process.env.WORKSPACE_DIR,
     process.env.WORKSPACE_FOLDER,
+    process.env.VSCODE_WORKSPACE_FOLDER,
     process.env.VSCODE_CWD,
     process.env.PWD,
     process.env.INIT_CWD,
@@ -198,6 +230,25 @@ function resolveWorkspaceDirForRequest(defaultWorkspaceDir, requestObj, toolArgs
   return resolveWorkspaceDir(candidate);
 }
 
+function resolveProjectIDForRequest({
+  toolArgs,
+  args,
+  workspaceDir,
+  responseProjectID,
+  envelopeProjectID,
+}) {
+  const resolvedWorkspaceDir = resolveWorkspaceDir(workspaceDir || process.cwd());
+  const workspaceMeta = loadWorkspaceMeta(resolvedWorkspaceDir);
+  return firstNonEmptyString([
+    toolArgs?.project_id,
+    toolArgs?.projectID,
+    responseProjectID,
+    envelopeProjectID,
+    workspaceMeta.project_id,
+    args?.projectID,
+  ]);
+}
+
 function homeCtxpackCacheRootDir() {
   const home = String(process.env.USERPROFILE || process.env.HOME || "").trim();
   if (!home) {
@@ -1411,6 +1462,19 @@ function addDoctorCheck(rows, status, label, detail) {
   });
 }
 
+function isUnauthorizedLike(rawText) {
+  const text = String(rawText || "").trim().toLowerCase();
+  if (!text) return false;
+  return (
+    text.includes("unauthorized") ||
+    text.includes("access denied") ||
+    text.includes("status 401") ||
+    text.includes("status 403") ||
+    text.includes("http 401") ||
+    text.includes("http 403")
+  );
+}
+
 function statusIcon(status) {
   if (status === "ok") return "OK";
   if (status === "fail") return "FAIL";
@@ -1695,12 +1759,25 @@ async function runDoctor(flags) {
         addDoctorCheck(rows, "ok", "server mode", "ctxpack writable");
       }
     } catch (err) {
-      addDoctorCheck(
-        rows,
-        "warn",
-        "server ctxpack policy",
-        `unable to read /ctxpack/stats (${String(err?.message || err)})`,
-      );
+      const statusCode = Number(err?.statusCode || 0);
+      const message = String(err?.message || err);
+      if (statusCode === 404) {
+        addDoctorCheck(
+          rows,
+          "ok",
+          "server ctxpack policy",
+          "ctxpack/stats endpoint is not exposed in this deployment (optional check skipped)",
+        );
+      } else if (statusCode === 401 || statusCode === 403 || isUnauthorizedLike(message)) {
+        addDoctorCheck(
+          rows,
+          "warn",
+          "server ctxpack policy",
+          "no permission to read ctxpack/stats in this environment",
+        );
+      } else {
+        addDoctorCheck(rows, "warn", "server ctxpack policy", `unable to read /ctxpack/stats (${message})`);
+      }
     }
   }
 
@@ -1736,7 +1813,17 @@ async function runDoctor(flags) {
       },
     });
     if (!rpc.ok) {
-      addDoctorCheck(rows, "fail", `smoke ${row.tool}`, rpc.error || "rpc error");
+      const errorText = String(rpc.error || "rpc error");
+      if (isUnauthorizedLike(errorText)) {
+        addDoctorCheck(
+          rows,
+          "warn",
+          `smoke ${row.tool}`,
+          "unauthorized for this tool with current token/project role",
+        );
+      } else {
+        addDoctorCheck(rows, "fail", `smoke ${row.tool}`, errorText);
+      }
       continue;
     }
     const envelope = parseToolEnvelopeFromRPCResult(safeObject(rpc.response).result);
@@ -1749,12 +1836,21 @@ async function runDoctor(flags) {
     if (ok && status >= 200 && status < 300) {
       addDoctorCheck(rows, "ok", `smoke ${row.tool}`, `status ${status}`);
     } else {
-      addDoctorCheck(
-        rows,
-        "fail",
-        `smoke ${row.tool}`,
-        `status ${status || "-"}, ok=${ok ? "true" : "false"}`,
-      );
+      if (status === 401 || status === 403) {
+        addDoctorCheck(
+          rows,
+          "warn",
+          `smoke ${row.tool}`,
+          `status ${status}: unauthorized for this tool with current token/project role`,
+        );
+      } else {
+        addDoctorCheck(
+          rows,
+          "fail",
+          `smoke ${row.tool}`,
+          `status ${status || "-"}, ok=${ok ? "true" : "false"}`,
+        );
+      }
     }
   }
 
@@ -1801,7 +1897,10 @@ function postJSON(urlText, timeoutSeconds, token, payload) {
             resolve(text.trim());
             return;
           }
-          reject(new Error(text.trim() || `http ${statusCode}`));
+          const err = new Error(text.trim() || `http ${statusCode}`);
+          err.statusCode = statusCode;
+          err.responseBody = text;
+          reject(err);
         });
       },
     );
@@ -1887,6 +1986,7 @@ function jsonRpcResult(requestObj, result) {
 }
 
 const LOCAL_PROJECT_TOOL_NAMES = ["project.summary", "project.describe", "project.get"];
+const LOCAL_CTXPACK_MERGE_TOOL_NAMES = ["ctxpack.merge.brief", "ctxpack.merge.execute"];
 
 function buildProjectSummaryInputSchema() {
   return {
@@ -1910,6 +2010,62 @@ function buildProjectSummaryInputSchema() {
   };
 }
 
+function buildCtxpackMergeBriefInputSchema() {
+  return {
+    type: "object",
+    properties: {
+      project_id: {
+        type: "string",
+        description: "Project UUID. If omitted, current configured project_id is used.",
+      },
+      status: {
+        type: "string",
+        description: "Merge-request status filter. Default: open.",
+        enum: ["open", "review", "approved", "rejected", "merged", "closed", "all"],
+      },
+      limit: {
+        type: "integer",
+        minimum: 1,
+        maximum: 100,
+        description: "Maximum merge requests to inspect. Default: 20.",
+      },
+    },
+    additionalProperties: false,
+  };
+}
+
+function buildCtxpackMergeExecuteInputSchema() {
+  return {
+    type: "object",
+    properties: {
+      project_id: {
+        type: "string",
+        description: "Project UUID. If omitted, current configured project_id is used.",
+      },
+      merge_request_id: {
+        type: "string",
+        description: "Target merge request UUID.",
+      },
+      action: {
+        type: "string",
+        description: "Action to execute.",
+        enum: ["review", "approve", "reject", "close", "merge"],
+      },
+      owner_confirmation: {
+        type: "string",
+        description:
+          "Explicit owner confirmation text from chat (for safety). Example: confirm / approved / yes.",
+      },
+      note: {
+        type: "string",
+        description: "Optional reviewer note recorded in metadata for non-merge actions.",
+      },
+    },
+    required: ["merge_request_id", "action", "owner_confirmation"],
+    additionalProperties: false,
+  };
+}
+
 function buildLocalToolSpecs() {
   return [
     {
@@ -1930,6 +2086,18 @@ function buildLocalToolSpecs() {
         "Alias of project.summary. Returns project metadata and access status for the given project_id.",
       inputSchema: buildProjectSummaryInputSchema(),
     },
+    {
+      name: "ctxpack.merge.brief",
+      description:
+        "Before merge, summarize pending ctxpack merge requests (who changed what), show risk/recommendation, and provide owner confirmation checklist.",
+      inputSchema: buildCtxpackMergeBriefInputSchema(),
+    },
+    {
+      name: "ctxpack.merge.execute",
+      description:
+        "Execute ctxpack merge-request action (review/approve/reject/close/merge) after explicit owner confirmation.",
+      inputSchema: buildCtxpackMergeExecuteInputSchema(),
+    },
   ];
 }
 
@@ -2233,6 +2401,10 @@ async function loadProjectSummaryForTool({
     visibility: String(project.visibility || "").trim() || "private",
     template: String(project.template || "").trim() || "blank",
     template_label: normalizeTemplateLabel(project.template),
+    owner_user_id: String(project.owner_user_id || "").trim(),
+    program_owner_user_id: String(project.program_owner_user_id || "").trim(),
+    tech_owner_user_id: String(project.tech_owner_user_id || "").trim(),
+    governance_owner_user_id: String(project.governance_owner_user_id || "").trim(),
     owner_name: String(project.owner_name || "").trim(),
     program_owner_name: String(project.program_owner_name || "").trim(),
     tech_owner_name: String(project.tech_owner_name || "").trim(),
@@ -2255,6 +2427,522 @@ async function loadProjectSummaryForTool({
   };
 }
 
+function normalizeMergeStatusFilter(rawValue) {
+  const value = String(rawValue || "").trim().toLowerCase();
+  if (!value) return "open";
+  if (["open", "review", "approved", "rejected", "merged", "closed", "all"].includes(value)) {
+    return value;
+  }
+  return "";
+}
+
+function normalizeMergeAction(rawValue) {
+  const value = String(rawValue || "").trim().toLowerCase();
+  if (["review", "approve", "reject", "close", "merge"].includes(value)) {
+    return value;
+  }
+  return "";
+}
+
+function parseMergeMetadata(rawMetadata) {
+  if (!rawMetadata) return {};
+  if (typeof rawMetadata === "object" && !Array.isArray(rawMetadata)) {
+    return rawMetadata;
+  }
+  if (typeof rawMetadata !== "string") return {};
+  try {
+    const parsed = JSON.parse(rawMetadata);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    return parsed;
+  } catch {
+    return {};
+  }
+}
+
+function collectMergeChangedPaths(metadataObj) {
+  const meta = safeObject(metadataObj);
+  const out = [];
+  const pushPath = (raw) => {
+    const value = String(raw || "").trim();
+    if (!value) return;
+    if (!out.includes(value)) out.push(value);
+  };
+  for (const pathValue of ensureArray(meta.changed_paths)) {
+    pushPath(pathValue);
+  }
+  for (const pathValue of ensureArray(meta.conflict_paths)) {
+    pushPath(pathValue);
+  }
+  const files = ensureArray(meta.files);
+  for (const file of files) {
+    pushPath(safeObject(file).path);
+  }
+  const changeSet = safeObject(meta.change_set);
+  const changeSetFiles = ensureArray(changeSet.files);
+  for (const file of changeSetFiles) {
+    pushPath(safeObject(file).path);
+  }
+  return out;
+}
+
+function summarizeMergeMetadata(metadataObj) {
+  const meta = safeObject(metadataObj);
+  const parts = [];
+  const changeSet = safeObject(meta.change_set);
+  const summary = safeObject(changeSet.summary);
+  const changedCount = Number.parseInt(String(summary.changed || 0), 10);
+  if (Number.isFinite(changedCount) && changedCount > 0) {
+    parts.push(`changed files: ${changedCount}`);
+  }
+  const title = String(meta.title || meta.summary || meta.reason || "").trim();
+  if (title) {
+    parts.push(title);
+  }
+  if (!parts.length) return "";
+  return parts.join(" | ");
+}
+
+function parseISOTime(rawValue) {
+  const text = String(rawValue || "").trim();
+  if (!text) return 0;
+  const ms = Date.parse(text);
+  if (!Number.isFinite(ms)) return 0;
+  return ms;
+}
+
+function extractActorFromToken(token) {
+  const payload = safeObject(decodeJwtPayload(token));
+  const userID = firstNonEmptyString([payload.sub, payload.user_id, payload.uid]);
+  const email = firstNonEmptyString([payload.email, payload.preferred_username]);
+  const name = firstNonEmptyString([payload.name, payload.given_name]);
+  return { user_id: userID, email, name };
+}
+
+async function loadProjectMemberMap({ siteBaseURL, projectID, token, timeoutSeconds }) {
+  const encodedProjectID = encodeURIComponent(projectID);
+  try {
+    const raw = await getJSONWithAuth(
+      `${siteBaseURL}/api/v1/projects/${encodedProjectID}/members?limit=500&offset=0`,
+      timeoutSeconds,
+      token,
+    );
+    const members = ensureArray(raw);
+    const map = new Map();
+    for (const rowRaw of members) {
+      const row = safeObject(rowRaw);
+      const userID = String(row.user_id || "").trim();
+      if (!userID) continue;
+      map.set(userID, {
+        user_id: userID,
+        name: String(row.name || "").trim(),
+        email: String(row.email || "").trim(),
+        role: String(row.role || "").trim(),
+      });
+    }
+    return map;
+  } catch {
+    return new Map();
+  }
+}
+
+async function loadOrgOwnerUserID({ siteBaseURL, orgID, token, timeoutSeconds }) {
+  const normalizedOrgID = String(orgID || "").trim();
+  if (!normalizedOrgID) return "";
+  try {
+    const raw = await getJSONWithAuth(
+      `${siteBaseURL}/api/v1/orgs/${encodeURIComponent(normalizedOrgID)}`,
+      timeoutSeconds,
+      token,
+    );
+    return String(safeObject(raw).owner_user_id || "").trim();
+  } catch {
+    return "";
+  }
+}
+
+function resolveActorDisplay(userID, membersByUserID) {
+  const id = String(userID || "").trim();
+  if (!id) return "-";
+  const row = membersByUserID.get(id);
+  if (!row) return id;
+  const name = String(row.name || "").trim();
+  const email = String(row.email || "").trim();
+  if (name && email) return `${name} <${email}>`;
+  if (name) return name;
+  if (email) return email;
+  return id;
+}
+
+function isOwnerConfirmationAccepted(rawValue) {
+  const text = String(rawValue || "").trim().toLowerCase();
+  if (!text) return false;
+  return ["yes", "y", "ok", "approve", "approved", "confirm", "confirmed"].includes(text);
+}
+
+async function loadCtxpackMergeBriefForTool({
+  siteBaseURL,
+  projectID,
+  token,
+  timeoutSeconds,
+  statusFilter,
+  limit,
+  workspaceDir,
+}) {
+  const summary = await loadProjectSummaryForTool({
+    siteBaseURL,
+    projectID,
+    token,
+    timeoutSeconds,
+    includeCtxpack: false,
+    syncCtxpackLocal: false,
+    workspaceDir,
+  });
+  if (String(summary.access || "") !== "granted") {
+    return {
+      project_id: projectID,
+      access: summary.access || "error",
+      status_code: summary.status_code || 500,
+      message: summary.message || "Unable to access project.",
+      merge_requests: [],
+      recommendation: {},
+    };
+  }
+
+  const normalizedStatus = normalizeMergeStatusFilter(statusFilter) || "open";
+  const cappedLimit = Math.max(1, Math.min(100, Number.parseInt(String(limit || 20), 10) || 20));
+  const encodedProjectID = encodeURIComponent(projectID);
+  const statusParam =
+    normalizedStatus === "all" || normalizedStatus === "open"
+      ? ""
+      : `&status=${encodeURIComponent(normalizedStatus)}`;
+  const listURL = `${siteBaseURL}/api/v1/projects/${encodedProjectID}/ctxpack/merge-requests?limit=${cappedLimit}&offset=0${statusParam}`;
+  let mergeFeatureAvailable = true;
+  let mergeFeatureWarning = "";
+  let allItems = [];
+  try {
+    const rawList = await getJSONWithAuth(listURL, timeoutSeconds, token);
+    allItems = ensureArray(rawList);
+  } catch (err) {
+    const statusCode = Number(err?.statusCode || 0) || 500;
+    if (statusCode === 404) {
+      mergeFeatureAvailable = false;
+      mergeFeatureWarning = "Merge-request API is not enabled on this server yet.";
+      allItems = [];
+    } else {
+      throw err;
+    }
+  }
+  const statusOpenSet = new Set(["open", "review", "approved"]);
+  const filteredItems =
+    normalizedStatus === "open"
+      ? allItems.filter((rowRaw) => statusOpenSet.has(String(safeObject(rowRaw).status || "").trim().toLowerCase()))
+      : allItems;
+
+  const membersByUserID = await loadProjectMemberMap({
+    siteBaseURL,
+    projectID,
+    token,
+    timeoutSeconds,
+  });
+
+  const actor = extractActorFromToken(token);
+  const orgOwnerUserID = await loadOrgOwnerUserID({
+    siteBaseURL,
+    orgID: summary.org_id,
+    token,
+    timeoutSeconds,
+  });
+  const projectOwnerIDs = new Set(
+    [summary.owner_user_id, summary.program_owner_user_id, summary.tech_owner_user_id, summary.governance_owner_user_id]
+      .map((value) => String(value || "").trim())
+      .filter(Boolean),
+  );
+  const isProjectOwner = actor.user_id ? projectOwnerIDs.has(actor.user_id) : false;
+  const isOrgOwner = Boolean(actor.user_id && orgOwnerUserID && actor.user_id === orgOwnerUserID);
+  const ownerGate = isProjectOwner || isOrgOwner;
+
+  const normalizedItems = filteredItems
+    .map((rowRaw) => {
+      const row = safeObject(rowRaw);
+      const metadata = parseMergeMetadata(row.metadata);
+      const changedPaths = collectMergeChangedPaths(metadata);
+      const status = String(row.status || "").trim().toLowerCase();
+      return {
+        merge_request_id: String(row.merge_request_id || "").trim(),
+        status,
+        created_by_user_id: String(row.created_by || "").trim(),
+        created_by: resolveActorDisplay(String(row.created_by || "").trim(), membersByUserID),
+        reviewed_by_user_id: String(row.reviewed_by || "").trim(),
+        reviewed_by: resolveActorDisplay(String(row.reviewed_by || "").trim(), membersByUserID),
+        approved_at: String(row.approved_at || "").trim(),
+        created_at: String(row.created_at || "").trim(),
+        updated_at: String(row.updated_at || "").trim(),
+        source_version_id: String(row.source_version_id || "").trim(),
+        target_version_id: String(row.target_version_id || "").trim(),
+        metadata_summary: summarizeMergeMetadata(metadata),
+        changed_paths: changedPaths,
+        changed_paths_count: changedPaths.length,
+      };
+    })
+    .sort((a, b) => parseISOTime(b.updated_at) - parseISOTime(a.updated_at));
+
+  const statusCount = {
+    open: normalizedItems.filter((row) => row.status === "open").length,
+    review: normalizedItems.filter((row) => row.status === "review").length,
+    approved: normalizedItems.filter((row) => row.status === "approved").length,
+    rejected: normalizedItems.filter((row) => row.status === "rejected").length,
+    merged: normalizedItems.filter((row) => row.status === "merged").length,
+    closed: normalizedItems.filter((row) => row.status === "closed").length,
+  };
+
+  const approvedCandidates = normalizedItems.filter((row) => row.status === "approved");
+  const reviewCandidates = normalizedItems.filter((row) => row.status === "review" || row.status === "open");
+  let recommendationAction = "no_action";
+  let recommendationReason = "No pending merge requests.";
+  let ownerPrompt = "";
+  if (!mergeFeatureAvailable) {
+    recommendationAction = "merge_api_unavailable";
+    recommendationReason = mergeFeatureWarning;
+    ownerPrompt =
+      "Ask platform owner/admin to enable ctxpack merge-request API before merge approval workflow.";
+  } else if (approvedCandidates.length > 0) {
+    recommendationAction = ownerGate ? "merge_ready" : "owner_approval_required";
+    recommendationReason =
+      approvedCandidates.length === 1
+        ? "There is 1 approved merge request ready for merge."
+        : `There are ${approvedCandidates.length} approved merge requests ready for merge.`;
+    const ids = approvedCandidates.slice(0, 5).map((row) => row.merge_request_id).filter(Boolean);
+    ownerPrompt = `Ask owner decision: merge now for ${ids.join(", ")} ?`;
+  } else if (reviewCandidates.length > 0) {
+    recommendationAction = ownerGate ? "review_then_approve" : "owner_review_required";
+    recommendationReason =
+      reviewCandidates.length === 1
+        ? "There is 1 merge request waiting for review/approval."
+        : `There are ${reviewCandidates.length} merge requests waiting for review/approval.`;
+    const ids = reviewCandidates.slice(0, 5).map((row) => row.merge_request_id).filter(Boolean);
+    ownerPrompt = `Ask owner decision: approve or reject ${ids.join(", ")} ?`;
+  }
+
+  return {
+    project_id: projectID,
+    access: "granted",
+    status_code: 200,
+    message: mergeFeatureAvailable
+      ? "Ctxpack merge briefing is ready."
+      : "Ctxpack merge briefing is ready, but merge-request API is unavailable on this server.",
+    merge_feature_available: mergeFeatureAvailable,
+    merge_feature_warning: mergeFeatureWarning,
+    owner_gate: {
+      actor_user_id: actor.user_id,
+      actor_email: actor.email,
+      actor_name: actor.name,
+      project_owner_user_id: String(summary.owner_user_id || "").trim(),
+      org_owner_user_id: orgOwnerUserID,
+      is_project_owner: isProjectOwner,
+      is_org_owner: isOrgOwner,
+      can_owner_finalize: ownerGate,
+    },
+    status_filter: normalizedStatus,
+    merge_request_count: normalizedItems.length,
+    status_count: statusCount,
+    merge_requests: normalizedItems,
+    recommendation: {
+      action: recommendationAction,
+      reason: recommendationReason,
+      owner_prompt: ownerPrompt,
+      owner_confirmation_required: true,
+    },
+  };
+}
+
+function buildCtxpackMergeBriefText(brief) {
+  if (String(brief?.access || "") !== "granted") {
+    return [
+      `Project ID: ${brief?.project_id || "-"}`,
+      `Access: ${brief?.access || "error"}`,
+      `Status: ${brief?.status_code || "-"}`,
+      `${brief?.message || "Unable to load ctxpack merge briefing."}`,
+    ].join("\n");
+  }
+
+  const lines = [
+    `Project ID: ${brief.project_id || "-"}`,
+    `Merge Requests: ${Number(brief.merge_request_count || 0)}`,
+    `Status Filter: ${brief.status_filter || "open"}`,
+    `Owner Gate: ${brief.owner_gate?.can_owner_finalize ? "owner-confirmation possible" : "owner token required"}`,
+    "",
+    "Status Summary:",
+    `- Open: ${Number(brief.status_count?.open || 0)}`,
+    `- Review: ${Number(brief.status_count?.review || 0)}`,
+    `- Approved: ${Number(brief.status_count?.approved || 0)}`,
+    `- Rejected: ${Number(brief.status_count?.rejected || 0)}`,
+    `- Merged: ${Number(brief.status_count?.merged || 0)}`,
+    `- Closed: ${Number(brief.status_count?.closed || 0)}`,
+  ];
+  if (brief.merge_feature_available === false) {
+    lines.push("");
+    lines.push("Merge API:");
+    lines.push(`- ${brief.merge_feature_warning || "Merge-request API is unavailable on this server."}`);
+  }
+  lines.push("");
+  lines.push("Recommendation:");
+  lines.push(`- Action: ${brief.recommendation?.action || "no_action"}`);
+  lines.push(`- Reason: ${brief.recommendation?.reason || "-"}`);
+  const ownerPrompt = String(brief.recommendation?.owner_prompt || "").trim();
+  if (ownerPrompt) {
+    lines.push(`- Owner Prompt: ${ownerPrompt}`);
+  }
+  const requests = ensureArray(brief.merge_requests);
+  if (requests.length > 0) {
+    lines.push("");
+    lines.push("Pending Details:");
+    for (const row of requests.slice(0, 20)) {
+      const changedPreview =
+        row.changed_paths_count > 0 ? `${row.changed_paths_count} path(s)` : "no changed_paths metadata";
+      const changedList =
+        row.changed_paths_count > 0 ? ` [${ensureArray(row.changed_paths).slice(0, 5).join(", ")}]` : "";
+      lines.push(
+        `- ${row.merge_request_id} | ${row.status} | by ${row.created_by || row.created_by_user_id || "-"} | ${changedPreview}${changedList}`,
+      );
+      if (row.metadata_summary) {
+        lines.push(`  summary: ${row.metadata_summary}`);
+      }
+    }
+  }
+  lines.push("");
+  lines.push(
+    "Before execute, ask owner for explicit confirmation, then run ctxpack.merge.execute with owner_confirmation.",
+  );
+  return lines.join("\n");
+}
+
+async function executeCtxpackMergeActionForTool({
+  siteBaseURL,
+  projectID,
+  mergeRequestID,
+  action,
+  ownerConfirmation,
+  token,
+  timeoutSeconds,
+  workspaceDir,
+}) {
+  if (!isOwnerConfirmationAccepted(ownerConfirmation)) {
+    return {
+      project_id: projectID,
+      merge_request_id: mergeRequestID,
+      action,
+      ok: false,
+      status_code: 400,
+      message: "Owner confirmation missing. Ask owner and pass owner_confirmation (confirm/approved/yes).",
+    };
+  }
+
+  const summary = await loadProjectSummaryForTool({
+    siteBaseURL,
+    projectID,
+    token,
+    timeoutSeconds,
+    includeCtxpack: false,
+    syncCtxpackLocal: false,
+    workspaceDir,
+  });
+  if (String(summary.access || "") !== "granted") {
+    return {
+      project_id: projectID,
+      merge_request_id: mergeRequestID,
+      action,
+      ok: false,
+      status_code: summary.status_code || 500,
+      message: summary.message || "Project access denied.",
+    };
+  }
+
+  const actor = extractActorFromToken(token);
+  const orgOwnerUserID = await loadOrgOwnerUserID({
+    siteBaseURL,
+    orgID: summary.org_id,
+    token,
+    timeoutSeconds,
+  });
+  const projectOwnerIDs = new Set(
+    [summary.owner_user_id, summary.program_owner_user_id, summary.tech_owner_user_id, summary.governance_owner_user_id]
+      .map((value) => String(value || "").trim())
+      .filter(Boolean),
+  );
+  const isProjectOwner = actor.user_id ? projectOwnerIDs.has(actor.user_id) : false;
+  const isOrgOwner = Boolean(actor.user_id && orgOwnerUserID && actor.user_id === orgOwnerUserID);
+  if (!(isProjectOwner || isOrgOwner)) {
+    return {
+      project_id: projectID,
+      merge_request_id: mergeRequestID,
+      action,
+      ok: false,
+      status_code: 403,
+      message: "Owner gate blocked: current token is not project/org owner. Ask owner account to execute.",
+    };
+  }
+
+  const encodedProjectID = encodeURIComponent(projectID);
+  const encodedMRID = encodeURIComponent(mergeRequestID);
+  const endpoint = `${siteBaseURL}/api/v1/projects/${encodedProjectID}/ctxpack/merge-requests/${encodedMRID}/${action}`;
+
+  try {
+    const responseText = await postJSON(endpoint, timeoutSeconds, token, {});
+    const parsed = tryJsonParse(responseText) || {};
+    return {
+      project_id: projectID,
+      merge_request_id: mergeRequestID,
+      action,
+      ok: true,
+      status_code: 200,
+      message: `Merge request action '${action}' completed.`,
+      actor_user_id: actor.user_id,
+      actor_email: actor.email,
+      response: safeObject(parsed),
+    };
+  } catch (err) {
+    const statusCode = Number(err?.statusCode || 0) || 500;
+    const bodyText = String(err?.responseBody || err?.message || "").trim();
+    let message = bodyText || `Failed to execute action '${action}'.`;
+    if (statusCode === 403) {
+      message = "Forbidden by server policy/role. Current account cannot execute this action.";
+    } else if (statusCode === 409) {
+      message =
+        "Merge conflict or approval state mismatch. Refresh briefing (ctxpack.merge.brief), then re-review before merge.";
+    } else if (statusCode === 404) {
+      message = "Merge request not found for this project.";
+    }
+    return {
+      project_id: projectID,
+      merge_request_id: mergeRequestID,
+      action,
+      ok: false,
+      status_code: statusCode,
+      message,
+      error: bodyText,
+    };
+  }
+}
+
+function buildCtxpackMergeExecuteText(result) {
+  const lines = [
+    `Project ID: ${result.project_id || "-"}`,
+    `Merge Request ID: ${result.merge_request_id || "-"}`,
+    `Action: ${result.action || "-"}`,
+    `Result: ${result.ok ? "ok" : "failed"} (status ${result.status_code || "-"})`,
+    `Message: ${result.message || "-"}`,
+  ];
+  if (result.ok) {
+    const mergedVersionID = String(result.response?.merged_version_id || "").trim();
+    if (mergedVersionID) {
+      lines.push(`Merged Version ID: ${mergedVersionID}`);
+    }
+  } else if (result.error) {
+    lines.push(`Server: ${result.error}`);
+  }
+  return lines.join("\n");
+}
+
 function buildProjectSummaryText(summary) {
   if (String(summary?.access || "") !== "granted") {
     return [
@@ -2327,6 +3015,7 @@ function appendProjectHintToInitialize(responseObj, args) {
     "- MUST call `project.summary` first when the user provides only a Project ID or asks project overview/agenda.",
     "- `project.describe` and `project.get` are aliases of `project.summary`.",
     "- After project summary, use workitem/evidence/decision tools as follow-up.",
+    "- Before any ctxpack merge, call `ctxpack.merge.brief` first, share recommendation to owner, get explicit owner confirmation, then call `ctxpack.merge.execute`.",
   ];
   if (args.projectID) {
     hintLines.splice(1, 0, `- Default project_id is ${args.projectID}.`);
@@ -2348,14 +3037,14 @@ async function maybeAutoSyncCtxpackForCall({
 }) {
   if (!isJsonRpcMethod(requestObj, "tools/call")) return null;
   if (!token) return null;
-  if (LOCAL_PROJECT_TOOL_NAMES.includes(toolName)) return null;
+  if (LOCAL_PROJECT_TOOL_NAMES.includes(toolName) || LOCAL_CTXPACK_MERGE_TOOL_NAMES.includes(toolName)) return null;
   if (String(toolName || "").trim().toLowerCase() === "ctxpack.ensure") return null;
 
-  const projectID = firstNonEmptyString([
-    toolArgs?.project_id,
-    toolArgs?.projectID,
-    args.projectID,
-  ]);
+  const projectID = resolveProjectIDForRequest({
+    toolArgs,
+    args,
+    workspaceDir,
+  });
   if (!isUUID(projectID)) return null;
 
   const workspacePath = resolveWorkspaceDir(workspaceDir || process.cwd());
@@ -2448,7 +3137,12 @@ async function appendWorkitemListHints(responseObj, args, toolArgs, token) {
   }
 
   const projectID = String(
-    toolArgs?.project_id || toolArgs?.projectID || responseProjectID || args.projectID || "",
+    resolveProjectIDForRequest({
+      toolArgs,
+      args,
+      workspaceDir: args.workspaceDir,
+      responseProjectID,
+    }),
   ).trim();
 
   if (projectID && isUUID(projectID)) {
@@ -2517,7 +3211,12 @@ function appendCtxpackEnsureSyncHints(responseObj, args, toolArgs, requestObj) {
   if (!Object.keys(body).length) return responseObj;
 
   const projectID = String(
-    toolArgs?.project_id || toolArgs?.projectID || envelope.project_id || args.projectID || "",
+    resolveProjectIDForRequest({
+      toolArgs,
+      args,
+      workspaceDir: args.workspaceDir,
+      envelopeProjectID: envelope.project_id,
+    }),
   ).trim();
   if (!projectID || !isUUID(projectID)) return responseObj;
   const workspaceDir = resolveWorkspaceDirForRequest(args.workspaceDir || process.cwd(), requestObj, toolArgs);
@@ -2632,13 +3331,15 @@ async function injectCtxpackPreflightToken(requestObj, toolName, toolArgs, args,
     return requestObj;
   }
 
-  const projectID = firstNonEmptyString([
-    rawArgs.project_id,
-    rawArgs.projectID,
-    toolArgs?.project_id,
-    toolArgs?.projectID,
-    args.projectID,
-  ]);
+  const mergedToolArgs = {
+    ...safeObject(toolArgs),
+    project_id: firstNonEmptyString([rawArgs.project_id, rawArgs.projectID, toolArgs?.project_id, toolArgs?.projectID]),
+  };
+  const projectID = resolveProjectIDForRequest({
+    toolArgs: mergedToolArgs,
+    args,
+    workspaceDir,
+  });
   if (!isUUID(projectID)) {
     return requestObj;
   }
@@ -2728,12 +3429,13 @@ async function appendCtxpackConflictHintToErrorResponse(responseObj, args, toolN
 }
 
 async function runProxy(flags) {
-  const workspaceMeta = loadWorkspaceMeta(process.cwd());
+  const explicitWorkspaceDirRaw = String(flags["workspace-dir"] || "").trim();
+  const explicitWorkspaceDir = explicitWorkspaceDirRaw ? resolveWorkspaceDir(explicitWorkspaceDirRaw) : "";
   const args = {
     baseURL: flags["base-url"] || DEFAULT_BASE_URL,
-    projectID: String(flags["project-id"] || workspaceMeta.project_id || "").trim(),
-    ctxpackKey: String(flags["ctxpack-key"] || buildCtxpackKeyFromMeta(workspaceMeta) || "").trim(),
-    workspaceDir: resolveWorkspaceDir(flags["workspace-dir"] || process.cwd()),
+    projectID: String(flags["project-id"] || "").trim(),
+    ctxpackKey: String(flags["ctxpack-key"] || "").trim(),
+    workspaceDir: explicitWorkspaceDir,
     includeDrafts: boolFromRaw(flags["include-drafts"], true),
     autoPullOnConflict: boolFromRaw(flags["auto-pull-on-conflict"], true),
     timeoutSeconds: intFromRaw(flags["timeout-seconds"], 30),
@@ -2800,12 +3502,16 @@ async function runProxy(flags) {
 
     const { name: toolName, args: toolArgs } = extractToolCall(requestObj);
     const requestWorkspaceCandidate = extractWorkspaceCandidateFromRequest(requestObj, toolArgs);
+    const envWorkspaceCandidate = extractWorkspaceCandidateFromEnv();
     if (requestWorkspaceCandidate) {
       sessionWorkspaceDir = requestWorkspaceCandidate;
+    } else if (envWorkspaceCandidate) {
+      sessionWorkspaceDir = envWorkspaceCandidate;
     }
     const requestWorkspaceDir = resolveWorkspaceDir(
       firstNonEmptyString([
         requestWorkspaceCandidate,
+        envWorkspaceCandidate,
         sessionWorkspaceDir,
         args.workspaceDir,
         process.cwd(),
@@ -2823,7 +3529,13 @@ async function runProxy(flags) {
       });
     }
     if (isJsonRpcMethod(requestObj, "tools/call") && LOCAL_PROJECT_TOOL_NAMES.includes(toolName)) {
-      const projectID = String(toolArgs.project_id || toolArgs.projectID || args.projectID || "").trim();
+      const projectID = String(
+        resolveProjectIDForRequest({
+          toolArgs,
+          args,
+          workspaceDir: requestWorkspaceDir,
+        }),
+      ).trim();
       if (!projectID) {
         process.stdout.write(
           `${JSON.stringify(jsonRpcError(requestObj, -32001, "project_id is required (or set --project-id during setup)"))}\n`,
@@ -2879,6 +3591,113 @@ async function runProxy(flags) {
       }
       return;
     }
+    if (isJsonRpcMethod(requestObj, "tools/call") && LOCAL_CTXPACK_MERGE_TOOL_NAMES.includes(toolName)) {
+      const projectID = String(
+        resolveProjectIDForRequest({
+          toolArgs,
+          args,
+          workspaceDir: requestWorkspaceDir,
+        }),
+      ).trim();
+      if (!projectID) {
+        process.stdout.write(
+          `${JSON.stringify(jsonRpcError(requestObj, -32001, "project_id is required (or set --project-id during setup)"))}\n`,
+        );
+        return;
+      }
+      if (!isUUID(projectID)) {
+        process.stdout.write(
+          `${JSON.stringify(jsonRpcError(requestObj, -32001, "project_id must be a valid UUID"))}\n`,
+        );
+        return;
+      }
+
+      try {
+        if (toolName === "ctxpack.merge.brief") {
+          const statusRaw = String(toolArgs.status || "").trim().toLowerCase();
+          const statusFilter = normalizeMergeStatusFilter(statusRaw);
+          if (statusRaw && !statusFilter) {
+            process.stdout.write(
+              `${JSON.stringify(
+                jsonRpcError(
+                  requestObj,
+                  -32001,
+                  "status must be one of: open, review, approved, rejected, merged, closed, all",
+                ),
+              )}\n`,
+            );
+            return;
+          }
+          const limit = Number.parseInt(String(toolArgs.limit || 20), 10) || 20;
+          const brief = await loadCtxpackMergeBriefForTool({
+            siteBaseURL: normalizeSiteBaseURL(args.baseURL),
+            projectID,
+            token,
+            timeoutSeconds: args.timeoutSeconds,
+            statusFilter: statusFilter || "open",
+            limit,
+            workspaceDir: requestWorkspaceDir,
+          });
+          const text = buildCtxpackMergeBriefText(brief);
+          process.stdout.write(
+            `${JSON.stringify(
+              jsonRpcResult(requestObj, {
+                content: [{ type: "text", text }],
+                structuredContent: brief,
+              }),
+            )}\n`,
+          );
+          return;
+        }
+
+        if (toolName === "ctxpack.merge.execute") {
+          const mergeRequestID = String(toolArgs.merge_request_id || toolArgs.mergeRequestID || "").trim();
+          const action = normalizeMergeAction(toolArgs.action);
+          const ownerConfirmation = String(
+            toolArgs.owner_confirmation || toolArgs.ownerConfirmation || "",
+          ).trim();
+          if (!mergeRequestID || !isUUID(mergeRequestID)) {
+            process.stdout.write(
+              `${JSON.stringify(jsonRpcError(requestObj, -32001, "merge_request_id must be a valid UUID"))}\n`,
+            );
+            return;
+          }
+          if (!action) {
+            process.stdout.write(
+              `${JSON.stringify(
+                jsonRpcError(requestObj, -32001, "action must be one of: review, approve, reject, close, merge"),
+              )}\n`,
+            );
+            return;
+          }
+          const result = await executeCtxpackMergeActionForTool({
+            siteBaseURL: normalizeSiteBaseURL(args.baseURL),
+            projectID,
+            mergeRequestID,
+            action,
+            ownerConfirmation,
+            token,
+            timeoutSeconds: args.timeoutSeconds,
+            workspaceDir: requestWorkspaceDir,
+          });
+          const text = buildCtxpackMergeExecuteText(result);
+          process.stdout.write(
+            `${JSON.stringify(
+              jsonRpcResult(requestObj, {
+                content: [{ type: "text", text }],
+                structuredContent: result,
+              }),
+            )}\n`,
+          );
+          return;
+        }
+      } catch (err) {
+        process.stdout.write(
+          `${JSON.stringify(jsonRpcError(requestObj, -32001, String(err?.message || err)))}\n`,
+        );
+        return;
+      }
+    }
 
     try {
       const requestWithDefaults = injectCtxpackPushDefaults(requestObj, toolName, requestWorkspaceDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metheus-governance-mcp-cli",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "Metheus Governance MCP CLI (setup + stdio proxy)",
   "type": "module",
   "files": [