metheus-governance-mcp-cli 0.2.152 → 0.2.157

package/README.md

@@ -383,7 +383,7 @@ Checks:
 - smoke calls: `workitem.list`, `evidence.list`, `decision.list`
 - Telegram room audit for active project destinations, including external room bots and visible server/local mismatches
 - route-state workspace artifact boundary violations recorded by the runner
-- external project artifact findings discovered from known out-of-workspace roots such as `~/.claude/plans`
+- external project artifact findings discovered from known out-of-workspace roots such as `~/.claude/plans` (Claude-managed area, not a Metheus authoring target)
 
 `--strict true` upgrades local runner route safety warnings into failures.
 Use it for production validation before enabling long-running bot routes.
@@ -497,8 +497,9 @@ Recommended production path:
 - keep project room identifier in server-side Chat Destinations
 - keep automation route config in `~/.metheus/bot-runner.json`
 - keep project workspace mappings in `~/.metheus/project-workspaces.json`
-- let `ctxpack pull` or project connection refresh the mapping automatically
-- successful `project.summary` / `project.describe` / `project.get` calls now also persist the trusted current workspace signal into the project workspace registry
+- treat `project-workspaces.json` as the local workspace authority for this machine
+- do not treat ctxpack sync/cache metadata as workspace authority
+- do not assume `project.summary` / `project.describe` / `project.get` will rewrite local workspace mappings
 - keep per-role execution policy under `role_profiles`
 - keep Telegram-wide binding defaults in `~/.metheus/telegram-bots/global.env`
 - use `bot_bindings` in `bot-runner.json` only as local fallback/override
@@ -509,6 +510,13 @@ Why `workspace_dir` matters:
 - the local runner must pass the correct folder to Codex, Claude Code, or Gemini on that member's machine
 - without a valid project mapping, bots may answer with a generic local root instead of the real project workspace
 
+Workspace/source-of-truth model:
+- `project-workspaces.json` answers only one question: `project_id -> local workspace_dir on this machine`
+- `bot-runner.json` stores executable route config and role profiles; it is not the project workspace registry
+- `ctxpack` is project guidance/specification content stored inside the workspace and on the server; it is not the local workspace authority
+- `.metheus/ctxpack-cache/` is local synced cache for ctxpack content; do not treat it as the final authoring target for project documents
+- `.metheus/runner-runtime/local-ai-scratch/` is local runner scratch space for AI CLI runtime support; do not treat it as a project artifact location or a user-facing document location
+
 Role profile fields:
 - `client`: `gpt`, `claude`, `gemini`, or `sample`
 - `codex` is still accepted as a compatibility alias for `gpt`
@@ -564,8 +572,9 @@ Archive policy fields:
 
 Mapping behavior:
 - `ctxpack pull --workspace-dir <path>` stores `project_id -> workspace_dir`
-- proxy/project connection can also persist the mapping
-- broader project roots are preferred over nested tool folders when updating the mapping
+- broader project roots are preferred over nested tool folders when updating the mapping intentionally
+- `project.summary` / `project.describe` / `project.get` sync ctxpack cache, but they do not own local workspace authority
+- if you need to change a project's local folder on this machine, update the project workspace registry intentionally instead of relying on ctxpack cache side effects
 
 Runner command contract:
 - stdin: JSON payload containing project, destination, trigger message, and recent context comments
@@ -633,6 +642,7 @@ These tools accept `project_id` and return:
 - workspace path -> auto-detected from client metadata/env by default
 - 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
+- this local cache sync does not make ctxpack the source of truth for `project-workspaces.json`
 
 Project-ID first-call rule:
 - when user gives only `Project ID`, call `project.summary` first.
@@ -651,9 +661,13 @@ Manual ctxpack pull/update:
 metheus-governance-mcp-cli ctxpack pull --project-id <project_uuid> --base-url https://metheus.gesiaplatform.com
 ```
 
+Canonical ctxpack write tool name:
+- use `ctxpack.update`
+- do not use legacy names like `ctxpack.push` or `ctxpack.save`
+
 When `workitem.list` returns empty, proxy appends a hint to call `project.summary` first.
 
-For `ctxpack` push conflicts (`ctxpack_conflict` / stale baseline), proxy behavior:
+For `ctxpack.update` conflicts (`ctxpack_conflict` / stale baseline), proxy behavior:
 - standard conflict message with pull/merge/retry guidance
 - auto ctxpack pull-to-local on conflict by default (`--auto-pull-on-conflict=true`)
 

package/cli.mjs

@@ -78,7 +78,7 @@ import {
   appendCtxpackEnsureSyncHints as appendCtxpackEnsureSyncHintsImpl,
   appendWorkitemListHints as appendWorkitemListHintsImpl,
   injectCtxpackPreflightToken as injectCtxpackPreflightTokenImpl,
-  injectCtxpackPushDefaults as injectCtxpackPushDefaultsImpl,
+  injectCtxpackUpdateDefaults as injectCtxpackUpdateDefaultsImpl,
   maybeAutoSyncCtxpackForCall as maybeAutoSyncCtxpackForCallImpl,
   maybeAutoSyncCtxpackForSessionRequest as maybeAutoSyncCtxpackForSessionRequestImpl,
   stripLocalOnlyToolArgs as stripLocalOnlyToolArgsImpl,
@@ -212,7 +212,7 @@ const PROVIDER_ENV_ORDER = Object.keys(PROVIDER_ENV_CONFIG);
 const SELF_UPDATE_STATE_RELATIVE_PATH = path.join(".metheus", "governance-mcp-cli-update.json");
 const CTXPACK_CACHE_RELATIVE_DIR = path.join(".metheus", "ctxpack-cache");
 const CTXPACK_META_FILENAME = ".metheus_ctxpack_sync.json";
-const CTXPACK_PUSH_TOOL_NAMES = ["ctxpack.push", "ctxpack.update", "ctxpack.save"];
+const CTXPACK_UPDATE_TOOL_NAMES = ["ctxpack.update"];
 const CLI_META = loadCLIMeta();
 const CLI_NAME = CLI_META.name || "metheus-governance-mcp-cli";
 const CLI_VERSION = CLI_META.version || "0.0.0";
@@ -3129,7 +3129,10 @@ function shouldIgnoreCtxpackArtifactPath(relativePath) {
   if (!normalizedPath) return true;
   return (
     normalizedPath === CTXPACK_META_FILENAME.toLowerCase()
-    || normalizedPath.startsWith(".metheus/")
+    || normalizedPath === ".metheus/ctxpack-cache"
+    || normalizedPath.startsWith(".metheus/ctxpack-cache/")
+    || normalizedPath === ".metheus/runner-runtime"
+    || normalizedPath.startsWith(".metheus/runner-runtime/")
     || normalizedPath.startsWith(".claude/")
     || normalizedPath.startsWith(".git/")
     || normalizedPath.startsWith("node_modules/")
@@ -6568,18 +6571,18 @@ function buildLocalProjectDispatchDeps() {
     boolFromRaw,
     normalizeSiteBaseURL,
     loadProjectSummaryForTool: (params) => loadProjectSummaryForTool(params, buildProjectToolDeps()),
-    buildProjectSummaryText,
-    normalizeMergeStatusFilter,
-    loadCtxpackMergeBriefForTool: (params) => loadCtxpackMergeBriefForTool(params, buildProjectToolDeps()),
-    buildCtxpackMergeBriefText,
-    normalizeMergeAction,
-    executeCtxpackMergeActionForTool: (params) => executeCtxpackMergeActionForTool(params, buildProjectToolDeps()),
-    buildCtxpackMergeExecuteText,
-    rememberProjectWorkspaceMapping,
-    jsonRpcError,
-    jsonRpcResult,
-    localProjectToolNames: LOCAL_PROJECT_TOOL_NAMES,
-    localCtxpackMergeToolNames: LOCAL_CTXPACK_MERGE_TOOL_NAMES,
+  buildProjectSummaryText,
+  normalizeMergeStatusFilter,
+  loadCtxpackMergeBriefForTool: (params) => loadCtxpackMergeBriefForTool(params, buildProjectToolDeps()),
+  buildCtxpackMergeBriefText,
+  normalizeMergeAction,
+  executeCtxpackMergeActionForTool: (params) => executeCtxpackMergeActionForTool(params, buildProjectToolDeps()),
+  buildCtxpackMergeExecuteText,
+  rememberProjectWorkspaceMapping,
+  jsonRpcError,
+  jsonRpcResult,
+  localProjectToolNames: LOCAL_PROJECT_TOOL_NAMES,
+  localCtxpackMergeToolNames: LOCAL_CTXPACK_MERGE_TOOL_NAMES,
   };
 }
 
@@ -6601,7 +6604,7 @@ function buildProxyToolHelperDeps() {
     loadProjectSummaryForTool: (params) => loadProjectSummaryForTool(params, buildProjectToolDeps()),
     parseToolEnvelopeFromRPCResult: (resultObj) =>
       parseToolEnvelopeFromRPCResult(resultObj, buildGatewayTransportDeps()),
-    ctxpackPushToolNames: CTXPACK_PUSH_TOOL_NAMES,
+    ctxpackUpdateToolNames: CTXPACK_UPDATE_TOOL_NAMES,
     localProjectToolNames: LOCAL_PROJECT_TOOL_NAMES,
     localCtxpackMergeToolNames: LOCAL_CTXPACK_MERGE_TOOL_NAMES,
     autoCtxpackSyncTracker,
@@ -6626,7 +6629,7 @@ function buildProxyResponsePipelineDeps() {
 
 function buildProxyGatewayRequestDeps() {
   return {
-    injectCtxpackPushDefaults,
+    injectCtxpackUpdateDefaults,
     injectCtxpackPreflightToken,
     stripLocalOnlyToolArgs,
     postJSON,
@@ -7016,7 +7019,7 @@ async function runDoctor(flags) {
         rows,
         "fail",
         "stale baseline",
-        `local ${localBaseVersionID} != server ${serverCurrentVersionID}. Run ctxpack pull before safe push.`,
+        `local ${localBaseVersionID} != server ${serverCurrentVersionID}. Run ctxpack pull before ctxpack.update.`,
       );
     } else {
       addDoctorCheck(rows, "ok", "stale baseline", `baseline is current (${serverCurrentVersionID})`);
@@ -7777,8 +7780,8 @@ function stripLocalOnlyToolArgs(requestObj) {
   return stripLocalOnlyToolArgsImpl(requestObj);
 }
 
-function injectCtxpackPushDefaults(requestObj, toolName, workspaceDir) {
-  return injectCtxpackPushDefaultsImpl(
+function injectCtxpackUpdateDefaults(requestObj, toolName, workspaceDir) {
+  return injectCtxpackUpdateDefaultsImpl(
     {
       requestObj,
       toolName,
@@ -8354,6 +8357,7 @@ TELEGRAM_BOT_REVIEW_TOKEN=review-token
     normalizeBotRunnerConfigContents,
     defaultLocalBotBridgeCommand,
     resolveRunnerExecutionPlan,
+    resolveRunnerExecutionPlanForRole,
     normalizeRunnerRoute,
     buildRunnerRouteNameSuggestion,
     buildRunnerRoutePayload,
@@ -8371,6 +8375,7 @@ TELEGRAM_BOT_REVIEW_TOKEN=review-token
     normalizeRunnerTriggerPolicy,
     evaluateTelegramRunnerTrigger,
     processRunnerSelectedRecord,
+    runRunnerAIExecution,
     formatBotReplyArchiveComment,
     findArchivedBotReplyRecord,
     parseArchivedChatComment,

package/lib/local-ai-adapters.mjs

@@ -288,6 +288,51 @@ export function normalizeExecutionArtifacts(rawArtifacts) {
     .filter(Boolean);
 }
 
+function normalizeExecutionCtxpackFile(rawFile) {
+  const file = safeObject(rawFile);
+  const filePath = firstNonEmptyString([
+    file.path,
+    file.file,
+    file.file_path,
+    file.filePath,
+    file.location,
+  ]);
+  if (!filePath) {
+    return null;
+  }
+  const operation = normalizeArtifactOperation(
+    file.operation
+    || file.op
+    || file.action,
+  );
+  const content = firstNonEmptyString([
+    file.content,
+    file.body,
+    file.text,
+    file.markdown,
+  ]);
+  if (operation !== "delete" && !content) {
+    return null;
+  }
+  return {
+    path: filePath,
+    content,
+    docType: firstNonEmptyString([
+      file.doc_type,
+      file.docType,
+      file.kind,
+      file.type,
+    ]),
+    operation,
+  };
+}
+
+export function normalizeExecutionCtxpackFiles(rawFiles) {
+  return ensureArray(rawFiles)
+    .map((item) => normalizeExecutionCtxpackFile(item))
+    .filter(Boolean);
+}
+
 function normalizeExecutionWorkItem(rawItem) {
   const item = safeObject(rawItem);
   const title = firstNonEmptyString([
@@ -345,6 +390,35 @@ function listRegularFilesRecursive(rootDir) {
   return output;
 }
 
+function normalizeWorkspaceRelativeArtifactPath(rawPath = "") {
+  return String(rawPath || "").trim().replace(/\\/g, "/").replace(/^\.\/+/, "");
+}
+
+function shouldTrackWorkspaceArtifactRelativePath(rawPath = "") {
+  const normalized = normalizeWorkspaceRelativeArtifactPath(rawPath);
+  return Boolean(normalized) && !isInternalRuntimeArtifactPath(normalized);
+}
+
+function snapshotWorkspaceArtifactMap(rootDir) {
+  const snapshot = new Map();
+  for (const filePath of listRegularFilesRecursive(rootDir)) {
+    const relativePath = normalizeWorkspaceRelativeArtifactPath(path.relative(rootDir, filePath));
+    if (!shouldTrackWorkspaceArtifactRelativePath(relativePath)) {
+      continue;
+    }
+    try {
+      const stats = fs.statSync(filePath);
+      snapshot.set(normalizeArtifactPathForRuntimeCompare(relativePath), {
+        relativePath,
+        resolvedPath: path.resolve(filePath),
+        mtimeMs: stats.mtimeMs,
+        sizeBytes: stats.size,
+      });
+    } catch {}
+  }
+  return snapshot;
+}
+
 function snapshotDirectoryMtimeMap(rootDir) {
   const snapshot = new Map();
   for (const filePath of listRegularFilesRecursive(rootDir)) {
@@ -356,6 +430,90 @@ function snapshotDirectoryMtimeMap(rootDir) {
   return snapshot;
 }
 
+export function captureWorkspaceArtifactSnapshot(workspaceDir) {
+  const normalizedWorkspaceDir = ensureWorkspaceDir(workspaceDir);
+  return {
+    workspaceDir: normalizedWorkspaceDir,
+    files: snapshotWorkspaceArtifactMap(normalizedWorkspaceDir),
+  };
+}
+
+export function observeExecutionArtifacts({
+  beforeSnapshot,
+  workspaceDir,
+  reportedArtifacts = [],
+}) {
+  const afterSnapshot = captureWorkspaceArtifactSnapshot(workspaceDir);
+  const beforeFiles = beforeSnapshot?.files instanceof Map ? beforeSnapshot.files : new Map();
+  const afterFiles = afterSnapshot.files instanceof Map ? afterSnapshot.files : new Map();
+  const reported = normalizeExecutionArtifacts(reportedArtifacts);
+  const reportedByPath = new Map(
+    reported
+      .map((item) => {
+        const artifact = safeObject(item);
+        const normalizedPath = normalizeArtifactPathForRuntimeCompare(artifact.path || artifact.relativePath || "");
+        if (!normalizedPath) {
+          return null;
+        }
+        return [normalizedPath, artifact];
+      })
+      .filter(Boolean),
+  );
+  const observedArtifacts = [];
+  const observedPathKeys = new Set();
+  const allPathKeys = new Set([
+    ...beforeFiles.keys(),
+    ...afterFiles.keys(),
+  ]);
+  for (const pathKey of allPathKeys) {
+    const beforeEntry = beforeFiles.get(pathKey);
+    const afterEntry = afterFiles.get(pathKey);
+    let operation = "";
+    if (!beforeEntry && afterEntry) {
+      operation = "create";
+    } else if (beforeEntry && !afterEntry) {
+      operation = "delete";
+    } else if (
+      beforeEntry
+      && afterEntry
+      && (
+        beforeEntry.mtimeMs !== afterEntry.mtimeMs
+        || beforeEntry.sizeBytes !== afterEntry.sizeBytes
+      )
+    ) {
+      operation = "update";
+    }
+    if (!operation) {
+      continue;
+    }
+    const reportedArtifact = safeObject(reportedByPath.get(pathKey));
+    const relativePath = normalizeWorkspaceRelativeArtifactPath(
+      afterEntry?.relativePath
+      || beforeEntry?.relativePath
+      || reportedArtifact.path
+      || "",
+    );
+    if (!shouldTrackWorkspaceArtifactRelativePath(relativePath)) {
+      continue;
+    }
+    observedPathKeys.add(pathKey);
+    observedArtifacts.push({
+      path: relativePath,
+      kind: String(reportedArtifact.kind || "").trim(),
+      operation,
+    });
+  }
+  return {
+    snapshot: afterSnapshot,
+    reportedArtifacts: reported,
+    artifacts: observedArtifacts,
+    unmatchedReportedArtifacts: reported.filter((item) => {
+      const normalizedPath = normalizeArtifactPathForRuntimeCompare(item.path || item.relativePath || "");
+      return normalizedPath && !observedPathKeys.has(normalizedPath);
+    }),
+  };
+}
+
 function resolveRunnerUserHomeDir(env) {
   const envHome = firstNonEmptyString([env?.CLAUDE_HOME, env?.USERPROFILE, env?.HOME, os.homedir()]);
   return envHome ? path.resolve(envHome) : "";
@@ -419,24 +577,20 @@ function detectExternalArtifactBoundaryViolations({ snapshot, workspaceDir }) {
 export function validateWorkspaceArtifacts(artifacts, workspaceDir, options = {}) {
   const normalizedWorkspaceDir = ensureWorkspaceDir(workspaceDir);
   const normalizedPermissionMode = normalizeLocalAIPermissionMode(options.permissionMode, "read_only");
-  const internalRuntimeRoots = [
-    path.join(normalizedWorkspaceDir, ".claude", "plans"),
-  ];
   const normalizedArtifacts = normalizeExecutionArtifacts(artifacts).map((artifact) => {
     const rawPath = String(artifact.path || "").trim();
     const resolvedPath = path.isAbsolute(rawPath)
       ? path.resolve(rawPath)
       : path.resolve(normalizedWorkspaceDir, rawPath);
-    const internalRuntimeArtifact = internalRuntimeRoots.some((rootDir) => (
-      isPathWithinWorkspace(resolvedPath, rootDir)
-    ));
+    const relativePath = isPathWithinWorkspace(resolvedPath, normalizedWorkspaceDir)
+      ? path.relative(normalizedWorkspaceDir, resolvedPath) || "."
+      : "";
+    const internalRuntimeArtifact = isInternalRuntimeArtifactPath(relativePath);
     return {
       ...artifact,
       path: rawPath,
       resolvedPath,
-      relativePath: isPathWithinWorkspace(resolvedPath, normalizedWorkspaceDir)
-        ? path.relative(normalizedWorkspaceDir, resolvedPath) || "."
-        : "",
+      relativePath,
       internalRuntimeArtifact,
     };
   });
@@ -469,12 +623,34 @@ function normalizeArtifactPathForRuntimeCompare(rawPath = "") {
   return normalized.replace(/^\.\/+/, "");
 }
 
+const INTERNAL_LOCAL_AI_RUNTIME_SCRATCH_RELATIVE_DIR = ".metheus/runner-runtime/local-ai-scratch";
+const NON_PROJECT_WORKSPACE_ARTIFACT_PREFIXES = [
+  ".git/",
+  "node_modules/",
+];
+const NON_PROJECT_WORKSPACE_ARTIFACT_EXACT_PATHS = new Set([
+  ".metheus_ctxpack_sync.json",
+  ".git",
+  "node_modules",
+]);
+
 export function isInternalRuntimeArtifactPath(rawPath = "") {
   const normalized = normalizeArtifactPathForRuntimeCompare(rawPath);
-  return normalized === ".claude/plans"
-    || normalized.startsWith(".claude/plans/")
+  if (!normalized) {
+    return false;
+  }
+  if (
+    normalized === INTERNAL_LOCAL_AI_RUNTIME_SCRATCH_RELATIVE_DIR
+    || normalized.startsWith(`${INTERNAL_LOCAL_AI_RUNTIME_SCRATCH_RELATIVE_DIR}/`)
     || normalized === ".metheus/ctxpack-cache"
-    || normalized.startsWith(".metheus/ctxpack-cache/");
+    || normalized.startsWith(".metheus/ctxpack-cache/")
+  ) {
+    return true;
+  }
+  if (NON_PROJECT_WORKSPACE_ARTIFACT_EXACT_PATHS.has(normalized)) {
+    return true;
+  }
+  return NON_PROJECT_WORKSPACE_ARTIFACT_PREFIXES.some((prefix) => normalized.startsWith(prefix));
 }
 
 function runCodexRawText({ promptText, workspaceDir, model, permissionMode, reasoningEffort, env }) {
@@ -514,7 +690,7 @@ function runCodexRawText({ promptText, workspaceDir, model, permissionMode, reas
 
 function prepareClaudeRuntimeConfig({ workspaceDir }) {
   const normalizedWorkspaceDir = ensureWorkspaceDir(workspaceDir);
-  const plansDirectory = path.join(normalizedWorkspaceDir, ".claude", "plans");
+  const plansDirectory = path.join(normalizedWorkspaceDir, ".metheus", "runner-runtime", "local-ai-scratch");
   fs.mkdirSync(plansDirectory, { recursive: true });
   const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "metheus-claude-settings-"));
   const settingsPath = path.join(tempDir, "settings.json");
@@ -682,6 +858,7 @@ function normalizeCliOutput(rawText) {
       replyToMessageID: intFromRawAllowZero(parsed.reply_to_message_id ?? parsed.replyToMessageID, 0),
       contract,
       artifacts: normalizeExecutionArtifacts(parsed.artifacts ?? parsed.files ?? parsed.outputs),
+      ctxpackFiles: normalizeExecutionCtxpackFiles(parsed.ctxpack_files ?? parsed.ctxpackFiles),
       workItems: normalizeExecutionWorkItems(parsed.work_items ?? parsed.workItems),
       raw: parsed,
     };
@@ -692,6 +869,7 @@ function normalizeCliOutput(rawText) {
     replyToMessageID: 0,
     contract: null,
     artifacts: [],
+    ctxpackFiles: [],
     workItems: [],
     raw: text,
   };
@@ -1321,7 +1499,7 @@ export function buildLocalBotPrompt(payload, { terse = true } = {}) {
       "Do the work for this step now. Do not say you will start later, wait, come back later, or plan first.",
       "If this is a worker step, actually create/update the required project artifacts now and include them in artifacts.",
       executionStep.ctxpack_update_required === true || executionStep.ctxpackUpdateRequired === true
-        ? "This step must update project guidance/specification content that belongs in the workspace as ctxpack source material. Update concrete workspace files now. Do not treat .metheus/ctxpack-cache or .claude/plans as the final authoring target. Use official project files inside the workspace such as doc/, docs/, README.md, or other explicit project paths, and include every changed ctxpack source file in artifacts so the server ctxpack can be updated from them."
+        ? "This step must update project guidance/specification content that belongs in ctxpack-backed workspace source files. Return every official guide/instruction/spec file in ctxpack_files with path, content, and doc_type so the runner can materialize those files and update server ctxpack. The workspace .metheus directory may contain official ctxpack source files, but do not treat .metheus/ctxpack-cache, .metheus/runner-runtime/local-ai-scratch, .metheus_ctxpack_sync.json, or .claude/ as final authoring targets. Use official project files such as .metheus/... source docs, doc/, docs/, README.md, or other explicit project paths."
         : "",
       executionStep.work_items_required === true || executionStep.workItemsRequired === true
         ? "This step must also break the work into executable governance work items. Return them in work_items with atomic titles and useful descriptions."
@@ -1381,12 +1559,12 @@ export function buildLocalBotPrompt(payload, { terse = true } = {}) {
     "- Do not claim that a file, plan, document, or code change is complete unless the corresponding artifact path is present in artifacts.",
     "",
     isInternalExecutionStep
-      ? "Return JSON only in one line: {\"reply\":\"what was completed in this step\",\"artifacts\":[{\"path\":\"relative/or/absolute/path\",\"kind\":\"plan|code|doc|spec|test\",\"operation\":\"create|update|delete\"}],\"work_items\":[{\"title\":\"short atomic task\",\"description\":\"useful implementation detail\"}],\"contract\":{\"type\":\"direct_result|summary_request|final_summary\",\"actionable\":true,\"summary_bot\":\"username\",\"next_responders\":[\"username\"]}}. Use artifacts: [] only if this step truly changes no project files, and use work_items: [] only if this step truly creates no governance tasks."
+      ? "Return JSON only in one line: {\"reply\":\"what was completed in this step\",\"artifacts\":[{\"path\":\"relative/or/absolute/path\",\"kind\":\"plan|code|doc|spec|test\",\"operation\":\"create|update|delete\"}],\"ctxpack_files\":[{\"path\":\"relative/path.md\",\"content\":\"full document text\",\"doc_type\":\"guide|readme|agenda|rule|architecture|manifest\",\"operation\":\"create|update|delete\"}],\"work_items\":[{\"title\":\"short atomic task\",\"description\":\"useful implementation detail\"}],\"contract\":{\"type\":\"direct_result|summary_request|final_summary\",\"actionable\":true,\"summary_bot\":\"username\",\"next_responders\":[\"username\"]}}. Use ctxpack_files when ctxpack-backed guidance/instruction files must be authored. Use artifacts: [] only if this step truly changes no project files, and use work_items: [] only if this step truly creates no governance tasks."
       : responseContract.must_reply === true
-      ? "Return JSON only in one line: {\"reply\":\"...\",\"artifacts\":[],\"work_items\":[]} or {\"reply\":\"...\",\"artifacts\":[],\"work_items\":[],\"contract\":{\"type\":\"direct_result|delegation|summary_request|final_summary\",\"actionable\":true,\"assignments\":[{\"target_bot\":\"username\",\"task\":\"...\"}],\"summary_bot\":\"username\",\"next_responders\":[\"username\"]}}."
+      ? "Return JSON only in one line: {\"reply\":\"...\",\"artifacts\":[],\"ctxpack_files\":[],\"work_items\":[]} or {\"reply\":\"...\",\"artifacts\":[],\"ctxpack_files\":[],\"work_items\":[],\"contract\":{\"type\":\"direct_result|delegation|summary_request|final_summary\",\"actionable\":true,\"assignments\":[{\"target_bot\":\"username\",\"task\":\"...\"}],\"summary_bot\":\"username\",\"next_responders\":[\"username\"]}}."
       : terse
-        ? "Return JSON only in one line: {\"reply\":\"...\",\"artifacts\":[],\"work_items\":[]} or {\"skip\":true,\"reason\":\"...\"}."
-        : "Return JSON only: {\"reply\":\"...\",\"artifacts\":[],\"work_items\":[]} or {\"skip\":true,\"reason\":\"...\"}. Keep the reply concise and directly useful in a group chat.",
+        ? "Return JSON only in one line: {\"reply\":\"...\",\"artifacts\":[],\"ctxpack_files\":[],\"work_items\":[]} or {\"skip\":true,\"reason\":\"...\"}."
+        : "Return JSON only: {\"reply\":\"...\",\"artifacts\":[],\"ctxpack_files\":[],\"work_items\":[]} or {\"skip\":true,\"reason\":\"...\"}. Keep the reply concise and directly useful in a group chat.",
   );
   if (conversation?.mode === "public_multi_bot") {
     const roleGuidance = {
@@ -1526,6 +1704,7 @@ export function serializeLocalAIResult(result) {
   return JSON.stringify({
     reply: String(result?.reply || "").trim(),
     artifacts: normalizeExecutionArtifacts(result?.artifacts),
+    ctxpack_files: normalizeExecutionCtxpackFiles(result?.ctxpackFiles),
     work_items: normalizeExecutionWorkItems(result?.workItems),
     ...(Array.isArray(result?.boundaryViolations) && result.boundaryViolations.length > 0
       ? { boundary_violations: result.boundaryViolations }
@@ -2078,6 +2257,7 @@ export function runLocalAIClient({
     return {
       ...sampleResult,
       artifacts: normalizeExecutionArtifacts(sampleResult?.artifacts),
+      ctxpackFiles: normalizeExecutionCtxpackFiles(sampleResult?.ctxpackFiles),
       boundaryViolations: [],
     };
   }
@@ -2129,6 +2309,7 @@ export function runLocalAIClient({
   return {
     ...safeObject(result),
     artifacts: normalizeExecutionArtifacts(result?.artifacts),
+    ctxpackFiles: normalizeExecutionCtxpackFiles(result?.ctxpackFiles),
     boundaryViolations: detectExternalArtifactBoundaryViolations({
       snapshot: boundarySnapshot,
       workspaceDir: resolvedWorkspaceDir,

package/lib/proxy-gateway-request.mjs

@@ -24,7 +24,7 @@ export async function handleProxyGatewayRequest(
   },
   deps,
 ) {
-  const injectCtxpackPushDefaults = requireDependency(deps, "injectCtxpackPushDefaults");
+  const injectCtxpackUpdateDefaults = requireDependency(deps, "injectCtxpackUpdateDefaults");
   const injectCtxpackPreflightToken = requireDependency(deps, "injectCtxpackPreflightToken");
   const stripLocalOnlyToolArgs = requireDependency(deps, "stripLocalOnlyToolArgs");
   const postJSON = requireDependency(deps, "postJSON");
@@ -32,7 +32,7 @@ export async function handleProxyGatewayRequest(
   const appendCtxpackConflictHintToErrorResponse = requireDependency(deps, "appendCtxpackConflictHintToErrorResponse");
   const applyProxyResponsePatches = requireDependency(deps, "applyProxyResponsePatches");
 
-  const requestWithDefaults = injectCtxpackPushDefaults(requestObj, toolName, requestWorkspaceDir);
+  const requestWithDefaults = injectCtxpackUpdateDefaults(requestObj, toolName, requestWorkspaceDir);
   const outboundRequestObj = stripLocalOnlyToolArgs(
     await injectCtxpackPreflightToken(
       requestWithDefaults,

package/lib/proxy-tool-helpers.mjs

@@ -390,7 +390,7 @@ export function stripLocalOnlyToolArgs(requestObj) {
   return { ...requestObj, params: nextParams };
 }
 
-export function injectCtxpackPushDefaults(
+export function injectCtxpackUpdateDefaults(
   {
     requestObj,
     toolName,
@@ -402,10 +402,10 @@ export function injectCtxpackPushDefaults(
   const loadWorkspaceMeta = requireDependency(deps, "loadWorkspaceMeta");
   const isUUID = requireDependency(deps, "isUUID");
 
-  const pushToolNames = ensureArray(deps?.ctxpackPushToolNames);
+  const updateToolNames = ensureArray(deps?.ctxpackUpdateToolNames);
   if (!isJsonRpcMethod(requestObj, "tools/call")) return requestObj;
   const normalizedTool = String(toolName || "").trim().toLowerCase();
-  if (!pushToolNames.includes(normalizedTool)) {
+  if (!updateToolNames.includes(normalizedTool)) {
     return requestObj;
   }
 
@@ -467,13 +467,13 @@ export async function injectCtxpackPreflightToken(
   const postJSON = requireDependency(deps, "postJSON");
   const tryJsonParse = requireDependency(deps, "tryJsonParse");
 
-  const pushToolNames = ensureArray(deps?.ctxpackPushToolNames);
+  const updateToolNames = ensureArray(deps?.ctxpackUpdateToolNames);
 
   if (!isJsonRpcMethod(requestObj, "tools/call")) return requestObj;
   if (!token) return requestObj;
 
   const normalizedTool = String(toolName || "").trim().toLowerCase();
-  if (!pushToolNames.includes(normalizedTool)) {
+  if (!updateToolNames.includes(normalizedTool)) {
     return requestObj;
   }
 
@@ -591,7 +591,7 @@ export async function appendCtxpackConflictHintToErrorResponse(
       autoPullHint = ` auto-pull failed: ${String(err?.message || err)}`;
     }
   }
-  const hint = `stale baseline detected. run 'metheus-governance-mcp ctxpack pull --project-id ${projectIDHint} --base-url ${baseURL}', merge local edits, then retry safe push.${autoPullHint}`;
+  const hint = `stale baseline detected. run 'metheus-governance-mcp ctxpack pull --project-id ${projectIDHint} --base-url ${baseURL}', merge local edits, then retry ctxpack.update.${autoPullHint}`;
   const nextError = { ...errObj, message: `${message}; ${hint}` };
   return { ...out, error: nextError };
 }