metheus-governance-mcp-cli 0.2.159 → 0.2.161

package/README.md

@@ -516,6 +516,8 @@ Workspace/source-of-truth model:
 - `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
+- `.metheus_ctxpack_sync.json` is sync metadata only; do not treat it as an official ctxpack source document
+- Official ctxpack authoring may live under normal project files or `.metheus/...` authoring paths, but exclude cache/runtime/metadata paths such as `.metheus/ctxpack-cache/`, `.metheus/runner-runtime/`, and `.metheus_ctxpack_sync.json`
 
 Role profile fields:
 - `client`: `gpt`, `claude`, `gemini`, or `sample`
@@ -664,6 +666,9 @@ metheus-governance-mcp-cli ctxpack pull --project-id <project_uuid> --base-url h
 Canonical ctxpack write tool name:
 - use `ctxpack.update`
 - do not use legacy names like `ctxpack.push` or `ctxpack.save`
+- chat/runner guidance:
+  - use `ctxpack.update` for official project guidance/instruction/policy/spec requests
+  - do not force `ctxpack.update` for normal README or generic implementation-document requests unless the request explicitly asks for official project guidance
 
 When `workitem.list` returns empty, proxy appends a hint to call `project.summary` first.
 

package/lib/local-ai-adapters.mjs

@@ -1499,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 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. Prefer official source paths under .metheus/project-guides/, .metheus/rules/, or other explicit workspace authoring paths when you are writing project guidance or instructions. Do not treat .metheus/ctxpack-cache, .metheus/runner-runtime/local-ai-scratch, .metheus_ctxpack_sync.json, or .claude/ as final authoring targets."
+        ? "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. A ctxpack update step is incomplete if ctxpack_files is empty. Prefer official source paths under .metheus/project-guides/, .metheus/rules/, or other explicit workspace authoring paths when you are writing project guidance or instructions. Do not treat .metheus/ctxpack-cache, .metheus/runner-runtime/local-ai-scratch, .metheus_ctxpack_sync.json, or .claude/ as final authoring targets."
         : "",
       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."
@@ -1559,7 +1559,7 @@ 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\"}],\"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."
+      ? "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. If execution_step.ctxpack_update_required is true, ctxpack_files must not be empty. 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\":[],\"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

package/lib/runner-orchestration.mjs

@@ -174,6 +174,21 @@ function buildExecutionFailureReplyText(detail) {
   if (/ctxpack\.update requires project ctxpack write access|ctxpack write access|ctxpack update permission|forbidden/i.test(normalizedDetail) && /ctxpack/i.test(normalizedDetail)) {
     return "I could not complete this request because the authenticated actor does not have ctxpack update permission for this project.";
   }
+  if (/ctxpack version_id is missing/i.test(normalizedDetail)) {
+    return "I could not complete this request because the project ctxpack version is missing. Refresh the project summary or ctxpack first.";
+  }
+  if (/ctxpack source path is not an official project authoring target|ctxpack source path is outside workspace|ctxpack source file \".*\" is missing content|ctxpack_files entry is missing path|ctxpack update step returned no ctxpack_files|did not produce any official ctxpack source files|ctxpack update produced no pushable ctxpack files|ctxpack\.update requires at least one validated official ctxpack source file/i.test(normalizedDetail)) {
+    return "I could not complete this request because the ctxpack update did not produce valid official ctxpack source files inside the workspace.";
+  }
+  if (/ctxpack source artifact is missing from workspace/i.test(normalizedDetail)) {
+    return "I could not complete this request because the ctxpack source files were not present in the workspace when the update ran.";
+  }
+  if (/invalid json response from ctxpack update/i.test(normalizedDetail)) {
+    return "I could not complete this request because the server returned an invalid response for the ctxpack update.";
+  }
+  if (/ctxpack/i.test(normalizedDetail) && /ECONNABORTED|ECONNRESET|ETIMEDOUT|http timeout|socket hang up|aborted/i.test(normalizedDetail)) {
+    return "I could not complete this request because the server ctxpack update request did not complete.";
+  }
   if (/ctxpack/i.test(normalizedDetail)) {
     return "I could not complete this request because the required ctxpack update did not succeed.";
   }
@@ -875,6 +890,18 @@ async function pushExecutionStepCtxpack({
       errors: ["runner execution dependency \"replaceProjectCtxpackFiles\" is required for ctxpack update steps"],
     };
   }
+  const pushableArtifacts = ensureArray(validatedArtifacts)
+    .filter((item) => {
+      const artifact = safeObject(item);
+      const artifactPath = String(artifact.relativePath || artifact.path || "").trim();
+      return artifactPath && !isDisallowedCtxpackSourceRelativePath(artifactPath);
+    });
+  if (!pushableArtifacts.length) {
+    return {
+      ctxpack: null,
+      errors: ["ctxpack.update requires at least one validated official ctxpack source file inside the workspace"],
+    };
+  }
   try {
     const response = await replaceProjectCtxpackFiles({
       siteBaseURL: runtime.baseURL,
@@ -883,7 +910,7 @@ async function pushExecutionStepCtxpack({
       actorUserID: safeObject(runtime.actor).user_id,
       projectID: normalizedRoute.projectID,
       workspaceDir: String(runtime.workspaceDir || "").trim() || String(normalizedRoute.workspaceDir || "").trim(),
-      artifacts: validatedArtifacts,
+      artifacts: pushableArtifacts,
     });
     return {
       ctxpack: {
@@ -907,6 +934,36 @@ async function pushExecutionStepCtxpack({
         ],
       };
     }
+    if (/ctxpack version_id is missing/i.test(detail)) {
+      return {
+        ctxpack: null,
+        errors: ["ctxpack version_id is missing; run ctxpack pull or refresh project summary first"],
+      };
+    }
+    if (/ctxpack update produced no pushable ctxpack files/i.test(detail)) {
+      return {
+        ctxpack: null,
+        errors: ["ctxpack update produced no pushable ctxpack source files"],
+      };
+    }
+    if (/ctxpack source artifact is missing from workspace/i.test(detail)) {
+      return {
+        ctxpack: null,
+        errors: [detail],
+      };
+    }
+    if (/invalid json response from ctxpack update/i.test(detail)) {
+      return {
+        ctxpack: null,
+        errors: ["server ctxpack update returned an invalid JSON response"],
+      };
+    }
+    if (/ECONNABORTED|ECONNRESET|ETIMEDOUT|http timeout|socket hang up|aborted/i.test(detail)) {
+      return {
+        ctxpack: null,
+        errors: [`ctxpack.update server request aborted before completion: ${detail}`],
+      };
+    }
     return {
       ctxpack: null,
       errors: [`failed to update project ctxpack for step "${String(safeObject(step).goal || safeObject(step).role || "ctxpack update").trim()}": ${detail}`],
@@ -1573,6 +1630,14 @@ async function maybeExecuteDynamicRolePlan({
     ) {
       stepErrors.push(`${String(step.role || "").trim()} step only produced internal runtime scratch files; create official workspace files for ctxpack source material`);
     }
+    if (safeObject(step).ctxpackUpdateRequired === true) {
+      if (ensureArray(stepResult?.ctxpackFiles).length === 0) {
+        stepErrors.push(`${String(step.role || "").trim()} step returned no ctxpack_files for a required ctxpack update`);
+      }
+      if (ensureArray(ctxpackMaterialization.artifacts).length === 0) {
+        stepErrors.push(`${String(step.role || "").trim()} step did not produce any official ctxpack source files inside the workspace`);
+      }
+    }
     if (requiresArtifactsForExecutionStep(step) && ensureArray(stepValidation.artifacts).length === 0) {
       if (reportedArtifactPaths.length > 0) {
         stepErrors.push(`${String(step.role || "").trim()} step reported project artifacts that were not observed in the workspace`);

package/lib/selftest-runner-scenarios.mjs

@@ -4137,6 +4137,13 @@ export async function runSelftestRunnerScenarios(push, deps) {
               skip: false,
               reply: "Created the implementation plan and broke the work into governance tasks.",
               artifacts: [{ path: "doc/implementation-plan.md", kind: "plan", operation: "create" }],
+              ctxpackFiles: [
+                {
+                  path: "doc/implementation-plan.md",
+                  docType: "guide",
+                  content: "# Implementation Plan\n",
+                },
+              ],
               workItems: [
                 { title: "Create API specification", description: "Draft the first API contract from the implementation plan." },
                 { title: "Implement onboarding flow", description: "Build the first user onboarding screens and state handling." },
@@ -4575,6 +4582,13 @@ export async function runSelftestRunnerScenarios(push, deps) {
               skip: false,
               reply: "Updated the implementation guide in the workspace.",
               artifacts: [{ path: "docs/implementation-guide.md", kind: "doc", operation: "update" }],
+              ctxpackFiles: [
+                {
+                  path: "docs/implementation-guide.md",
+                  docType: "guide",
+                  content: "# Implementation Guide\n",
+                },
+              ],
               workItems: [],
             };
           }
@@ -4987,6 +5001,13 @@ export async function runSelftestRunnerScenarios(push, deps) {
               skip: false,
               reply: "Updated the implementation guide in the workspace.",
               artifacts: [{ path: "docs/implementation-guide.md", kind: "doc", operation: "update" }],
+              ctxpackFiles: [
+                {
+                  path: "docs/implementation-guide.md",
+                  docType: "guide",
+                  content: "# Implementation Guide\n",
+                },
+              ],
               workItems: [],
             };
           }
@@ -5081,13 +5102,13 @@ export async function runSelftestRunnerScenarios(push, deps) {
     let deliveryCalls = 0;
     let deliveredText = "";
     let ctxpackUpdateCalls = 0;
-    const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), "metheus-runner-selftest-ctxpack-guidance-force-"));
+    const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), "metheus-runner-selftest-ctxpack-requires-files-"));
     const expectedPath = ".metheus/project-guides/project-operating-guide.md";
     const expectedAbsolutePath = path.join(workspaceDir, ".metheus", "project-guides", "project-operating-guide.md");
     const processed = await processRunnerSelectedRecord({
-      routeKey: "single-bot-ctxpack-guidance-force-key",
+      routeKey: "single-bot-ctxpack-requires-files-key",
       normalizedRoute: normalizeRunnerRoute({
-        name: "telegram-monitor-single-bot-ctxpack-guidance-force",
+        name: "telegram-monitor-single-bot-ctxpack-requires-files",
         project_id: selftestProjectID,
         provider: "telegram",
         role: "monitor",
@@ -5110,16 +5131,16 @@ export async function runSelftestRunnerScenarios(push, deps) {
         dry_run_delivery: true,
       }),
       selectedRecord: {
-        id: "comment-single-bot-ctxpack-guidance-force",
-        createdAt: "2026-03-17T01:00:05.750Z",
+        id: "comment-single-bot-ctxpack-requires-files",
+        createdAt: "2026-03-17T01:00:05.625Z",
         parsedArchive: {
           kind: "telegram_message",
           chatID: "-100123",
           chatType: "supergroup",
           senderIsBot: false,
-          body: "@RyoAI_bot 프로젝트 운영 가이드를 작성해서 ctxpack에 반영해줘.",
+          body: "@RyoAI_bot update the operating guide in ctxpack.",
           mentionUsernames: ["RyoAI_bot"],
-          messageID: 1310,
+          messageID: 13095,
         },
       },
       pendingOrdered: [],
@@ -5167,7 +5188,197 @@ export async function runSelftestRunnerScenarios(push, deps) {
           if (stepRole === "monitor") {
             return {
               skip: false,
-              reply: "Identified this as an official project guidance update request.",
+              reply: "Classified this as a ctxpack guidance update request.",
+            };
+          }
+          if (stepRole === "worker") {
+            fs.mkdirSync(path.dirname(expectedAbsolutePath), { recursive: true });
+            fs.writeFileSync(expectedAbsolutePath, "# Project Operating Guide\n", "utf8");
+            return {
+              skip: false,
+              reply: "Updated the guide file.",
+              artifacts: [{ path: expectedPath, kind: "doc", operation: "update" }],
+              workItems: [],
+            };
+          }
+          throw new Error(`unexpected step role ${stepRole}`);
+        },
+        performLocalBotDelivery: async ({ text }) => {
+          deliveryCalls += 1;
+          deliveredText = String(text || "");
+          return {
+            delivery: { dryRun: true, body: {} },
+            archive: {},
+          };
+        },
+        serializeRunnerTriggerPolicy: (value) => value,
+        serializeRunnerArchivePolicy: (value) => value,
+        buildRunnerExecutionDeps: () => ({
+          validateWorkspaceArtifacts,
+          analyzeHumanConversationIntentWithAI: async () => ({
+            mode: "single_bot",
+            lead_bot: "ryoai_bot",
+            participants: ["ryoai_bot"],
+            initial_responders: ["ryoai_bot"],
+            allowed_responders: ["ryoai_bot"],
+            summary_bot: "",
+            allow_bot_to_bot: false,
+            reply_expectation: "actionable",
+          }),
+          planRoleExecutionWithAI: async () => ({
+            requiresExecution: true,
+            summaryRole: "worker",
+            steps: [
+              { role: "monitor", goal: "Inspect the guidance request" },
+              {
+                role: "worker",
+                goal: "Update the operating guide in ctxpack",
+                artifactsRequired: true,
+                ctxpackUpdateRequired: true,
+                outputHint: expectedPath,
+              },
+            ],
+          }),
+          auditRoleExecutionPlanWithAI: async () => ({
+            requires_execution: true,
+            requires_worker_step: true,
+            requires_ctxpack_update_step: true,
+            plan_satisfies_request: true,
+            reason: "worker ctxpack step present",
+          }),
+          resolveRunnerExecutionPlanForRole: (_route, _bot, roleName) => ({
+            mode: "role_profile",
+            roleProfileName: String(roleName || "").trim(),
+            roleProfile: {
+              client: "sample",
+              model: "",
+              permissionMode: String(roleName || "").trim() === "worker" ? "workspace_write" : "read_only",
+              reasoningEffort: String(roleName || "").trim() === "worker" ? "medium" : "low",
+            },
+            workspaceDir,
+            workspaceSource: "selftest",
+            usedCommandFallback: false,
+          }),
+          replaceProjectCtxpackFiles: async () => {
+            ctxpackUpdateCalls += 1;
+            throw new Error("ctxpack.update should not run when ctxpack_files are missing");
+          },
+          loadBotRunnerConfig: () => ({
+            roleProfiles: {},
+            botBindings: {},
+            routes: [],
+            projectMappings: {},
+          }),
+        }),
+        buildRunnerDeliveryDeps: () => ({}),
+        buildRunnerRuntimeDeps: () => ({}),
+        resolveConversationPeerBots: () => [
+          { id: "bot-lead-1", name: "RyoAI_bot" },
+        ],
+      },
+    });
+    push(
+      "single_bot_ctxpack_update_requires_ctxpack_files",
+      processed.kind === "error"
+        && String(processed.result?.outcome || "") === "execution_failed"
+        && ctxpackUpdateCalls === 0
+        && deliveryCalls === 1
+        && /valid official ctxpack source files/i.test(deliveredText),
+      `kind=${String(processed.kind || "(none)")} outcome=${String(processed.result?.outcome || "(none)")} ctxpack_updates=${ctxpackUpdateCalls} delivery_calls=${deliveryCalls} delivered=${deliveredText} detail=${String(processed.result?.detail || "(none)")}`,
+    );
+  } catch (err) {
+    push("single_bot_ctxpack_update_requires_ctxpack_files", false, String(err?.message || err));
+  }
+
+  try {
+    let deliveryCalls = 0;
+    let deliveredText = "";
+    const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), "metheus-runner-selftest-ctxpack-version-missing-"));
+    const expectedPath = ".metheus/project-guides/project-operating-guide.md";
+    const processed = await processRunnerSelectedRecord({
+      routeKey: "single-bot-ctxpack-version-missing-key",
+      normalizedRoute: normalizeRunnerRoute({
+        name: "telegram-monitor-single-bot-ctxpack-version-missing",
+        project_id: selftestProjectID,
+        provider: "telegram",
+        role: "monitor",
+        role_profile: "monitor",
+        destination_id: "dest-1",
+        destination_label: "Main Room",
+        server_bot_name: "RyoAI_bot",
+        server_bot_id: "bot-lead-1",
+        trigger_policy: {
+          mentions_only: true,
+          direct_messages: true,
+          reply_to_bot_messages: true,
+        },
+        archive_policy: {
+          mirror_replies: true,
+          dedupe_inbound: true,
+          dedupe_outbound: true,
+          skip_bot_messages: true,
+        },
+        dry_run_delivery: true,
+      }),
+      selectedRecord: {
+        id: "comment-single-bot-ctxpack-version-missing",
+        createdAt: "2026-03-17T01:00:05.675Z",
+        parsedArchive: {
+          kind: "telegram_message",
+          chatID: "-100123",
+          chatType: "supergroup",
+          senderIsBot: false,
+          body: "@RyoAI_bot update the operating guide in ctxpack.",
+          mentionUsernames: ["RyoAI_bot"],
+          messageID: 13096,
+        },
+      },
+      pendingOrdered: [],
+      bot: {
+        id: "bot-lead-1",
+        name: "RyoAI_bot",
+        username: "RyoAI_bot",
+        role: "monitor",
+        provider: "telegram",
+      },
+      destination: {
+        id: "dest-1",
+        label: "Main Room",
+        provider: "telegram",
+        chatID: "-100123",
+      },
+      archiveThread: {
+        threadID: "thread-1",
+        workItemID: "work-item-1",
+      },
+      executionPlan: {
+        mode: "role_profile",
+        roleProfileName: "monitor",
+        roleProfile: {
+          client: "sample",
+          model: "",
+          permissionMode: "read_only",
+          reasoningEffort: "low",
+        },
+        workspaceDir,
+        workspaceSource: "selftest",
+        usedCommandFallback: false,
+      },
+      runtime: {
+        baseURL: "https://example.test",
+        token: "selftest-token",
+        timeoutSeconds: 30,
+        actor: { user_id: "user-1" },
+      },
+      deps: {
+        saveRunnerRouteState: () => {},
+        startRunnerTypingHeartbeat: () => ({ async stop() {} }),
+        runRunnerAIExecution: async ({ route }) => {
+          const stepRole = String(route?.role || "").trim().toLowerCase();
+          if (stepRole === "monitor") {
+            return {
+              skip: false,
+              reply: "Classified this as a ctxpack guidance update request.",
             };
           }
           if (stepRole === "worker") {
@@ -5179,7 +5390,7 @@ export async function runSelftestRunnerScenarios(push, deps) {
                 {
                   path: expectedPath,
                   docType: "guide",
-                  content: "# Project Operating Guide\n\nUse ctxpack-backed official guidance files.\n",
+                  content: "# Project Operating Guide\n\nVersion check required.\n",
                 },
               ],
               workItems: [],
@@ -5216,16 +5427,19 @@ export async function runSelftestRunnerScenarios(push, deps) {
               { role: "monitor", goal: "Inspect the guidance request" },
               {
                 role: "worker",
-                goal: "Draft the project operating guide",
+                goal: "Update the operating guide in ctxpack",
                 artifactsRequired: true,
+                ctxpackUpdateRequired: true,
+                outputHint: expectedPath,
               },
             ],
           }),
           auditRoleExecutionPlanWithAI: async () => ({
             requires_execution: true,
             requires_worker_step: true,
+            requires_ctxpack_update_step: true,
             plan_satisfies_request: true,
-            reason: "worker step present",
+            reason: "worker ctxpack step present",
           }),
           resolveRunnerExecutionPlanForRole: (_route, _bot, roleName) => ({
             mode: "role_profile",
@@ -5240,20 +5454,8 @@ export async function runSelftestRunnerScenarios(push, deps) {
             workspaceSource: "selftest",
             usedCommandFallback: false,
           }),
-          replaceProjectCtxpackFiles: async ({ artifacts }) => {
-            ctxpackUpdateCalls += 1;
-            return {
-              ctxpack_id: "ctxpack-3",
-              version_id: "version-ctxpack-3",
-              version: "0.3.0",
-              status: "draft",
-              files: ensureArray(artifacts).map((artifact) => ({
-                path: String(artifact.path || artifact.relativePath || "").trim(),
-                doc_type: "guide",
-              })),
-              pushed_file_count: ensureArray(artifacts).length,
-              changed_paths: ensureArray(artifacts).map((artifact) => String(artifact.path || artifact.relativePath || "").trim()),
-            };
+          replaceProjectCtxpackFiles: async () => {
+            throw new Error("ctxpack version_id is missing; run ctxpack pull or refresh project summary first");
           },
           loadBotRunnerConfig: () => ({
             roleProfiles: {},
@@ -5270,17 +5472,606 @@ export async function runSelftestRunnerScenarios(push, deps) {
       },
     });
     push(
-      "single_bot_guide_request_forces_ctxpack_update_when_planner_omits_it",
-      processed.kind === "replied"
-        && ctxpackUpdateCalls === 1
-        && fs.existsSync(expectedAbsolutePath)
-        && ensureArray(processed.result?.ctxpack_changed_paths).includes(expectedPath)
+      "single_bot_ctxpack_update_reports_missing_version",
+      processed.kind === "error"
+        && String(processed.result?.outcome || "") === "execution_failed"
         && deliveryCalls === 1
-        && /operating guide/i.test(deliveredText),
-      `kind=${String(processed.kind || "(none)")} ctxpack_updates=${ctxpackUpdateCalls} exists=${String(fs.existsSync(expectedAbsolutePath))} changed=${ensureArray(processed.result?.ctxpack_changed_paths).join(",")} delivered=${deliveredText}`,
+        && /ctxpack version is missing/i.test(deliveredText),
+      `kind=${String(processed.kind || "(none)")} outcome=${String(processed.result?.outcome || "(none)")} delivery_calls=${deliveryCalls} delivered=${deliveredText} detail=${String(processed.result?.detail || "(none)")}`,
     );
   } catch (err) {
-    push("single_bot_guide_request_forces_ctxpack_update_when_planner_omits_it", false, String(err?.message || err));
+    push("single_bot_ctxpack_update_reports_missing_version", false, String(err?.message || err));
+  }
+
+  try {
+    let deliveryCalls = 0;
+    let deliveredText = "";
+    const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), "metheus-runner-selftest-ctxpack-server-abort-"));
+    const expectedPath = ".metheus/project-guides/project-operating-guide.md";
+    const processed = await processRunnerSelectedRecord({
+      routeKey: "single-bot-ctxpack-server-abort-key",
+      normalizedRoute: normalizeRunnerRoute({
+        name: "telegram-monitor-single-bot-ctxpack-server-abort",
+        project_id: selftestProjectID,
+        provider: "telegram",
+        role: "monitor",
+        role_profile: "monitor",
+        destination_id: "dest-1",
+        destination_label: "Main Room",
+        server_bot_name: "RyoAI_bot",
+        server_bot_id: "bot-lead-1",
+        trigger_policy: {
+          mentions_only: true,
+          direct_messages: true,
+          reply_to_bot_messages: true,
+        },
+        archive_policy: {
+          mirror_replies: true,
+          dedupe_inbound: true,
+          dedupe_outbound: true,
+          skip_bot_messages: true,
+        },
+        dry_run_delivery: true,
+      }),
+      selectedRecord: {
+        id: "comment-single-bot-ctxpack-server-abort",
+        createdAt: "2026-03-17T01:00:05.700Z",
+        parsedArchive: {
+          kind: "telegram_message",
+          chatID: "-100123",
+          chatType: "supergroup",
+          senderIsBot: false,
+          body: "@RyoAI_bot update the operating guide in ctxpack.",
+          mentionUsernames: ["RyoAI_bot"],
+          messageID: 13097,
+        },
+      },
+      pendingOrdered: [],
+      bot: {
+        id: "bot-lead-1",
+        name: "RyoAI_bot",
+        username: "RyoAI_bot",
+        role: "monitor",
+        provider: "telegram",
+      },
+      destination: {
+        id: "dest-1",
+        label: "Main Room",
+        provider: "telegram",
+        chatID: "-100123",
+      },
+      archiveThread: {
+        threadID: "thread-1",
+        workItemID: "work-item-1",
+      },
+      executionPlan: {
+        mode: "role_profile",
+        roleProfileName: "monitor",
+        roleProfile: {
+          client: "sample",
+          model: "",
+          permissionMode: "read_only",
+          reasoningEffort: "low",
+        },
+        workspaceDir,
+        workspaceSource: "selftest",
+        usedCommandFallback: false,
+      },
+      runtime: {
+        baseURL: "https://example.test",
+        token: "selftest-token",
+        timeoutSeconds: 30,
+        actor: { user_id: "user-1" },
+      },
+      deps: {
+        saveRunnerRouteState: () => {},
+        startRunnerTypingHeartbeat: () => ({ async stop() {} }),
+        runRunnerAIExecution: async ({ route }) => {
+          const stepRole = String(route?.role || "").trim().toLowerCase();
+          if (stepRole === "monitor") {
+            return {
+              skip: false,
+              reply: "Classified this as a ctxpack guidance update request.",
+            };
+          }
+          if (stepRole === "worker") {
+            return {
+              skip: false,
+              reply: "Prepared the official operating guide content.",
+              artifacts: [],
+              ctxpackFiles: [
+                {
+                  path: expectedPath,
+                  docType: "guide",
+                  content: "# Project Operating Guide\n\nServer write must complete.\n",
+                },
+              ],
+              workItems: [],
+            };
+          }
+          throw new Error(`unexpected step role ${stepRole}`);
+        },
+        performLocalBotDelivery: async ({ text }) => {
+          deliveryCalls += 1;
+          deliveredText = String(text || "");
+          return {
+            delivery: { dryRun: true, body: {} },
+            archive: {},
+          };
+        },
+        serializeRunnerTriggerPolicy: (value) => value,
+        serializeRunnerArchivePolicy: (value) => value,
+        buildRunnerExecutionDeps: () => ({
+          validateWorkspaceArtifacts,
+          analyzeHumanConversationIntentWithAI: async () => ({
+            mode: "single_bot",
+            lead_bot: "ryoai_bot",
+            participants: ["ryoai_bot"],
+            initial_responders: ["ryoai_bot"],
+            allowed_responders: ["ryoai_bot"],
+            summary_bot: "",
+            allow_bot_to_bot: false,
+            reply_expectation: "actionable",
+          }),
+          planRoleExecutionWithAI: async () => ({
+            requiresExecution: true,
+            summaryRole: "worker",
+            steps: [
+              { role: "monitor", goal: "Inspect the guidance request" },
+              {
+                role: "worker",
+                goal: "Update the operating guide in ctxpack",
+                artifactsRequired: true,
+                ctxpackUpdateRequired: true,
+                outputHint: expectedPath,
+              },
+            ],
+          }),
+          auditRoleExecutionPlanWithAI: async () => ({
+            requires_execution: true,
+            requires_worker_step: true,
+            requires_ctxpack_update_step: true,
+            plan_satisfies_request: true,
+            reason: "worker ctxpack step present",
+          }),
+          resolveRunnerExecutionPlanForRole: (_route, _bot, roleName) => ({
+            mode: "role_profile",
+            roleProfileName: String(roleName || "").trim(),
+            roleProfile: {
+              client: "sample",
+              model: "",
+              permissionMode: String(roleName || "").trim() === "worker" ? "workspace_write" : "read_only",
+              reasoningEffort: String(roleName || "").trim() === "worker" ? "medium" : "low",
+            },
+            workspaceDir,
+            workspaceSource: "selftest",
+            usedCommandFallback: false,
+          }),
+          replaceProjectCtxpackFiles: async () => {
+            throw new Error("write ECONNABORTED");
+          },
+          loadBotRunnerConfig: () => ({
+            roleProfiles: {},
+            botBindings: {},
+            routes: [],
+            projectMappings: {},
+          }),
+        }),
+        buildRunnerDeliveryDeps: () => ({}),
+        buildRunnerRuntimeDeps: () => ({}),
+        resolveConversationPeerBots: () => [
+          { id: "bot-lead-1", name: "RyoAI_bot" },
+        ],
+      },
+    });
+    push(
+      "single_bot_ctxpack_update_reports_server_abort",
+      processed.kind === "error"
+        && String(processed.result?.outcome || "") === "execution_failed"
+        && deliveryCalls === 1
+        && /server ctxpack update request did not complete/i.test(deliveredText),
+      `kind=${String(processed.kind || "(none)")} outcome=${String(processed.result?.outcome || "(none)")} delivery_calls=${deliveryCalls} delivered=${deliveredText} detail=${String(processed.result?.detail || "(none)")}`,
+    );
+  } catch (err) {
+    push("single_bot_ctxpack_update_reports_server_abort", false, String(err?.message || err));
+  }
+
+  try {
+    let deliveryCalls = 0;
+    let deliveredText = "";
+    let ctxpackUpdateCalls = 0;
+    const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), "metheus-runner-selftest-ctxpack-guidance-force-"));
+    const expectedPath = ".metheus/project-guides/project-operating-guide.md";
+    const expectedAbsolutePath = path.join(workspaceDir, ".metheus", "project-guides", "project-operating-guide.md");
+    const processed = await processRunnerSelectedRecord({
+      routeKey: "single-bot-ctxpack-guidance-force-key",
+      normalizedRoute: normalizeRunnerRoute({
+        name: "telegram-monitor-single-bot-ctxpack-guidance-force",
+        project_id: selftestProjectID,
+        provider: "telegram",
+        role: "monitor",
+        role_profile: "monitor",
+        destination_id: "dest-1",
+        destination_label: "Main Room",
+        server_bot_name: "RyoAI_bot",
+        server_bot_id: "bot-lead-1",
+        trigger_policy: {
+          mentions_only: true,
+          direct_messages: true,
+          reply_to_bot_messages: true,
+        },
+        archive_policy: {
+          mirror_replies: true,
+          dedupe_inbound: true,
+          dedupe_outbound: true,
+          skip_bot_messages: true,
+        },
+        dry_run_delivery: true,
+      }),
+      selectedRecord: {
+        id: "comment-single-bot-ctxpack-guidance-force",
+        createdAt: "2026-03-17T01:00:05.750Z",
+        parsedArchive: {
+          kind: "telegram_message",
+          chatID: "-100123",
+          chatType: "supergroup",
+          senderIsBot: false,
+          body: "@RyoAI_bot 프로젝트 운영 가이드를 작성해서 ctxpack에 반영해줘.",
+          mentionUsernames: ["RyoAI_bot"],
+          messageID: 1310,
+        },
+      },
+      pendingOrdered: [],
+      bot: {
+        id: "bot-lead-1",
+        name: "RyoAI_bot",
+        username: "RyoAI_bot",
+        role: "monitor",
+        provider: "telegram",
+      },
+      destination: {
+        id: "dest-1",
+        label: "Main Room",
+        provider: "telegram",
+        chatID: "-100123",
+      },
+      archiveThread: {
+        threadID: "thread-1",
+        workItemID: "work-item-1",
+      },
+      executionPlan: {
+        mode: "role_profile",
+        roleProfileName: "monitor",
+        roleProfile: {
+          client: "sample",
+          model: "",
+          permissionMode: "read_only",
+          reasoningEffort: "low",
+        },
+        workspaceDir,
+        workspaceSource: "selftest",
+        usedCommandFallback: false,
+      },
+      runtime: {
+        baseURL: "https://example.test",
+        token: "selftest-token",
+        timeoutSeconds: 30,
+        actor: { user_id: "user-1" },
+      },
+      deps: {
+        saveRunnerRouteState: () => {},
+        startRunnerTypingHeartbeat: () => ({ async stop() {} }),
+        runRunnerAIExecution: async ({ route }) => {
+          const stepRole = String(route?.role || "").trim().toLowerCase();
+          if (stepRole === "monitor") {
+            return {
+              skip: false,
+              reply: "Identified this as an official project guidance update request.",
+            };
+          }
+          if (stepRole === "worker") {
+            return {
+              skip: false,
+              reply: "Prepared the official operating guide content.",
+              artifacts: [],
+              ctxpackFiles: [
+                {
+                  path: expectedPath,
+                  docType: "guide",
+                  content: "# Project Operating Guide\n\nUse ctxpack-backed official guidance files.\n",
+                },
+              ],
+              workItems: [],
+            };
+          }
+          throw new Error(`unexpected step role ${stepRole}`);
+        },
+        performLocalBotDelivery: async ({ text }) => {
+          deliveryCalls += 1;
+          deliveredText = String(text || "");
+          return {
+            delivery: { dryRun: true, body: {} },
+            archive: {},
+          };
+        },
+        serializeRunnerTriggerPolicy: (value) => value,
+        serializeRunnerArchivePolicy: (value) => value,
+        buildRunnerExecutionDeps: () => ({
+          validateWorkspaceArtifacts,
+          analyzeHumanConversationIntentWithAI: async () => ({
+            mode: "single_bot",
+            lead_bot: "ryoai_bot",
+            participants: ["ryoai_bot"],
+            initial_responders: ["ryoai_bot"],
+            allowed_responders: ["ryoai_bot"],
+            summary_bot: "",
+            allow_bot_to_bot: false,
+            reply_expectation: "actionable",
+          }),
+          planRoleExecutionWithAI: async () => ({
+            requiresExecution: true,
+            summaryRole: "worker",
+            steps: [
+              { role: "monitor", goal: "Inspect the guidance request" },
+              {
+                role: "worker",
+                goal: "Draft the project operating guide",
+                artifactsRequired: true,
+              },
+            ],
+          }),
+          auditRoleExecutionPlanWithAI: async () => ({
+            requires_execution: true,
+            requires_worker_step: true,
+            plan_satisfies_request: true,
+            reason: "worker step present",
+          }),
+          resolveRunnerExecutionPlanForRole: (_route, _bot, roleName) => ({
+            mode: "role_profile",
+            roleProfileName: String(roleName || "").trim(),
+            roleProfile: {
+              client: "sample",
+              model: "",
+              permissionMode: String(roleName || "").trim() === "worker" ? "workspace_write" : "read_only",
+              reasoningEffort: String(roleName || "").trim() === "worker" ? "medium" : "low",
+            },
+            workspaceDir,
+            workspaceSource: "selftest",
+            usedCommandFallback: false,
+          }),
+          replaceProjectCtxpackFiles: async ({ artifacts }) => {
+            ctxpackUpdateCalls += 1;
+            return {
+              ctxpack_id: "ctxpack-3",
+              version_id: "version-ctxpack-3",
+              version: "0.3.0",
+              status: "draft",
+              files: ensureArray(artifacts).map((artifact) => ({
+                path: String(artifact.path || artifact.relativePath || "").trim(),
+                doc_type: "guide",
+              })),
+              pushed_file_count: ensureArray(artifacts).length,
+              changed_paths: ensureArray(artifacts).map((artifact) => String(artifact.path || artifact.relativePath || "").trim()),
+            };
+          },
+          loadBotRunnerConfig: () => ({
+            roleProfiles: {},
+            botBindings: {},
+            routes: [],
+            projectMappings: {},
+          }),
+        }),
+        buildRunnerDeliveryDeps: () => ({}),
+        buildRunnerRuntimeDeps: () => ({}),
+        resolveConversationPeerBots: () => [
+          { id: "bot-lead-1", name: "RyoAI_bot" },
+        ],
+      },
+    });
+    push(
+      "single_bot_guide_request_forces_ctxpack_update_when_planner_omits_it",
+      processed.kind === "replied"
+        && ctxpackUpdateCalls === 1
+        && fs.existsSync(expectedAbsolutePath)
+        && ensureArray(processed.result?.ctxpack_changed_paths).includes(expectedPath)
+        && deliveryCalls === 1
+        && /operating guide/i.test(deliveredText),
+      `kind=${String(processed.kind || "(none)")} ctxpack_updates=${ctxpackUpdateCalls} exists=${String(fs.existsSync(expectedAbsolutePath))} changed=${ensureArray(processed.result?.ctxpack_changed_paths).join(",")} delivered=${deliveredText}`,
+    );
+  } catch (err) {
+    push("single_bot_guide_request_forces_ctxpack_update_when_planner_omits_it", false, String(err?.message || err));
+  }
+
+  try {
+    let deliveryCalls = 0;
+    let deliveredText = "";
+    let ctxpackUpdateCalls = 0;
+    const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), "metheus-runner-selftest-readme-not-ctxpack-"));
+    const readmePath = path.join(workspaceDir, "README.md");
+    const processed = await processRunnerSelectedRecord({
+      routeKey: "single-bot-readme-not-ctxpack-key",
+      normalizedRoute: normalizeRunnerRoute({
+        name: "telegram-monitor-single-bot-readme-not-ctxpack",
+        project_id: selftestProjectID,
+        provider: "telegram",
+        role: "monitor",
+        role_profile: "monitor",
+        destination_id: "dest-1",
+        destination_label: "Main Room",
+        server_bot_name: "RyoAI_bot",
+        server_bot_id: "bot-lead-1",
+        trigger_policy: {
+          mentions_only: true,
+          direct_messages: true,
+          reply_to_bot_messages: true,
+        },
+        archive_policy: {
+          mirror_replies: true,
+          dedupe_inbound: true,
+          dedupe_outbound: true,
+          skip_bot_messages: true,
+        },
+        dry_run_delivery: true,
+      }),
+      selectedRecord: {
+        id: "comment-single-bot-readme-not-ctxpack",
+        createdAt: "2026-03-17T01:00:05.875Z",
+        parsedArchive: {
+          kind: "telegram_message",
+          chatID: "-100123",
+          chatType: "supergroup",
+          senderIsBot: false,
+          body: "@RyoAI_bot create the implementation README now.",
+          mentionUsernames: ["RyoAI_bot"],
+          messageID: 1311,
+        },
+      },
+      pendingOrdered: [],
+      bot: {
+        id: "bot-lead-1",
+        name: "RyoAI_bot",
+        username: "RyoAI_bot",
+        role: "monitor",
+        provider: "telegram",
+      },
+      destination: {
+        id: "dest-1",
+        label: "Main Room",
+        provider: "telegram",
+        chatID: "-100123",
+      },
+      archiveThread: {
+        threadID: "thread-1",
+        workItemID: "work-item-1",
+      },
+      executionPlan: {
+        mode: "role_profile",
+        roleProfileName: "monitor",
+        roleProfile: {
+          client: "sample",
+          model: "",
+          permissionMode: "read_only",
+          reasoningEffort: "low",
+        },
+        workspaceDir,
+        workspaceSource: "selftest",
+        usedCommandFallback: false,
+      },
+      runtime: {
+        baseURL: "https://example.test",
+        token: "selftest-token",
+        timeoutSeconds: 30,
+        actor: { user_id: "user-1" },
+      },
+      deps: {
+        saveRunnerRouteState: () => {},
+        startRunnerTypingHeartbeat: () => ({ async stop() {} }),
+        runRunnerAIExecution: async ({ route }) => {
+          const stepRole = String(route?.role || "").trim().toLowerCase();
+          if (stepRole === "monitor") {
+            return {
+              skip: false,
+              reply: "Identified this as a normal project README request.",
+            };
+          }
+          if (stepRole === "worker") {
+            fs.writeFileSync(readmePath, "# README\n", "utf8");
+            return {
+              skip: false,
+              reply: "Created the implementation README.",
+              artifacts: [
+                { path: "README.md", kind: "document", operation: "create" },
+              ],
+              workItems: [],
+            };
+          }
+          throw new Error(`unexpected step role ${stepRole}`);
+        },
+        performLocalBotDelivery: async ({ text }) => {
+          deliveryCalls += 1;
+          deliveredText = String(text || "");
+          return {
+            delivery: { dryRun: true, body: {} },
+            archive: {},
+          };
+        },
+        serializeRunnerTriggerPolicy: (value) => value,
+        serializeRunnerArchivePolicy: (value) => value,
+        buildRunnerExecutionDeps: () => ({
+          validateWorkspaceArtifacts,
+          analyzeHumanConversationIntentWithAI: async () => ({
+            mode: "single_bot",
+            lead_bot: "ryoai_bot",
+            participants: ["ryoai_bot"],
+            initial_responders: ["ryoai_bot"],
+            allowed_responders: ["ryoai_bot"],
+            summary_bot: "",
+            allow_bot_to_bot: false,
+            reply_expectation: "actionable",
+          }),
+          planRoleExecutionWithAI: async () => ({
+            requiresExecution: true,
+            summaryRole: "worker",
+            steps: [
+              { role: "monitor", goal: "Inspect the README request" },
+              {
+                role: "worker",
+                goal: "Create the README",
+                artifactsRequired: true,
+              },
+            ],
+          }),
+          auditRoleExecutionPlanWithAI: async () => ({
+            requires_execution: true,
+            requires_worker_step: true,
+            requires_ctxpack_update_step: false,
+            plan_satisfies_request: true,
+            reason: "worker step present",
+          }),
+          resolveRunnerExecutionPlanForRole: (_route, _bot, roleName) => ({
+            mode: "role_profile",
+            roleProfileName: String(roleName || "").trim(),
+            roleProfile: {
+              client: "sample",
+              model: "",
+              permissionMode: String(roleName || "").trim() === "worker" ? "workspace_write" : "read_only",
+              reasoningEffort: String(roleName || "").trim() === "worker" ? "medium" : "low",
+            },
+            workspaceDir,
+            workspaceSource: "selftest",
+            usedCommandFallback: false,
+          }),
+          replaceProjectCtxpackFiles: async () => {
+            ctxpackUpdateCalls += 1;
+            throw new Error("ctxpack update should not run for a plain README request");
+          },
+          loadBotRunnerConfig: () => ({
+            roleProfiles: {},
+            botBindings: {},
+            routes: [],
+            projectMappings: {},
+          }),
+        }),
+        buildRunnerDeliveryDeps: () => ({}),
+        buildRunnerRuntimeDeps: () => ({}),
+        resolveConversationPeerBots: () => [
+          { id: "bot-lead-1", name: "RyoAI_bot" },
+        ],
+      },
+    });
+    push(
+      "single_bot_readme_request_does_not_force_ctxpack_update",
+      processed.kind === "replied"
+        && ctxpackUpdateCalls === 0
+        && fs.existsSync(readmePath)
+        && ensureArray(processed.result?.artifact_paths).includes("README.md")
+        && ensureArray(processed.result?.ctxpack_changed_paths).length === 0
+        && deliveryCalls === 1
+        && /README/i.test(deliveredText),
+      `kind=${String(processed.kind || "(none)")} ctxpack_updates=${ctxpackUpdateCalls} exists=${String(fs.existsSync(readmePath))} artifacts=${ensureArray(processed.result?.artifact_paths).join(",")} changed=${ensureArray(processed.result?.ctxpack_changed_paths).join(",")} delivered=${deliveredText}`,
+    );
+  } catch (err) {
+    push("single_bot_readme_request_does_not_force_ctxpack_update", false, String(err?.message || err));
   }
 
   try {

package/package.json

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