@geraldmaron/construct 1.0.0 → 1.0.2

package/rules/policy/bootstrap.yaml

@@ -0,0 +1,11 @@
+# bootstrap policy
+# Controls session bootstrap enforcement (write/bash gating until session grounded).
+
+rule: bootstrap
+hook_event: PreToolUse
+blocked_tools: [Write, Edit, MultiEdit, NotebookEdit, TodoWrite, Bash]
+bootstrap_trio: [workflow_status, project_context, memory_search]
+read_threshold: 3
+benign_bash_pattern: "^(git (status|log|diff|branch|show|rev-parse)|ls|cat|head|tail|pwd|wc|file|echo|which|node --version|npm --version)\\b"
+action: block
+message: "Requires session bootstrap. Run workflow_status + project_context + memory_search first (or 3+ read calls)."

package/rules/policy/drive.yaml

@@ -0,0 +1,8 @@
+# drive policy
+# Controls stop-blocking when drive mode is active and acceptance criteria are unmet.
+
+rule: drive
+hook_event: Stop
+condition: drive_state.active == true AND drive_state.canStop != true
+action: block
+message: "Drive mode active — unmet criteria remain. Record evidence in .cx/drive-state.json to unblock."

package/rules/policy/task.yaml

@@ -0,0 +1,9 @@
+# task-complete policy
+# Blocks marking a workflow task as done without verification evidence.
+
+rule: task-complete
+hook_event: PreToolUse
+trigger_tools: [mcp__construct-mcp__workflow_update_task]
+condition: task.verification is empty OR task.acceptanceCriteria is empty
+action: block
+message: "Task completion requires owner, acceptance criteria, and verification evidence in .cx/workflow.json."

package/rules/policy/workflow.yaml

@@ -0,0 +1,9 @@
+# workflow policy
+# Controls UserPromptSubmit routing — ensures significant work flows through workflow state.
+
+rule: workflow
+hook_event: UserPromptSubmit
+condition: workflow.status == "in-progress" AND (open_tasks.length > 0 OR high_severity_findings.length > 0)
+bypass_patterns: ["\\b(stop|pause|halt|enough|abort|cancel)\\b"]
+action: block
+message: "Workflow is active. Continue the current task, update .cx/workflow.json, or say stop/pause to end."

package/rules/python/hooks.md

@@ -10,12 +10,8 @@ paths:
 ---
 # Python Hooks
 
-> This file extends [common/hooks.md](../common/hooks.md) with Python specific content.
-
 ## PostToolUse Hooks
 
-Configure in `~/.claude/settings.json`:
-
 - **black/ruff**: Auto-format `.py` files after edit
 - **mypy/pyright**: Run type checking after editing `.py` files
 

package/rules/swift/hooks.md

@@ -10,12 +10,8 @@ paths:
 ---
 # Swift Hooks
 
-> This file extends [common/hooks.md](../common/hooks.md) with Swift specific content.
-
 ## PostToolUse Hooks
 
-Configure in `~/.claude/settings.json`:
-
 - **SwiftFormat**: Auto-format `.swift` files after edit
 - **SwiftLint**: Run lint checks after editing `.swift` files
 - **swift build**: Type-check modified packages after edit

package/rules/typescript/hooks.md

@@ -12,12 +12,8 @@ paths:
 ---
 # TypeScript/JavaScript Hooks
 
-> This file extends [common/hooks.md](../common/hooks.md) with TypeScript/JavaScript specific content.
-
 ## PostToolUse Hooks
 
-Configure in `~/.claude/settings.json`:
-
 - **Prettier**: Auto-format JS/TS files after edit
 - **TypeScript check**: Run `tsc` after editing `.ts`/`.tsx` files
 - **console.log warning**: Warn about `console.log` in edited files

package/rules/web/hooks.md

@@ -3,8 +3,6 @@ rules/web/hooks.md — <one-line purpose>
 
 <2–6 line summary.>
 -->
-> This file extends [common/hooks.md](../common/hooks.md) with web-specific hook recommendations.
-
 # Web Hooks
 
 ## Recommended PostToolUse Hooks

package/{sync-agents.mjs → scripts/sync-agents.mjs}

@@ -4,12 +4,20 @@
  *
  * Reads registry.json, resolves env vars and model tiers, then writes Claude Code,
  * OpenCode, Codex, Copilot, VS Code, and Cursor adapters. Called by 'construct sync'.
- * Protected file — read the CLAUDE.md constraints before editing.
+ *
+ * Flags:
+ *   --dry-run             Print a diff of what would change without writing anything.
+ *   --force               Bypass prompt word-cap hard stop (still warns).
+ *   --project             Write to the current project's .claude/ directory only.
+ *   --compress-personas   Run the engine's Compressor on every persona prompt
+ *                         before writing platform adapters. The source persona
+ *                         file is unchanged; only the runtime adapter is shorter.
+ *                         Lossy by definition — opt-in only.
  */
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
-import { generateCompletions } from "./lib/completions.mjs";
+import { generateCompletions } from "../lib/completions.mjs";
 import {
   buildCodexMcpEntry,
   getCodexConfigPath,
@@ -20,25 +28,27 @@ import {
   serializeCodexMcpTable,
   tomlString,
   writeCodexConfig,
-} from "./lib/codex-config.mjs";
-import { findOpenCodeConfigPath, readOpenCodeConfig, writeOpenCodeConfig } from "./lib/opencode-config.mjs";
-import { resolvePromptContract } from "./lib/prompt-composer.mjs";
+} from "../lib/codex-config.mjs";
+import { findOpenCodeConfigPath, readOpenCodeConfig, writeOpenCodeConfig } from "../lib/opencode-config.mjs";
+import { resolvePromptContract } from "../lib/prompt-composer.js";
 import {
   buildClaudeMcpEntry,
   buildOpenCodeMcpEntry,
   getOpenCodeMcpId,
-} from "./lib/mcp-platform-config.mjs";
-import { loadConstructEnv } from "./lib/env-config.mjs";
-import { inlineRoleAntiPatterns, PROMPT_WORD_CAP } from "./lib/role-preload.mjs";
-import { resolveTiersForPrimary } from "./lib/model-router.mjs";
+} from "../lib/mcp-platform-config.mjs";
+import { loadConstructEnv } from "../lib/env-config.mjs";
+import { inlineRoleAntiPatterns, PROMPT_WORD_CAP } from "../lib/role-preload.mjs";
+import { resolveTiersForPrimary } from "../lib/model-router.mjs";
+import { stampFrontmatter } from "../lib/doc-stamp.mjs";
 
 const home = os.homedir();
-const root = path.resolve(import.meta.dirname);
+const root = path.resolve(import.meta.dirname, "..");
 
 const mergedEnv = loadConstructEnv({ rootDir: root, homeDir: home, env: process.env });
 for (const [key, value] of Object.entries(mergedEnv)) {
   if (!(key in process.env)) process.env[key] = value;
 }
+if (!process.env.CX_TOOLKIT_DIR) process.env.CX_TOOLKIT_DIR = root;
 const registryPath = path.join(root, "agents", "registry.json");
 const registry = JSON.parse(fs.readFileSync(registryPath, "utf8"));
 
@@ -94,8 +104,8 @@ function validateRegistry(registry) {
         errors.push(`models.${tier}: missing tier object`);
         continue;
       }
-      if (!t.primary || typeof t.primary !== "string") {
-        errors.push(`models.${tier}: primary model must be a non-empty string`);
+      if (t.primary !== null && (typeof t.primary !== "string" || !t.primary)) {
+        errors.push(`models.${tier}: primary must be null or a non-empty string`);
       }
     }
   }
@@ -110,6 +120,95 @@ if (validationErrors.length > 0) {
   process.exit(1);
 }
 
+// --- Dry-run + lockfile + two-phase write infrastructure ---
+
+const DRY_RUN = process.argv.includes("--dry-run");
+const COMPRESS_PERSONAS = process.argv.includes("--compress-personas");
+const lockPath = path.join(root, ".cx", "sync.lock");
+const stagingDir = path.join(root, ".cx", "sync-staging");
+
+/** Acquire an exclusive lockfile. Aborts if already held by a live process. */
+function acquireLock() {
+  if (DRY_RUN) return;
+  try {
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    fs.writeFileSync(lockPath, String(process.pid), { flag: "wx" });
+  } catch (err) {
+    if (err.code === "EEXIST") {
+      const holder = fs.readFileSync(lockPath, "utf8").trim();
+      // Check whether the holding process is still alive
+      let holderAlive = false;
+      try { process.kill(Number(holder), 0); holderAlive = true; } catch { /* dead */ }
+      if (holderAlive) {
+        console.error(`[sync] Another sync is already running (pid ${holder}). Aborting.`);
+        console.error(`[sync] If this is stale, remove .cx/sync.lock and retry.`);
+        process.exit(1);
+      }
+      // Stale lock — steal it
+      fs.writeFileSync(lockPath, String(process.pid), { flag: "w" });
+      return;
+    }
+    throw err;
+  }
+}
+
+/** Release the lockfile. Called in a finally block. */
+function releaseLock() {
+  if (DRY_RUN) return;
+  try { fs.unlinkSync(lockPath); } catch { /* already gone */ }
+}
+
+/**
+ * Staging-aware write. In dry-run mode, writes to the staging dir instead of the
+ * real destination and records the path pair for diff output. In normal mode,
+ * writes to staging first, then the real path is swapped in by commitStaging().
+ */
+const _stagedPairs = []; // [{ staging, real, content }]
+
+function writeFile(file, content) {
+  mkdirp(path.dirname(file));
+  const stamped = file.endsWith('.md') ? stampFrontmatter(content, { generator: 'construct/sync-agents' }) : content;
+
+  if (DRY_RUN) {
+    // Stage in memory only — compare against current on-disk content.
+    let current = "";
+    try { current = fs.readFileSync(file, "utf8"); } catch { /* new file */ }
+    if (current !== stamped) _stagedPairs.push({ real: file, staging: null, content: stamped, current });
+    return;
+  }
+
+  // Two-phase: write to staging, commit later.
+  const rel = path.relative(root, file);
+  const stagingPath = path.join(stagingDir, rel);
+  mkdirp(path.dirname(stagingPath));
+  fs.writeFileSync(stagingPath, stamped);
+  _stagedPairs.push({ real: file, staging: stagingPath, content: stamped });
+}
+
+/** Atomically rename all staged files into their real destinations. */
+function commitStaging() {
+  for (const { real, staging } of _stagedPairs) {
+    if (!staging) continue;
+    mkdirp(path.dirname(real));
+    fs.renameSync(staging, real);
+  }
+  // Clean up staging dir.
+  try { fs.rmSync(stagingDir, { recursive: true, force: true }); } catch { /* ok */ }
+}
+
+/** Print a human-readable diff summary for --dry-run mode. */
+function printDryRunDiff() {
+  if (_stagedPairs.length === 0) {
+    console.log("[sync --dry-run] No changes — all outputs are already up to date.");
+    return;
+  }
+  console.log(`[sync --dry-run] ${_stagedPairs.length} file(s) would change:\n`);
+  for (const { real } of _stagedPairs) {
+    console.log(`  ~ ${path.relative(root, real)}`);
+  }
+  console.log("\nRe-run without --dry-run to apply.");
+}
+
 const systemName = registry.system;
 const agentPrefix = `${registry.prefix}-`;
 const sharedGuidance = registry.sharedGuidance ?? [];
@@ -248,7 +347,6 @@ function resolveModelChain(entry) {
 }
 
 function mkdirp(dir) { fs.mkdirSync(dir, { recursive: true }); }
-function writeFile(file, content) { mkdirp(path.dirname(file)); fs.writeFileSync(file, content); }
 
 function adapterName(entry) {
   return entry.isPersona ? entry.name : `${agentPrefix}${entry.name}`;
@@ -269,8 +367,8 @@ function loadPersonaPrompt(persona) {
   return prompt;
 }
 
-function buildAgentRoster(allEntries) {
-  return allEntries.map((e) => `- ${adapterName(e)}: ${e.description}`).join("\n");
+export function buildAgentRoster(allEntries) {
+  return allEntries.map((e) => `- ${adapterName(e)}: ${e.when_to_use || e.description}`).join("\n");
 }
 
 function buildModelGuidanceBlock(entry) {
@@ -304,7 +402,7 @@ function buildPrompt(entry, allEntries, platform) {
     fallback: entry.prompt || '',
   }).prompt;
 
-  prompt = inlineRoleAntiPatterns(prompt, root, entry.name);
+  prompt = inlineRoleAntiPatterns(prompt, root, entry.name, console.warn, { preload: entry.preloadRoleGuidance === true });
 
   if (entry.injectAgentRoster && allEntries) {
     const roster = buildAgentRoster(allEntries);
@@ -325,7 +423,20 @@ function buildPrompt(entry, allEntries, platform) {
   const wordCount = prompt.split(/\s+/).filter(Boolean).length;
   const effectiveCap = Number(entry.wordCapOverride) > 0 ? entry.wordCapOverride : PROMPT_WORD_CAP;
   if (wordCount > effectiveCap) {
-    console.warn(`[sync] ${entry.name}: prompt is ${wordCount} words (cap ${effectiveCap})`);
+    const msg = `[sync] ${entry.name}: prompt is ${wordCount} words (cap ${effectiveCap})`;
+    if (process.env.CONSTRUCT_SYNC_FORCE === '1' || process.argv.includes('--force')) {
+      console.warn(`${msg} — proceeding due to --force / CONSTRUCT_SYNC_FORCE=1.`);
+    } else {
+      console.error(`${msg}`);
+      console.error(
+        `[sync] Hard cap exceeded. Options:\n` +
+        `   - trim the prompt body or move detail to a skill (preferred)\n` +
+        `   - set "wordCapOverride": <N> on this entry in agents/registry.json with a written reason\n` +
+        `   - re-run with --force or CONSTRUCT_SYNC_FORCE=1 as a temporary escape hatch\n` +
+        `Prompt budget is a hard contract because every over-cap agent degrades every session that dispatches it.`,
+      );
+      process.exit(1);
+    }
   }
 
   return prompt;
@@ -349,6 +460,7 @@ function readManifest(dir) {
 }
 
 function writeManifest(dir, files) {
+  if (DRY_RUN) return;
   fs.writeFileSync(path.join(dir, MANIFEST_FILE), [...files].sort().join("\n") + "\n");
 }
 
@@ -360,7 +472,7 @@ function removeStaleAdapters(dir, ext, entries) {
     expected.add(`${adapterName(e)}${ext}`);
   }
 
-  // Read what construct wrote last time — delete anything no longer expected
+  // Stale manifest entries — delete files not in the current expected set.
   const previouslyWritten = readManifest(dir);
   for (const file of previouslyWritten) {
     if (!expected.has(file) && fs.existsSync(path.join(dir, file))) {
@@ -421,11 +533,84 @@ ${buildPrompt(entry, allEntries, "claude")}
 `;
 }
 
+/**
+ * Rewrite the home-mode hook command pattern
+ *   node "$HOME/.construct/lib/hooks/<name>.mjs"
+ * into the project-portable form
+ *   node .construct/run.mjs hook <name>
+ * so the resulting settings.json works on any clone where the project ships
+ * the .construct/ launcher (committed by `npm install`'s postinstall or by
+ * `construct init`). The launcher resolves Construct via node_modules → npx
+ * → globally-installed CLI → cached binary → docker, in that order, so it
+ * works for non-Node ecosystems too. Other commands (inline node -e
+ * snippets, npx block-no-verify@…) are left untouched.
+ */
+function makeHooksPortable(hooksJson) {
+  // Operate on the in-memory object so we don't fight JSON string escaping.
+  const replaceCommand = (cmd) => {
+    if (typeof cmd !== 'string') return cmd;
+    const m = cmd.match(/^node\s+"?\$HOME\/\.construct\/lib\/hooks\/([a-z0-9-]+)\.mjs"?\s*(.*)$/);
+    if (!m) return cmd;
+    const [, name, rest] = m;
+    return `node .construct/run.mjs hook ${name}${rest ? ' ' + rest.trim() : ''}`;
+  };
+
+  const walk = (node) => {
+    if (Array.isArray(node)) return node.map(walk);
+    if (node && typeof node === 'object') {
+      const out = {};
+      for (const [k, v] of Object.entries(node)) {
+        out[k] = k === 'command' ? replaceCommand(v) : walk(v);
+      }
+      return out;
+    }
+    return node;
+  };
+
+  return JSON.stringify(walk(hooksJson));
+}
+
+/**
+ * Materialise a project-local `.claude/settings.json` from the home template,
+ * with hook commands rewritten to be path-relative to whatever Construct
+ * install the project carries. Merges into an existing settings.json
+ * if one is already in the project; otherwise creates a fresh one.
+ */
+function writeProjectClaudeSettings(targetDir) {
+  const settingsPath = path.join(targetDir, ".claude", "settings.json");
+  const templatePath = path.join(root, "platforms", "claude", "settings.template.json");
+  if (!fs.existsSync(templatePath)) return;
+
+  const template = JSON.parse(fs.readFileSync(templatePath, "utf8"));
+
+  const existing = fs.existsSync(settingsPath)
+    ? JSON.parse(fs.readFileSync(settingsPath, "utf8"))
+    : {};
+
+  if (template.hooks) {
+    existing.hooks = JSON.parse(makeHooksPortable(template.hooks));
+  }
+  if (template.permissions) {
+    existing.permissions ??= template.permissions;
+  }
+  if (template.mcpServers) {
+    existing.mcpServers ??= {};
+    for (const [id, mcpDef] of Object.entries(template.mcpServers)) {
+      if (existing.mcpServers[id]) continue;
+      existing.mcpServers[id] = mcpDef;
+    }
+  }
+
+  if (DRY_RUN) return;
+  mkdirp(path.dirname(settingsPath));
+  writeFile(settingsPath, JSON.stringify(existing, null, 2) + "\n");
+}
+
 function syncClaude(entries, targetDir = null) {
   const claudeAgentsDir = targetDir
     ? path.join(targetDir, ".claude", "agents")
     : path.join(home, ".claude", "agents");
-  mkdirp(claudeAgentsDir);
+  if (!DRY_RUN) mkdirp(claudeAgentsDir);
 
   for (const entry of entries) {
     const name = adapterName(entry);
@@ -434,6 +619,11 @@ function syncClaude(entries, targetDir = null) {
   }
   removeStaleAdapters(claudeAgentsDir, ".md", entries);
 
+  if (targetDir) {
+    writeProjectClaudeSettings(targetDir);
+    return;
+  }
+
   if (!targetDir) {
     const claudeMdPath = path.join(home, ".claude", "CLAUDE.md");
     const existing = fs.existsSync(claudeMdPath) ? fs.readFileSync(claudeMdPath, "utf8") : "# Claude Global Instructions\n";
@@ -475,7 +665,7 @@ ${agentList || "(all specialists are internal — routed through Construct)"}`;
         if (settings.mcpServers[id] && !hasPlaceholder) continue;
         settings.mcpServers[id] = buildClaudeMcpEntry(id, mcpDef, process.env);
       }
-      fs.writeFileSync(claudeSettingsPath, JSON.stringify(settings, null, 2) + "\n");
+      if (!DRY_RUN) fs.writeFileSync(claudeSettingsPath, JSON.stringify(settings, null, 2) + "\n");
     }
   }
 }
@@ -510,10 +700,14 @@ function hasCodexMcpTable(text, id) {
   return new RegExp(`^\\[mcp_servers\\.(?:${escapeRegExp(id)}|${escapeRegExp(tomlString(id))})\\]`, "m").test(text);
 }
 
+function isCodexMcpSupported(id) {
+  return id !== "memory";
+}
+
 function syncCodex(entries) {
   const codexDir = path.join(home, ".codex");
   const codexAgentsDir = path.join(codexDir, "agents");
-  mkdirp(codexAgentsDir);
+  if (!DRY_RUN) mkdirp(codexAgentsDir);
 
   for (const entry of entries) {
     writeFile(path.join(codexAgentsDir, `${adapterName(entry)}.toml`), codexAgentToml(entry, entries));
@@ -524,10 +718,11 @@ function syncCodex(entries) {
   const existing = removeDanglingConstructMcpMarkers(removeDanglingConstructMcpTimeouts(readCodexConfig(configPath)));
   const entryNames = entries.map(adapterName);
   const registryMcp = registry.mcpServers ?? {};
-  const mcpIds = Object.keys(registryMcp).filter((id) => hasCodexMcpTable(existing, id));
+  const existingMcpIds = Object.keys(registryMcp).filter((id) => hasCodexMcpTable(existing, id));
+  const mcpIds = existingMcpIds.filter(isCodexMcpSupported);
   const withoutManagedTables = removeDanglingConstructMcpMarkers(removeTomlTables(
     removeCodexAgentTables(existing, entryNames),
-    mcpIds.flatMap((id) => [`mcp_servers.${id}`, `mcp_servers.${tomlString(id)}`]),
+    existingMcpIds.flatMap((id) => [`mcp_servers.${id}`, `mcp_servers.${tomlString(id)}`]),
   ));
   const hasAgentsRoot = /^\[agents\]\s*$/m.test(withoutManagedTables);
   const rootBlock = hasAgentsRoot ? "" : "[agents]\nmax_threads = 6\nmax_depth = 1\n\n";
@@ -570,7 +765,7 @@ When using this prompt, stay within the role above and adapt to the current repo
 
 function syncCopilot(entries) {
   const promptsDir = path.join(home, ".github", "prompts");
-  mkdirp(promptsDir);
+  if (!DRY_RUN) mkdirp(promptsDir);
   for (const entry of entries) {
     writeFile(path.join(promptsDir, `${adapterName(entry)}.prompt.md`), copilotPrompt(entry, entries));
   }
@@ -634,7 +829,7 @@ function syncVSCode() {
         mcpServers[id] = buildClaudeMcpEntry(id, mcpDef, process.env);
       }
       settings["github.copilot.mcpServers"] = mcpServers;
-      fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+      if (!DRY_RUN) fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
       synced = true;
     } catch {
       // Skip unreadable settings files
@@ -661,7 +856,7 @@ function syncCursor() {
       if (config.mcpServers[id] && !hasPlaceholder) continue;
       config.mcpServers[id] = buildClaudeMcpEntry(id, mcpDef, process.env);
     }
-    fs.writeFileSync(cursorMcpPath, JSON.stringify(config, null, 2) + "\n");
+    if (!DRY_RUN) fs.writeFileSync(cursorMcpPath, JSON.stringify(config, null, 2) + "\n");
     return true;
   } catch {
     return false;
@@ -757,6 +952,10 @@ function syncOpencode(entries) {
     for (const [id, mcpDef] of Object.entries(registryMcp)) {
       const openCodeId = getOpenCodeMcpId(id);
       if (openCodeId !== id) delete config.mcp[id];
+      if (id === 'memory' && config.mcp.cass && !config.mcp[openCodeId]) {
+        config.mcp[openCodeId] = config.mcp.cass;
+      }
+      if (id === 'memory') delete config.mcp.cass;
       const existing = JSON.stringify(config.mcp[openCodeId] ?? "");
       const hasPlaceholder = existing.includes("__") && existing.includes("__");
       const argsHaveTemplates = (mcpDef.args ?? []).some((a) => typeof a === 'string' && a.includes('__'));
@@ -796,7 +995,7 @@ function syncOpencode(entries) {
   writeOpenCodeConfig(config, configPath);
 
   const sourcePluginsDir = path.join(root, "platforms", "opencode", "plugins");
-  if (fs.existsSync(sourcePluginsDir)) {
+  if (fs.existsSync(sourcePluginsDir) && !DRY_RUN) {
     mkdirp(pluginsDir);
     for (const file of fs.readdirSync(sourcePluginsDir)) {
       if (!file.endsWith(".js") && !file.endsWith(".ts")) continue;
@@ -808,7 +1007,7 @@ function syncOpencode(entries) {
   }
 
   config.plugin = [...config.plugin, managedPluginPath];
-  writeOpenCodeConfig(config, configPath);
+  if (!DRY_RUN) writeOpenCodeConfig(config, configPath);
 
   return true;
 }
@@ -828,19 +1027,20 @@ function syncCommands(targetDir = null) {
     if (!domain.isDirectory()) continue;
     const domainDir = path.join(sourceCommandsDir, domain.name);
     const targetDomainDir = path.join(claudeCommandsDir, domain.name);
-    mkdirp(targetDomainDir);
+    if (!DRY_RUN) mkdirp(targetDomainDir);
 
     for (const file of fs.readdirSync(domainDir)) {
       if (!file.endsWith(".md")) continue;
+      count++;
+      if (DRY_RUN) continue;
       const source = path.join(domainDir, file);
       const target = path.join(targetDomainDir, file);
       fs.copyFileSync(source, target);
-      count++;
     }
   }
 
   // Clean up stale command files not in source
-  if (fs.existsSync(claudeCommandsDir)) {
+  if (!DRY_RUN && fs.existsSync(claudeCommandsDir)) {
     for (const domain of fs.readdirSync(claudeCommandsDir, { withFileTypes: true })) {
       if (!domain.isDirectory()) continue;
       const sourceDomainDir = path.join(sourceCommandsDir, domain.name);
@@ -865,35 +1065,80 @@ function syncCommands(targetDir = null) {
 const projectDir = process.argv.includes("--project") ? process.cwd() : null;
 const entries = buildEntries();
 
-if (projectDir) {
-  syncClaude(entries, projectDir);
-  const cmdCount = syncCommands(projectDir);
-  console.log(`Synced ${entries.length} agents + ${cmdCount} commands to ${path.join(projectDir, ".claude/")} (project mode).`);
-} else {
-  const personaCount = entries.filter((e) => e.isPersona).length;
-  const agentCount = entries.filter((e) => !e.isPersona).length;
-
-  syncCodex(entries);
-  syncClaude(entries);
-  syncCopilot(entries);
-  const opencodeOk = syncOpencode(entries);
-  const vscodeOk = syncVSCode();
-  const cursorOk = syncCursor();
-  const cmdCount = syncCommands();
-
-  const targets = [
-    "Codex",
-    "Claude Code",
-    "Copilot",
-    opencodeOk && "OpenCode",
-    vscodeOk && "VS Code",
-    cursorOk && "Cursor",
-  ].filter(Boolean).join(", ");
-  console.log(`Synced ${personaCount} personas + ${agentCount} specialists + ${cmdCount} commands to ${targets}.`);
-
-  // Regenerate shell completions so new commands are immediately tab-completable
-  const completionsDir = generateCompletions();
-  if (completionsDir) {
-    console.log(`Completions updated → ${completionsDir}`);
+if (COMPRESS_PERSONAS) {
+  // Run the engine's Compressor on every persona prompt so the runtime
+  // adapter file is shorter than the source persona on disk. The source
+  // file stays unchanged so authors keep editing the readable version.
+  const { getEngine } = await import('./lib/engine/index.mjs');
+  const engine = await getEngine({ rootDir: root });
+  const compressor = engine.layers.compressor;
+  let totalIn = 0;
+  let totalOut = 0;
+  for (const entry of entries) {
+    if (!entry.isPersona || !entry.prompt) continue;
+    const before = entry.prompt;
+    try {
+      const after = await compressor.compress(before, { ratio: 0.6 });
+      if (typeof after === 'string' && after.length > 0) {
+        entry.prompt = after;
+        totalIn += before.length;
+        totalOut += after.length;
+      }
+    } catch (err) {
+      console.warn(`compress-personas: skipping ${entry.name}: ${err.message}`);
+    }
+  }
+  if (totalIn > 0) {
+    const ratio = ((totalOut / totalIn) * 100).toFixed(0);
+    console.log(`compress-personas: ${totalIn} → ${totalOut} chars (${ratio}%) across ${entries.filter((e) => e.isPersona).length} personas`);
+  }
+}
+
+acquireLock();
+try {
+  if (projectDir) {
+    syncClaude(entries, projectDir);
+    const cmdCount = syncCommands(projectDir);
+    if (DRY_RUN) {
+      printDryRunDiff();
+    } else {
+      commitStaging();
+      console.log(`Synced ${entries.length} agents + ${cmdCount} commands to ${path.join(projectDir, ".claude/")} (project mode).`);
+    }
+  } else {
+    const personaCount = entries.filter((e) => e.isPersona).length;
+    const agentCount = entries.filter((e) => !e.isPersona).length;
+
+    syncCodex(entries);
+    syncClaude(entries);
+    syncCopilot(entries);
+    const opencodeOk = syncOpencode(entries);
+    const vscodeOk = syncVSCode();
+    const cursorOk = syncCursor();
+    const cmdCount = syncCommands();
+
+    if (DRY_RUN) {
+      printDryRunDiff();
+    } else {
+      commitStaging();
+
+      const targets = [
+        "Codex",
+        "Claude Code",
+        "Copilot",
+        opencodeOk && "OpenCode",
+        vscodeOk && "VS Code",
+        cursorOk && "Cursor",
+      ].filter(Boolean).join(", ");
+      console.log(`Synced ${personaCount} personas + ${agentCount} specialists + ${cmdCount} commands to ${targets}.`);
+
+      // Regenerate shell completions so new commands are immediately tab-completable
+      const completionsDir = generateCompletions();
+      if (completionsDir) {
+        console.log(`Completions updated → ${completionsDir}`);
+      }
+    }
   }
+} finally {
+  releaseLock();
 }