metheus-governance-mcp-cli 0.2.46 → 0.2.48

package/README.md

@@ -50,17 +50,10 @@ Gemini CLI note:
 - `gemini mcp` commands require Gemini auth to be configured first (`GEMINI_API_KEY` or `~/.gemini/settings.json` auth).
 - `setup` registers Gemini in both `user` and `project` scopes to improve auto-discovery across folders.
 
-When a client does not send workspace metadata (for example some Codex sessions),
-set a stable fallback root once:
-
-```bash
-metheus-governance-mcp-cli setup --project-id <project_uuid> --ctxpack-key "<ctxpack_key>" --base-url https://metheus.gesiaplatform.com --workspace-dir auto --workspace-fallback-dir C:\code_test
-```
-
-This sets fallback workspace context for clients that do not pass workspace metadata:
-- Codex/Antigravity/Cursor: `METHEUS_WORKSPACE_DIR` env
-- Gemini: pinned `--workspace-dir <fallback>` and `METHEUS_WORKSPACE_DIR` in MCP registration
-- fallback env is used only when workspace cannot be resolved (or resolves to home); when current `cwd` is a real project folder, sync uses that folder.
+Workspace signal guardrail:
+- default recommendation is `--workspace-dir auto` with no fixed fallback path.
+- if a client session does not provide trusted workspace signals (`workspaceFolders` / `rootUri` / `cwd`), ctxpack local write is blocked (`sync_status=guarded`, `local_file_count=0`).
+- use `--workspace-fallback-dir` only when you intentionally want a shared fallback root.
 
 Guardrail note:
 - By default, CLI blocks reading/writing ctxpack sync metadata when workspace root resolves to the home directory.
@@ -105,8 +98,8 @@ Cursor note:
 
 Tool naming compatibility:
 - Claude/Codex/Gemini keep canonical MCP tool names (`project.summary`, `ctxpack.merge.brief`, ...).
-- Cursor/Antigravity sessions may receive safe aliases (`project_summary`, `ctxpack_merge_brief`, ...).
-- Proxy maps alias calls back to canonical names automatically.
+- Cursor/Antigravity sessions use safe aliases only (`project_summary`, `ctxpack_merge_brief`, ...).
+- Proxy maps safe alias calls back to canonical names automatically.
 
 Local bootstrap tools exposed by proxy:
 
@@ -127,7 +120,12 @@ These tools accept `project_id` and return:
 - same version -> keep current
 - newer server version -> update local cache
 - workspace path -> auto-detected from client metadata/env by default
-- use `--workspace-fallback-dir <path>` when client metadata is unavailable
+- if workspace signal is missing in auto mode, sync is guarded (no local write)
+- use `--workspace-fallback-dir <path>` only when you intentionally want fallback writes
+
+Project-ID first-call rule:
+- when user gives only `Project ID`, call `project.summary` first.
+- call `ctxpack.ensure` after `project.summary` only when extra ctxpack refresh/export context is needed.
 
 Ctxpack merge safety flow:
 - call `ctxpack.merge.brief` first

package/cli.mjs

@@ -3719,6 +3719,7 @@ function appendProjectHintToInitialize(responseObj, args, options = {}) {
   const projectSummaryTool = displayToolNameForClient("project.summary", useSafeToolAliases);
   const projectDescribeTool = displayToolNameForClient("project.describe", useSafeToolAliases);
   const projectGetTool = displayToolNameForClient("project.get", useSafeToolAliases);
+  const ctxpackEnsureTool = displayToolNameForClient("ctxpack.ensure", useSafeToolAliases);
   const ctxpackMergeBriefTool = displayToolNameForClient("ctxpack.merge.brief", useSafeToolAliases);
   const ctxpackMergeExecuteTool = displayToolNameForClient("ctxpack.merge.execute", useSafeToolAliases);
   const hintLines = [
@@ -3730,6 +3731,8 @@ function appendProjectHintToInitialize(responseObj, args, options = {}) {
       : []),
     `- MUST call \`${projectSummaryTool}\` first when the user provides only a Project ID or asks project overview/agenda.`,
     `- \`${projectDescribeTool}\` and \`${projectGetTool}\` are aliases of \`${projectSummaryTool}\`.`,
+    `- Never handle a bare Project ID by local file/transcript search before \`${projectSummaryTool}\` succeeds.`,
+    `- Run \`${ctxpackEnsureTool}\` only after \`${projectSummaryTool}\`, and only when additional ctxpack refresh/export context is needed.`,
     "- After project summary, use workitem/evidence/decision tools as follow-up.",
     `- Before any ctxpack merge, call \`${ctxpackMergeBriefTool}\` first, share recommendation to owner, get explicit owner confirmation, then call \`${ctxpackMergeExecuteTool}\`.`,
     "- IMPORTANT: When calling ANY tool, always include your current working directory / project folder path as the `workspace_dir` argument. This enables ctxpack files to be synced to the correct workspace location.",
@@ -3738,7 +3741,13 @@ function appendProjectHintToInitialize(responseObj, args, options = {}) {
     hintLines.splice(1, 0, `- Default project_id is ${args.projectID}.`);
   }
   const hint = `${hintLines.join("\n")}\n`;
-  const current = String(result.instructions || "").trimEnd();
+  let current = String(result.instructions || "").trimEnd();
+  if (current) {
+    current = current.replace(
+      /If a user provides only Project ID,\s*call ctxpack\.ensure first[^.\n]*[.\n]?/gi,
+      `If a user provides only Project ID, call ${projectSummaryTool} first. Then call ${ctxpackEnsureTool} only if additional ctxpack refresh is needed.\n`,
+    );
+  }
   result.instructions = current ? `${hint}\n${current}` : hint;
   responseObj.result = result;
   return responseObj;

package/package.json

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