@kontextmind/kxm 0.7.86 → 0.7.87

package/plugins/kxm/src/local-snapshot.ts

@@ -1,7 +1,7 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
-import { DatabaseSync } from "./sqlite.ts";
+import { DatabaseSync, openReadOnlyDatabase } from "./sqlite.ts";
 import type { AgentIdentity, AgentRecord, MessageRecord } from "./protocol.ts";
 import type { WorkflowRun } from "./workflow.ts";
 import { readRoutingRecords } from "./telemetry.ts";
@@ -250,7 +250,7 @@ export function loadLocalMeshSnapshot(
   let plans: MeshTuiPlan[] = [];
   if (existsSync(dataPath)) {
     hasLegacy = true;
-    const database = new DatabaseSync(dataPath, { readOnly: true });
+    const database = openReadOnlyDatabase(dataPath);
     try {
       database.exec("PRAGMA busy_timeout = 5000");
       // Stored rows carry identity only. Presence is derived here against the
@@ -287,7 +287,7 @@ export function loadLocalMeshSnapshot(
     if (existsSync(registryDbPath)) {
       hasKxm = true;
       try {
-        const regDb = new DatabaseSync(registryDbPath, { readOnly: true });
+        const regDb = openReadOnlyDatabase(registryDbPath);
         try {
           regDb.exec("PRAGMA busy_timeout = 5000");
           const pRows = regDb.prepare("SELECT project_key FROM projects").all() as Array<{ project_key: string }>;
@@ -315,7 +315,7 @@ export function loadLocalMeshSnapshot(
       if (existsSync(eventDbPath)) {
         hasKxm = true;
         try {
-          const eventDb = new DatabaseSync(eventDbPath, { readOnly: true });
+          const eventDb = openReadOnlyDatabase(eventDbPath);
           try {
             eventDb.exec("PRAGMA busy_timeout = 5000");
             const runRows = eventDb.prepare(`

package/plugins/kxm/src/mcp-server.ts

@@ -8,7 +8,7 @@ import { AGENT_COMMANDS_MAP, enforceToolPolicy, getMcpTools, reconcileInbox } fr
 import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 
-const VERSION = "0.7.86";
+const VERSION = "0.7.87";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();
 let meshClient: HubClient | undefined;

package/plugins/kxm/src/memory.ts

@@ -245,10 +245,10 @@ export function createMemoryNote(
     body?: string | undefined;
     sourceRef?: string | undefined;
     runId?: string | undefined;
+    dryRun?: boolean | undefined;
   } = {},
 ): { record: MemoryRecord; path: string } {
   const { candidatesDir } = memoryDirectories(repoRoot);
-  mkdirSync(candidatesDir, { recursive: true });
 
   const scope: MemoryScope = options.scope ?? "project";
   if (!VALID_SCOPES.has(scope)) {
@@ -277,6 +277,8 @@ export function createMemoryNote(
   };
 
   const targetPath = join(candidatesDir, `${id}.md`);
+  if (options.dryRun) return { record, path: targetPath };
+  mkdirSync(candidatesDir, { recursive: true });
   writeFileSync(targetPath, formatMemoryRecord(record), "utf8");
   return { record, path: targetPath };
 }
@@ -316,7 +318,8 @@ export function formatHarnessMemoryBlock(records: MemoryRecord[]): string {
   return contentLines.join("\n");
 }
 
-export function updateHarnessDocument(filePath: string, block: string, defaultHeader: string): boolean {
+/** Returns whether the projection block changed the file; `dryRun` answers without writing. */
+export function updateHarnessDocument(filePath: string, block: string, defaultHeader: string, dryRun = false): boolean {
   let original = "";
   if (existsSync(filePath)) {
     original = readFileSync(filePath, "utf8");
@@ -340,13 +343,13 @@ export function updateHarnessDocument(filePath: string, block: string, defaultHe
   }
 
   if (updated !== original) {
-    writeFileSync(filePath, updated, "utf8");
+    if (!dryRun) writeFileSync(filePath, updated, "utf8");
     return true;
   }
   return false;
 }
 
-export function syncHarnessMemory(repoRoot: string): { updated: string[]; created: string[] } {
+export function syncHarnessMemory(repoRoot: string, options: { dryRun?: boolean } = {}): { updated: string[]; created: string[] } {
   const root = resolve(repoRoot);
   const records = loadAuthoredMemory(root);
   const block = formatHarnessMemoryBlock(records);
@@ -358,7 +361,7 @@ export function syncHarnessMemory(repoRoot: string): { updated: string[]; create
   const agentsPath = join(root, "AGENTS.md");
   const agentsHeader = "# AGENTS\n\nFollow project instructions.\n";
   const agentsExisted = existsSync(agentsPath);
-  if (updateHarnessDocument(agentsPath, block, agentsHeader)) {
+  if (updateHarnessDocument(agentsPath, block, agentsHeader, options.dryRun)) {
     if (agentsExisted) updated.push("AGENTS.md");
     else created.push("AGENTS.md");
   }
@@ -367,7 +370,7 @@ export function syncHarnessMemory(repoRoot: string): { updated: string[]; create
   const claudePath = join(root, "CLAUDE.md");
   const claudeHeader = `# KXM (Claude)\n\nFollow [\`AGENTS.md\`](AGENTS.md). Official phase tracking:\n[\`plans/implementation-plan.md\`](plans/implementation-plan.md#tracking-working-tree-not-a-release).\n\nYou are the **planner / architecture critic** unless the human explicitly asks\nyou to implement. Default writer is native Grok CLI (\`grok --model grok-4.6\`) — a starting\nrotation, not a sole writer. If \`grok\` is logged out, never bill Grok through another harness;\nuse a relief route Tracking **admits**, or stop and name the limits hit. Your reviews are\nartifacts, not hub \`peer-reply\` evidence.\n`;
   const claudeExisted = existsSync(claudePath);
-  if (updateHarnessDocument(claudePath, block, claudeHeader)) {
+  if (updateHarnessDocument(claudePath, block, claudeHeader, options.dryRun)) {
     if (claudeExisted) updated.push("CLAUDE.md");
     else created.push("CLAUDE.md");
   }
@@ -376,7 +379,7 @@ export function syncHarnessMemory(repoRoot: string): { updated: string[]; create
   const geminiPath = join(root, "GEMINI.md");
   const geminiHeader = `# KXM (Gemini / Antigravity)\n\nFollow [\`AGENTS.md\`](AGENTS.md). Official phase tracking:\n[\`plans/implementation-plan.md\`](plans/implementation-plan.md#tracking-working-tree-not-a-release).\n\nGoogle goes through the \`antigravity\` **Pi provider** (Tracking \u2192 Decided,\n2026-09-15); \`agy\` stays a harness catalog/helper entry, not the admission path.\nCurrent admissions come from Tracking and \`kxm harness list\`. Starting rotation\nremains Grok.\n`;
   const geminiExisted = existsSync(geminiPath);
-  if (updateHarnessDocument(geminiPath, block, geminiHeader)) {
+  if (updateHarnessDocument(geminiPath, block, geminiHeader, options.dryRun)) {
     if (geminiExisted) updated.push("GEMINI.md");
     else created.push("GEMINI.md");
   }

package/plugins/kxm/src/role.ts

@@ -308,18 +308,21 @@ export function addRole(
     repoRoot?: string | undefined;
     userConfigDir?: string | undefined;
     overwrite?: boolean | undefined;
+    dryRun?: boolean | undefined;
   } = {},
 ): { id: string; filePath: string; scope: "global" | "local" } {
   const scope = options.scope ?? "local";
   const repoRoot = options.repoRoot ?? process.cwd();
-  const dir = ensureRolesDirectory(scope, repoRoot, options.userConfigDir);
+  const dir = options.dryRun
+    ? rolesDirectory(scope, repoRoot, options.userConfigDir)
+    : ensureRolesDirectory(scope, repoRoot, options.userConfigDir);
   const filePath = join(dir, `${role.id}.yaml`);
 
   if (existsSync(filePath) && !options.overwrite) {
     throw new Error(`role_already_exists: role '${role.id}' already exists at ${filePath}`);
   }
 
-  writeFileSync(filePath, stringify(role), "utf8");
+  if (!options.dryRun) writeFileSync(filePath, stringify(role), "utf8");
   return { id: role.id, filePath, scope };
 }
 
@@ -329,6 +332,7 @@ export function removeRole(
     scope?: "global" | "local" | undefined;
     repoRoot?: string | undefined;
     userConfigDir?: string | undefined;
+    dryRun?: boolean | undefined;
   } = {},
 ): { id: string; removed: boolean; filePath: string; scope: "global" | "local" } {
   const scope = options.scope ?? "local";
@@ -340,6 +344,7 @@ export function removeRole(
     throw new Error(`role_not_found: role '${roleId}' not found in ${scope} directory (${filePath})`);
   }
 
+  if (options.dryRun) return { id: roleId, removed: false, filePath, scope };
   rmSync(filePath);
   return { id: roleId, removed: true, filePath, scope };
 }
@@ -351,6 +356,7 @@ export function modifyRole(
     scope?: "global" | "local" | undefined;
     repoRoot?: string | undefined;
     userConfigDir?: string | undefined;
+    dryRun?: boolean | undefined;
   } = {},
 ): { id: string; role: KxmRoleDefinition; filePath: string; scope: "global" | "local" } {
   const target = getRole(roleId, { scope: options.scope, repoRoot: options.repoRoot, userConfigDir: options.userConfigDir });
@@ -367,10 +373,12 @@ export function modifyRole(
 
   const scope = options.scope ?? target.scope;
   const repoRoot = options.repoRoot ?? process.cwd();
-  const dir = ensureRolesDirectory(scope, repoRoot, options.userConfigDir);
+  const dir = options.dryRun
+    ? rolesDirectory(scope, repoRoot, options.userConfigDir)
+    : ensureRolesDirectory(scope, repoRoot, options.userConfigDir);
   const filePath = join(dir, `${roleId}.yaml`);
 
-  writeFileSync(filePath, stringify(updated), "utf8");
+  if (!options.dryRun) writeFileSync(filePath, stringify(updated), "utf8");
   return { id: roleId, role: updated, filePath, scope };
 }
 
@@ -562,17 +570,19 @@ export function saveRoleHostsConfig(
     repoRoot?: string | undefined;
     userConfigDir?: string | undefined;
     format?: "yaml" | "json" | undefined;
+    dryRun?: boolean | undefined;
   } = {},
 ): { filePath: string; scope: "global" | "local" } {
   const scope = options.scope ?? "local";
   const repoRoot = options.repoRoot ?? process.cwd();
   const dir = scope === "global" ? userConfigDirectory(options.userConfigDir) : repoConfigDirectory(repoRoot);
+  const format = options.format ?? "yaml";
+  const filePath = join(dir, format === "json" ? "role-hosts.json" : "role-hosts.yaml");
+  if (options.dryRun) return { filePath, scope };
   if (!existsSync(dir)) {
     mkdirSync(dir, { recursive: true });
   }
 
-  const format = options.format ?? "yaml";
-  const filePath = join(dir, format === "json" ? "role-hosts.json" : "role-hosts.yaml");
   const payload: RoleHostsConfig = {
     schema: KXM_ROLE_HOSTS_SCHEMA,
     seats: config.seats ?? {},
@@ -594,6 +604,7 @@ export function setRoleSeatHost(
     repoRoot?: string | undefined;
     userConfigDir?: string | undefined;
     format?: "yaml" | "json" | undefined;
+    dryRun?: boolean | undefined;
   } = {},
 ): { filePath: string; seatId: string; binding: RoleSeatBinding; scope: "global" | "local" } {
   const scope = options.scope ?? "local";
@@ -624,6 +635,7 @@ export function setRoleSeatHost(
     repoRoot: options.repoRoot,
     userConfigDir: options.userConfigDir,
     format: options.format,
+    dryRun: options.dryRun,
   });
 
   return { filePath: saved.filePath, seatId, binding, scope };

package/plugins/kxm/src/session-work.ts

@@ -398,6 +398,8 @@ export function loadSessionBrief(
     cost?: string;
     sessionToken?: string;
     ship?: SessionShipStatus;
+    /** false answers from disk and the hub without refreshing session-brief.json. */
+    writeCache?: boolean;
   } = {},
 ): SessionBrief {
   const paths = resolveKxmSnapshotPaths(cwd, env);
@@ -464,7 +466,7 @@ export function loadSessionBrief(
     );
   }
 
-  writeCachedSessionBrief(paths.stateDir, brief);
+  if (options.writeCache !== false) writeCachedSessionBrief(paths.stateDir, brief);
   return brief;
 }
 
@@ -479,6 +481,7 @@ export async function loadSessionBriefAsync(
     cost?: string;
     sessionToken?: string;
     ship?: SessionShipStatus;
+    writeCache?: boolean;
   } = {},
 ): Promise<SessionBrief> {
   const paths = resolveKxmSnapshotPaths(cwd, env);

package/plugins/kxm/src/skills.ts

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { parse } from "yaml";
 import { redactSecrets } from "./redact.ts";
 
@@ -190,17 +190,32 @@ export interface SkillLifecycleOptions {
    * evals. When unset, `optimization` evaluations are rejected. */
   allowOptimizationEvals?: boolean;
   now?: () => string;
+  /** Validate and record every change in `planned` without touching disk. */
+  dryRun?: boolean;
 }
 
 export class SkillLifecycle {
   private readonly root: string;
   private readonly now: () => string;
   private readonly allowOptimizationEvals: boolean;
+  private readonly dryRun: boolean;
+  /** What a `dryRun` lifecycle would have written or moved, in order. */
+  readonly planned: Array<{ action: "write" | "move"; target: string }> = [];
 
   constructor(root: string, options: SkillLifecycleOptions = {}) {
     this.root = root;
     this.now = options.now ?? (() => new Date().toISOString());
     this.allowOptimizationEvals = options.allowOptimizationEvals === true;
+    this.dryRun = options.dryRun === true;
+  }
+
+  private write(file: string, content: string): void {
+    if (this.dryRun) {
+      this.planned.push({ action: "write", target: file });
+      return;
+    }
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, content);
   }
 
   private dir(state: SkillState): string {
@@ -217,15 +232,14 @@ export class SkillLifecycle {
   }
 
   private appendHistory(id: string, record: unknown): void {
-    mkdirSync(join(this.root, "history"), { recursive: true });
     const line = `${JSON.stringify(record)}\n`;
     if (existsSync(this.historyFile(id))) {
       // Bound the history file: append within the audit limit.
       const existing = readFileSync(this.historyFile(id), "utf8");
       const lines = existing.split("\n").filter((entry) => entry.trim());
-      writeFileSync(this.historyFile(id), [...lines.slice(-499), line.trim()].join("\n") + "\n");
+      this.write(this.historyFile(id), [...lines.slice(-499), line.trim()].join("\n") + "\n");
     } else {
-      writeFileSync(this.historyFile(id), line);
+      this.write(this.historyFile(id), line);
     }
   }
 
@@ -252,6 +266,10 @@ export class SkillLifecycle {
     if (!existsSync(fromDir)) {
       throw new SkillLifecycleError("skill_not_found", `skill ${id} not found in ${from}`);
     }
+    if (this.dryRun) {
+      this.planned.push({ action: "move", target: `${fromDir} -> ${toDir}` });
+      return;
+    }
     mkdirSync(this.dir(to), { recursive: true });
     if (existsSync(toDir)) rmSync(toDir, { recursive: true, force: true });
     renameSync(fromDir, toDir);
@@ -299,7 +317,7 @@ export class SkillLifecycle {
 
     const contentSha256 = skillContentSha256(content);
     const id = skillIdFor(name, contentSha256);
-    const { dir, metadata, skill } = this.paths("candidate", id);
+    const { metadata, skill } = this.paths("candidate", id);
     if (existsSync(metadata)) {
       throw new SkillLifecycleError(
         "skill_candidate_exists",
@@ -319,9 +337,8 @@ export class SkillLifecycle {
       createdAt: this.now(),
       ...(input.supersedes ? { supersedes: input.supersedes } : {}),
     };
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(skill, content);
-    writeFileSync(metadata, `${JSON.stringify(record, null, 2)}\n`);
+    this.write(skill, content);
+    this.write(metadata, `${JSON.stringify(record, null, 2)}\n`);
     this.appendHistory(id, { schema: "kxm.skill-history-event.v1", event: "candidate_created", by: createdBy, supersedes: input.supersedes, at: record.createdAt });
     return record;
   }
@@ -429,20 +446,17 @@ export class SkillLifecycle {
     // Instead of moving directory, write promoted directory and generate patch
     const candidatePaths = this.paths("candidate", candidateId);
     const promotedPaths = this.paths("promoted", candidateId);
-    mkdirSync(promotedPaths.dir, { recursive: true });
 
     const skillContent = readFileSync(candidatePaths.skill, "utf8");
     const metadataContent = readFileSync(candidatePaths.metadata, "utf8");
-    writeFileSync(promotedPaths.skill, skillContent);
-    writeFileSync(promotedPaths.metadata, metadataContent);
+    this.write(promotedPaths.skill, skillContent);
+    this.write(promotedPaths.metadata, metadataContent);
 
-    const patchesDir = join(this.root, "patches");
-    mkdirSync(patchesDir, { recursive: true });
-    const patchPath = join(patchesDir, `${candidateId}.patch`);
+    const patchPath = join(this.root, "patches", `${candidateId}.patch`);
     const relSkillPath = `.kxm/skills/promoted/${candidateId}/SKILL.md`;
     const relMetaPath = `.kxm/skills/promoted/${candidateId}/metadata.json`;
     const patch = `${createUnifiedPatch(relSkillPath, skillContent)}${createUnifiedPatch(relMetaPath, metadataContent)}`;
-    writeFileSync(patchPath, patch, "utf8");
+    this.write(patchPath, patch);
 
     this.appendHistory(candidateId, record);
     return { ...metadata, patch, patchPath };

package/plugins/kxm/src/sqlite.ts

@@ -8,7 +8,10 @@
  * flag `readOnly`, Bun spells it `readonly`. Options are normalized here so
  * callers keep using the Node spelling everywhere.
  */
+import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 
 export interface DatabaseSyncOptions {
   readOnly?: boolean;
@@ -74,3 +77,18 @@ export class DatabaseSync {
     this.inner.close();
   }
 }
+
+/**
+ * Open a database for reading without touching its directory. A plain
+ * read-only open of a WAL database creates the `-wal` and `-shm` sidecars when
+ * they are missing and leaves them behind. With no `-wal` present, the main
+ * file already holds every committed page, so it is opened `immutable` (no
+ * locks, no sidecars); a present `-wal` means a writer or un-checkpointed
+ * frames, and the ordinary read-only open reads through them.
+ */
+export function openReadOnlyDatabase(path: string): DatabaseSync {
+  if (existsSync(`${path}-wal`)) return new DatabaseSync(path, { readOnly: true });
+  const uri = pathToFileURL(resolve(path));
+  uri.searchParams.set("immutable", "1");
+  return new DatabaseSync(uri.href, { readOnly: true });
+}

package/plugins/kxm/src/task-manager.ts

@@ -58,6 +58,14 @@ function tasksDirectory(repoRoot: string): string {
   return resolve(repoRoot, ".kxm", "tasks");
 }
 
+export function goalFilePath(repoRoot: string, goalId: string): string {
+  return join(goalsDirectory(repoRoot), `${goalId}.yaml`);
+}
+
+export function taskFilePath(repoRoot: string, taskId: string): string {
+  return join(tasksDirectory(repoRoot), `${taskId}.yaml`);
+}
+
 export function createGoal(
   repoRoot: string,
   input: {
@@ -66,9 +74,8 @@ export function createGoal(
     successMetrics?: string[] | undefined;
     targetDate?: string | undefined;
   },
+  options: { dryRun?: boolean | undefined } = {},
 ): GoalRecord {
-  const dir = goalsDirectory(repoRoot);
-  mkdirSync(dir, { recursive: true });
 
   const id = `goal_${randomUUID().replaceAll("-", "").slice(0, 12)}`;
   const now = new Date().toISOString();
@@ -84,8 +91,9 @@ export function createGoal(
     updatedAt: now,
   };
 
-  const filePath = join(dir, `${id}.yaml`);
-  writeFileSync(filePath, stringify(record).trim() + "\n", "utf8");
+  if (options.dryRun) return record;
+  mkdirSync(goalsDirectory(repoRoot), { recursive: true });
+  writeFileSync(goalFilePath(repoRoot, id), stringify(record).trim() + "\n", "utf8");
   return record;
 }
 
@@ -123,9 +131,8 @@ export function createTask(
       issueKey: string;
     } | undefined;
   },
+  options: { dryRun?: boolean | undefined } = {},
 ): TaskRecord {
-  const dir = tasksDirectory(repoRoot);
-  mkdirSync(dir, { recursive: true });
 
   const id = `task_${randomUUID().replaceAll("-", "").slice(0, 12)}`;
   const now = new Date().toISOString();
@@ -151,8 +158,9 @@ export function createTask(
     updatedAt: now,
   };
 
-  const filePath = join(dir, `${id}.yaml`);
-  writeFileSync(filePath, stringify(record).trim() + "\n", "utf8");
+  if (options.dryRun) return record;
+  mkdirSync(tasksDirectory(repoRoot), { recursive: true });
+  writeFileSync(taskFilePath(repoRoot, id), stringify(record).trim() + "\n", "utf8");
   return record;
 }
 
@@ -201,7 +209,7 @@ export function updateTaskStatus(
   repoRoot: string,
   taskId: string,
   status: TaskStatus,
-  options: { workflowRunId?: string } = {},
+  options: { workflowRunId?: string; dryRun?: boolean | undefined } = {},
 ): TaskRecord {
   const task = getTask(repoRoot, taskId);
   if (!task) {
@@ -212,8 +220,7 @@ export function updateTaskStatus(
   if (options.workflowRunId) task.workflowRunId = options.workflowRunId;
   task.updatedAt = new Date().toISOString();
 
-  const filePath = join(tasksDirectory(repoRoot), `${taskId}.yaml`);
-  writeFileSync(filePath, stringify(task).trim() + "\n", "utf8");
+  if (!options.dryRun) writeFileSync(taskFilePath(repoRoot, taskId), stringify(task).trim() + "\n", "utf8");
   return task;
 }
 
@@ -223,6 +230,7 @@ export function syncTaskWithTracker(
   options: {
     mockRemoteState?: string;
     commentReceipt?: string;
+    dryRun?: boolean | undefined;
   } = {},
 ): TaskRecord {
   const task = getTask(repoRoot, taskId);
@@ -238,7 +246,6 @@ export function syncTaskWithTracker(
   task.trackerSync.lastSyncedAt = now;
   task.updatedAt = now;
 
-  const filePath = join(tasksDirectory(repoRoot), `${taskId}.yaml`);
-  writeFileSync(filePath, stringify(task).trim() + "\n", "utf8");
+  if (!options.dryRun) writeFileSync(taskFilePath(repoRoot, taskId), stringify(task).trim() + "\n", "utf8");
   return task;
 }

package/plugins/kxm/src/workflow-manager.ts

@@ -326,11 +326,14 @@ export function addWorkflowDefinition(
     repoRoot?: string | undefined;
     userConfigDir?: string | undefined;
     overwrite?: boolean | undefined;
+    dryRun?: boolean | undefined;
   } = {},
 ): { id: string; filePath: string; scope: "global" | "local" } {
   const scope = options.scope ?? "local";
   const repoRoot = options.repoRoot ?? process.cwd();
-  const dir = ensureWorkflowsDirectory(scope, repoRoot, options.userConfigDir);
+  const dir = options.dryRun
+    ? workflowsDirectory(scope, repoRoot, options.userConfigDir)
+    : ensureWorkflowsDirectory(scope, repoRoot, options.userConfigDir);
   const filePath = join(dir, `${workflowId}.yaml`);
 
   if (existsSync(filePath) && !options.overwrite) {
@@ -338,7 +341,7 @@ export function addWorkflowDefinition(
   }
 
   const payload = typeof content === "string" ? content : stringify(content);
-  writeFileSync(filePath, payload, "utf8");
+  if (!options.dryRun) writeFileSync(filePath, payload, "utf8");
   return { id: workflowId, filePath, scope };
 }
 
@@ -348,6 +351,7 @@ export function removeWorkflowDefinition(
     scope?: "global" | "local" | undefined;
     repoRoot?: string | undefined;
     userConfigDir?: string | undefined;
+    dryRun?: boolean | undefined;
   } = {},
 ): { id: string; removed: boolean; filePath: string; scope: "global" | "local" } {
   const scope = options.scope ?? "local";
@@ -359,6 +363,7 @@ export function removeWorkflowDefinition(
     throw new Error(`workflow_not_found: workflow '${workflowId}' not found in ${scope} directory (${filePath})`);
   }
 
+  if (options.dryRun) return { id: workflowId, removed: false, filePath, scope };
   rmSync(filePath);
   return { id: workflowId, removed: true, filePath, scope };
 }
@@ -370,6 +375,7 @@ export function modifyWorkflowDefinition(
     scope?: "global" | "local" | undefined;
     repoRoot?: string | undefined;
     userConfigDir?: string | undefined;
+    dryRun?: boolean | undefined;
   } = {},
 ): { id: string; workflow: Record<string, unknown>; filePath: string; scope: "global" | "local" } {
   const target = getWorkflowDefinition(workflowId, { scope: options.scope, repoRoot: options.repoRoot, userConfigDir: options.userConfigDir });
@@ -384,9 +390,11 @@ export function modifyWorkflowDefinition(
 
   const scope = options.scope ?? target.scope;
   const repoRoot = options.repoRoot ?? process.cwd();
-  const dir = ensureWorkflowsDirectory(scope, repoRoot, options.userConfigDir);
+  const dir = options.dryRun
+    ? workflowsDirectory(scope, repoRoot, options.userConfigDir)
+    : ensureWorkflowsDirectory(scope, repoRoot, options.userConfigDir);
   const filePath = join(dir, `${workflowId}.yaml`);
 
-  writeFileSync(filePath, stringify(updated), "utf8");
+  if (!options.dryRun) writeFileSync(filePath, stringify(updated), "utf8");
   return { id: workflowId, workflow: updated, filePath, scope };
 }