@aiwg/cli 2026.10.5 → 2026.10.7

package/tools/agents/providers/codex.mjs

@@ -1,3 +1,4 @@
+import { importImpl } from '../../_resolve-impl.mjs';
 /**
  * OpenAI Codex Provider
  *
@@ -35,6 +36,7 @@ const staticModelCatalog = _require('../../../agentic/code/providers/model-catal
 import path from 'path';
 import os from 'os';
 import { spawn } from 'child_process';
+import { pathToFileURL } from 'node:url';
 import { load as loadYaml } from 'js-yaml';
 import { classifyModelRole, modelForRole } from './model-role.mjs';
 import {
@@ -66,7 +68,8 @@ import {
   parseFrontmatter,
   resolveAiwgRoot
 } from './base.mjs';
-const modelCatalog = loadRuntimeModelCatalog(staticModelCatalog);
+
+import { writeContextFileSync } from './context-write.mjs';
 
 function resolveCodexHelperRoot(srcRoot) {
   const resolved = resolveAiwgRoot(srcRoot);
@@ -101,7 +104,6 @@ export const kernelSkillsPath = '.agents/skills/';
 // Legacy home-dir skills location written by AIWG versions prior to the #766
 // regression fix. Pruned on every codex skill deploy so codex-rs stops listing
 // each AIWG skill twice. Never touches non-AIWG (unmarked) skills.
-const legacyHomeSkillsDir = path.join(os.homedir(), '.codex', 'skills');
 
 export const support = {
   agents: 'native',
@@ -125,6 +127,7 @@ export const capabilities = {
  * Map model shorthand to OpenAI/GPT format
  */
 export function mapModel(originalModel, modelCfg, modelsConfig) {
+  const modelCatalog = modelCfg.modelCatalog || loadRuntimeModelCatalog(staticModelCatalog);
   const gptModels = {
     'opus': modelCatalog.providers.codex.roles.reasoning.id,
     'sonnet': modelCatalog.providers.codex.roles.coding.id,
@@ -204,7 +207,7 @@ export function renderAgentToml(srcPath, content, models) {
  */
 export function transformAgent(srcPath, content, opts) {
   const { reasoningModel, codingModel, efficiencyModel } = opts;
-  const catalogModels = modelCatalog.providers.codex.roles;
+  const catalogModels = (opts.modelCatalog || loadRuntimeModelCatalog(staticModelCatalog)).providers.codex.roles;
 
   const models = {
     reasoning: reasoningModel || catalogModels.reasoning.id,
@@ -239,6 +242,27 @@ export function deployAgents(agentFiles, targetDir, opts) {
   }, transformAgent);
 }
 
+/** Run the helper in this pass; retain process isolation for troubleshooting. */
+async function runCodexDeployer(scriptPath, args, helperRoot, opts) {
+  if (process.env.AIWG_DEPLOY_SUBPROCESS !== '1') {
+    const deployer = await import(pathToFileURL(scriptPath).href);
+    await deployer.main(args, { homeDir: opts.deploymentHome || os.homedir() });
+    return;
+  }
+  await new Promise((resolve, reject) => {
+    const child = spawn('node', [scriptPath, ...args], {
+      stdio: 'inherit',
+      cwd: helperRoot,
+      env: opts.deploymentHome ? { ...process.env, HOME: opts.deploymentHome } : process.env,
+    });
+    child.on('close', code => {
+      if (code === 0) resolve();
+      else reject(new Error(`${path.basename(scriptPath)} exited with code ${code}`));
+    });
+    child.on('error', reject);
+  });
+}
+
 /**
  * Deploy commands via external script
  *
@@ -257,30 +281,16 @@ export async function deployCommands(targetDir, srcRoot, opts) {
 
   console.log('Delegating command deployment to deploy-prompts-codex.mjs (~/.codex/prompts/)...');
 
-  return new Promise((resolve, reject) => {
-    // NOTE: Do NOT pass --target - Codex prompts belong in ~/.codex/prompts/ (home)
-    const args = ['--source', srcRoot];
-    if (opts.dryRun) args.push('--dry-run');
-    if (opts.force) args.push('--force');
-    if (opts.mode) args.push('--mode', opts.mode);
-    if (opts.copyStandardSkills === true) args.push('--copy-all');
-    // A copy-all the deployer forced on the caller's behalf (project-local
-    // bundles) still honors the startup listing cap (#2561).
-    if (opts.listingBudget === true) args.push('--listing-budget');
-
-    const child = spawn('node', [scriptPath, ...args], {
-      stdio: 'inherit',
-      cwd: helperRoot,
-      env: opts.deploymentHome ? { ...process.env, HOME: opts.deploymentHome } : process.env
-    });
-
-    child.on('close', (code) => {
-      if (code === 0) resolve();
-      else reject(new Error(`deploy-prompts-codex.mjs exited with code ${code}`));
-    });
-
-    child.on('error', reject);
-  });
+  // NOTE: Do NOT pass --target - Codex prompts belong in ~/.codex/prompts/ (home)
+  const args = ['--source', srcRoot];
+  if (opts.dryRun) args.push('--dry-run');
+  if (opts.force) args.push('--force');
+  if (opts.mode) args.push('--mode', opts.mode);
+  if (opts.copyStandardSkills === true) args.push('--copy-all');
+  // A copy-all the deployer forced on the caller's behalf (project-local
+  // bundles) still honors the startup listing cap (#2561).
+  if (opts.listingBudget === true) args.push('--listing-budget');
+  await runCodexDeployer(scriptPath, args, helperRoot, opts);
 }
 
 /**
@@ -305,37 +315,23 @@ export async function deploySkills(targetDir, srcRoot, opts) {
   const crossAgentSkillsDir = path.join(targetDir, '.agents', 'skills');
   console.log(`Deploying skills to ${crossAgentSkillsDir} (.agents/skills — codex-scanned path)...`);
 
-  await new Promise((resolve, reject) => {
-    const args = ['--source', srcRoot, '--target', crossAgentSkillsDir];
-    // Overflow past Codex's startup listing cap lands here instead of being
-    // deployed over the cap (#2561); the index still reaches these skills.
-    args.push('--standard-target', path.join(targetDir, ...paths.skills.split('/').filter(Boolean)));
-    if (opts.dryRun) args.push('--dry-run');
-    if (opts.force) args.push('--force');
-    if (opts.mode) args.push('--mode', opts.mode);
-    if (opts.copyStandardSkills === true) args.push('--copy-all');
-    // A copy-all the deployer forced on the caller's behalf (project-local
-    // bundles) still honors the startup listing cap (#2561).
-    if (opts.listingBudget === true) args.push('--listing-budget');
-
-    const child = spawn('node', [scriptPath, ...args], {
-      stdio: 'inherit',
-      cwd: helperRoot,
-      env: opts.deploymentHome ? { ...process.env, HOME: opts.deploymentHome } : process.env
-    });
-
-    child.on('close', (code) => {
-      if (code === 0) resolve();
-      else reject(new Error(`deploy-skills-codex.mjs exited with code ${code}`));
-    });
-
-    child.on('error', reject);
-  });
+  const args = ['--source', srcRoot, '--target', crossAgentSkillsDir];
+  // Overflow past Codex's startup listing cap lands here instead of being
+  // deployed over the cap (#2561); the index still reaches these skills.
+  args.push('--standard-target', path.join(targetDir, ...paths.skills.split('/').filter(Boolean)));
+  if (opts.dryRun) args.push('--dry-run');
+  if (opts.force) args.push('--force');
+  if (opts.mode) args.push('--mode', opts.mode);
+  if (opts.copyStandardSkills === true) args.push('--copy-all');
+  // A copy-all the deployer forced on the caller's behalf (project-local
+  // bundles) still honors the startup listing cap (#2561).
+  if (opts.listingBudget === true) args.push('--listing-budget');
+  await runCodexDeployer(scriptPath, args, helperRoot, opts);
 
   // Self-heal: prune AIWG-managed skill dirs left behind in the legacy
   // ~/.codex/skills/ home location by pre-fix versions, so codex-rs stops
   // listing each skill twice.
-  pruneLegacyCodexSkills(opts, opts.legacyCodexSkills || legacyHomeSkillsDir);
+  pruneLegacyCodexSkills(opts, opts.legacyCodexSkills || path.join(os.homedir(), '.codex', 'skills'));
 }
 
 /**
@@ -346,7 +342,7 @@ export async function deploySkills(targetDir, srcRoot, opts) {
  * the `.aiwg-managed` marker are removed — user-authored skills are never
  * touched. The now-empty legacy dir is removed if AIWG owned everything in it.
  */
-export function pruneLegacyCodexSkills(opts = {}, legacyDir = legacyHomeSkillsDir) {
+export function pruneLegacyCodexSkills(opts = {}, legacyDir = path.join(os.homedir(), '.codex', 'skills')) {
   let entries;
   try {
     entries = fs.readdirSync(legacyDir, { withFileTypes: true });
@@ -401,6 +397,7 @@ export function deployRules(ruleFiles, targetDir, opts) {
  * Aggregate agents to single AGENTS.md file
  */
 export function aggregateToAgentsMd(agentFiles, destPath, opts) {
+  if (opts.contextFiles === false) return 0;
   const lines = ['# AIWG agent definitions', '', 'Read the selected definition before invoking an agent.', ''];
   for (const file of agentFiles) {
     const { metadata } = parseFrontmatter(fs.readFileSync(file, 'utf8'));
@@ -409,7 +406,7 @@ export function aggregateToAgentsMd(agentFiles, destPath, opts) {
   }
   const out = `${lines.join('\n')}\n`;
   if (opts.dryRun) console.log(`[dry-run] write ${destPath}`);
-  else fs.writeFileSync(destPath, out, 'utf8');
+  else writeContextFileSync(destPath, out, 'utf8');
 
 }
 
@@ -518,7 +515,7 @@ export async function postDeploy(targetDir, opts) {
   initializeFrameworkWorkspace(targetDir, opts.mode, opts.dryRun, opts.srcRoot);
 
   if (opts.createAgentsMd) {
-    createAgentsMd(targetDir, opts.srcRoot, opts.dryRun);
+    if (opts.contextFiles !== false) createAgentsMd(targetDir, opts.srcRoot, opts.dryRun);
   }
 }
 

package/tools/agents/providers/context-write.mjs

@@ -0,0 +1,28 @@
+/**
+ * Context-file writes for deployment providers (#3037).
+ *
+ * The journaled writer lives in compiled TypeScript. In source-resolution
+ * mode (AIWG_RESOLVE_IMPL_FROM=src without a TS loader) it cannot load, and
+ * read-only consumers of provider modules (for example the remotes topology
+ * block) must still import cleanly. Writes then fail closed with the original
+ * load error, so nothing ever writes context files without the safety layer.
+ */
+import { importImpl } from '../../_resolve-impl.mjs';
+
+// Mirrors CONTEXT_STAGE_ENV in src/smiths/context-pipeline/context-file-safety.ts.
+export const CONTEXT_STAGE_ENV = 'AIWG_CONTEXT_STAGE_LOG';
+
+let loadError = null;
+let writer = null;
+try {
+  writer = await importImpl(import.meta.url, 'smiths/context-pipeline/context-file-safety.js');
+} catch (error) {
+  loadError = error;
+}
+
+export function writeContextFileSync(file, content, encoding) {
+  if (!writer) {
+    throw new Error(`Context-file safety layer is unavailable; refusing to write ${file}`, { cause: loadError });
+  }
+  return writer.writeContextFileSync(file, content, encoding);
+}

package/tools/agents/providers/copilot.mjs

@@ -1,3 +1,4 @@
+import { importImpl } from '../../_resolve-impl.mjs';
 /**
  * GitHub Copilot Provider
  *
@@ -27,6 +28,7 @@ let fs;
 try { const gfs = _require('graceful-fs'); gfs.gracefulify(realFs); fs = realFs; } catch { fs = realFs; }
 import path from 'path';
 import {
+  withRuleDeployment,
   ensureDir,
   listMdFiles,
   listMdFilesRecursive,
@@ -53,6 +55,8 @@ import {
   deploySoulCompanions,
   loadRuntimeModelCatalog
 } from './base.mjs';
+
+import { writeContextFileSync } from './context-write.mjs';
 const modelCatalog = loadRuntimeModelCatalog(staticModelCatalog);
 
 // ============================================================================
@@ -429,6 +433,7 @@ export function deploySkills(skillDirs, targetDir, opts) {
  * Deploy rules to .github/instructions/ as .instructions.md files
  */
 export function deployRules(ruleFiles, targetDir, opts) {
+  if (opts.ruleDelivery) return [];
   const destDir = path.join(targetDir, paths.rules);
   ensureDir(destDir, opts.dryRun);
   cleanupOldRuleFiles(destDir, opts);
@@ -475,14 +480,14 @@ export function createCopilotInstructions(target, srcRoot, dryRun) {
     if (dryRun) {
       console.log(`[dry-run] Would update existing copilot-instructions.md with AIWG section`);
     } else {
-      fs.writeFileSync(destPath, combined, 'utf8');
+      writeContextFileSync(destPath, combined, 'utf8');
       console.log('Updated copilot-instructions.md with AIWG SDLC framework section');
     }
   } else {
     if (dryRun) {
       console.log(`[dry-run] Would create copilot-instructions.md from template`);
     } else {
-      fs.writeFileSync(destPath, template, 'utf8');
+      writeContextFileSync(destPath, template, 'utf8');
       console.log('Created copilot-instructions.md from template');
     }
   }
@@ -495,8 +500,8 @@ export function createCopilotInstructions(target, srcRoot, dryRun) {
 export async function postDeploy(targetDir, opts) {
   initializeFrameworkWorkspace(targetDir, opts.mode, opts.dryRun, opts.srcRoot);
 
-  // Create copilot-instructions.md
-  createCopilotInstructions(targetDir, opts.srcRoot, opts.dryRun);
+  // copilot-instructions.md is Copilot's context file: --no-context-files leaves it alone.
+  if (opts.contextFiles !== false) createCopilotInstructions(targetDir, opts.srcRoot, opts.dryRun);
 }
 
 // ============================================================================
@@ -517,6 +522,10 @@ export function getFileExtension(type) {
 // ============================================================================
 
 export async function deploy(opts) {
+  return withRuleDeployment(opts, { name, paths, kernelSkillsPath }, deploySelected);
+}
+
+async function deploySelected(opts) {
   const {
     srcRoot,
     target,

package/tools/agents/providers/cursor.mjs

@@ -414,7 +414,7 @@ export async function postDeploy(targetDir, opts) {
   initializeFrameworkWorkspace(targetDir, opts.mode, opts.dryRun, opts.srcRoot);
 
   if (opts.createAgentsMd) {
-    createAgentsMd(targetDir, opts.srcRoot, opts.dryRun);
+    if (opts.contextFiles !== false) createAgentsMd(targetDir, opts.srcRoot, opts.dryRun);
   }
 
   // PUW-019 (#1120): wire environment.json + worktrees.json templates.

package/tools/agents/providers/deepseek-harness.mjs

@@ -46,7 +46,7 @@ export function deployCordisPatch(target, opts) {
 }
 
 export async function postDeploy(target, opts) {
-  if (opts.createAgentsMd || (!opts.commandsOnly && !opts.skillsOnly && !opts.rulesOnly)) createAgentsMd(target, opts.srcRoot, opts.dryRun);
+  if (opts.contextFiles !== false && (opts.createAgentsMd || (!opts.commandsOnly && !opts.skillsOnly && !opts.rulesOnly))) createAgentsMd(target, opts.srcRoot, opts.dryRun);
   if (!opts.quiet) console.log('DeepSeek Harness: runtime credentials remain environment-only; use a reviewed ephemeral route patch.');
 }
 

package/tools/agents/providers/factory.mjs

@@ -25,6 +25,7 @@ let fs;
 try { const gfs = _require('graceful-fs'); gfs.gracefulify(realFs); fs = realFs; } catch { fs = realFs; }
 import path from 'path';
 import {
+  withRuleDeployment,
   ensureDir,
   listMdFiles,
   listMdFilesRecursive,
@@ -576,6 +577,7 @@ export function deploySkills(skillDirs, targetDir, opts) {
  * Deploy rules to .factory/rules/
  */
 export function deployRules(ruleFiles, targetDir, opts) {
+  if (opts.ruleDelivery) return [];
   const destDir = path.join(targetDir, paths.rules);
   ensureDir(destDir, opts.dryRun);
   cleanupOldRuleFiles(destDir, opts);
@@ -816,7 +818,7 @@ export async function postDeploy(targetDir, opts) {
 
   // Create/update AGENTS.md if requested
   if (opts.createAgentsMd) {
-    createAgentsMd(targetDir, opts.srcRoot, opts.dryRun);
+    if (opts.contextFiles !== false) createAgentsMd(targetDir, opts.srcRoot, opts.dryRun);
   }
 }
 
@@ -945,6 +947,10 @@ export function getFileExtension(type) {
  * Main deployment function for Factory provider
  */
 export async function deploy(opts) {
+  return withRuleDeployment(opts, { name, paths, kernelSkillsPath, transformSkillMd: transformSkillFrontmatter }, deploySelected);
+}
+
+async function deploySelected(opts) {
   const {
     srcRoot,
     target,

package/tools/agents/providers/grok-build.mjs

@@ -16,6 +16,8 @@ import fs from 'node:fs';
 import { createHash, randomUUID } from 'node:crypto';
 import yaml from 'js-yaml';
 import {
+  withRuleDeployment,
+  replaceBoundRulesBlock,
   createAgentsMdFromTemplate,
   deploySkillsWithKernelRouting,
   collectFrameworkArtifacts,
@@ -224,7 +226,17 @@ function matchesSkillSource(source, target) {
       if (relative.endsWith(path.sep)) return true;
       let content = fs.readFileSync(path.join(source, relative), 'utf8');
       if (relative === 'SKILL.md') content = injectPlatformInContent(content, 'grok-build');
-      return content === fs.readFileSync(path.join(target, relative), 'utf8');
+      const deployed = fs.readFileSync(path.join(target, relative), 'utf8');
+      if (content === deployed) return true;
+      if (relative !== 'SKILL.md' || !deployed.includes('<!-- AIWG:bound-rules:start -->')) return false;
+      // Activation projection appends generated bindings. Verify the complete
+      // deployed bytes against the receipt before comparing the authored body;
+      // an operator edit (including inside the binding block) must survive.
+      const receipt = JSON.parse(fs.readFileSync(path.join(target, '.aiwg-manifest.json'), 'utf8'));
+      const digest = `sha256:${createHash('sha256').update(deployed).digest('hex')}`;
+      return receipt.skillSource === path.resolve(source)
+        && receipt.managed?.[relative]?.hash === digest
+        && replaceBoundRulesBlock(content, []).trimEnd() === replaceBoundRulesBlock(deployed, []).trimEnd();
     });
   } catch { return false; }
 }
@@ -326,7 +338,7 @@ export function uninstall(target, opts = {}) {
 
 export async function postDeploy(target, opts = {}) {
   if (opts.createAgentsMd || (!opts.commandsOnly && !opts.skillsOnly && !opts.rulesOnly)) {
-    createAgentsMd(target, opts.srcRoot, opts.dryRun);
+    if (opts.contextFiles !== false) createAgentsMd(target, opts.srcRoot, opts.dryRun);
   }
   if (!opts.quiet) {
     const home = resolveGrokHome(opts.env || process.env);
@@ -344,6 +356,10 @@ export function getFileExtension() {
 }
 
 export async function deploy(opts) {
+  return withRuleDeployment(opts, { name, paths, kernelSkillsPath }, deploySelected);
+}
+
+async function deploySelected(opts) {
   const mode = normalizeDeploymentMode(opts.mode);
   if (opts.createAgentsMd || (!opts.commandsOnly && !opts.skillsOnly && !opts.rulesOnly)) {
     assertSafeAgentsMd(opts.target);

package/tools/agents/providers/grokbot.mjs

@@ -171,7 +171,7 @@ export async function postDeploy(targetDir, opts = {}) {
     opts.createAgentsMd ||
     (!opts.commandsOnly && !opts.skillsOnly && !opts.rulesOnly)
   ) {
-    createAgentsMd(targetDir, opts.srcRoot, opts.dryRun);
+    if (opts.contextFiles !== false) createAgentsMd(targetDir, opts.srcRoot, opts.dryRun);
   }
   if (!opts.quiet) {
     const root = resolveGrokbotSkillsDir(opts.env || process.env);

package/tools/agents/providers/hermes.mjs

@@ -1,3 +1,4 @@
+import { importImpl } from '../../_resolve-impl.mjs';
 /**
  * Hermes Agent Provider
  *
@@ -41,6 +42,8 @@ import {
   stripPlatformsFromContent,
 } from './base.mjs';
 
+import { writeContextFileSync } from './context-write.mjs';
+
 // ============================================================================
 // Hermes home resolution (HERMES_HOME) — #2119
 // ============================================================================
@@ -224,9 +227,9 @@ export function assertContextBudget(content, name = 'AGENTS.md', rules = []) {
  * priming on every Hermes turn (#1318 / S7; skill-discovery added #1347).
  *
  * The full rule bodies are reachable without MCP via `aiwg discover` and
- * `aiwg show rule <name>`; MCP exposes the same path through `rule-list` and
+ * `aiwg show rule <name> --body`; MCP exposes the same path through `rule-list` and
  * `rule-show` when configured (#1320). The bodies exceed Hermes's 20K context
- * cap if inlined verbatim (anti-laziness alone is 32K chars), so we inline
+ * cap if inlined verbatim (anti-laziness alone was 32K chars; it now ships as a compact core body, #3450), so we inline
  * compressed directives only and point to CLI/MCP for the full text.
  *
  * Selection criteria: rules tagged CRITICAL/HIGH enforcement level whose
@@ -240,7 +243,7 @@ const CRITICAL_RULE_DIRECTIVES = `## CRITICAL Rules (always apply)
 These are the highest-enforcement AIWG rules. Full bodies are reachable without
 MCP:
 - Find rules: \`aiwg discover "rule <topic>" --type rule\`
-- Fetch a rule: \`aiwg show rule <name>\`
+- Fetch a rule: \`aiwg show rule <name> --body\`
 
 If the optional MCP sidecar is configured, the same surface is available through
 \`mcp_aiwg_rule_list\` and \`mcp_aiwg_rule_show\`.
@@ -260,13 +263,6 @@ Never add AI-tool attribution to commits, PRs, code, or docs. No \`Co-Authored-B
 no "Generated with", no "Written by [AI tool]". The AI is a tool; tools don't sign
 their output. Applies to ALL platforms (Claude, Codex, Copilot, Cursor, etc.).
 
-### Rule: anti-laziness
-Never delete tests to make them pass. Never skip/disable tests. Never remove
-features instead of fixing them. Never weaken assertions to be meaningless.
-Never suppress CI/pipeline signals (\`continue-on-error\`, \`|| true\`, \`set +e\`).
-If stuck after 3 honest attempts: escalate with full context, don't shortcut.
-Within scope: leave nothing half-done — code + tests + docs + verification.
-
 ### Rule: citation-policy
 Never fabricate citations, DOIs, URLs, or page numbers. Only cite sources that
 exist in the research corpus (.aiwg/research/sources/). Match claim strength
@@ -331,6 +327,7 @@ function mergeHermesContext(file, generated, kind) {
 }
 
 export function generateAgentsMd(agentCount, skillCount, targetDir, opts) {
+  if (opts.contextFiles === false) return;
   const { dryRun } = opts;
 
   // Startup is reserved for rule contracts. Workflow routing, artifact catalogs,
@@ -339,7 +336,7 @@ export function generateAgentsMd(agentCount, skillCount, targetDir, opts) {
   const header = `# AIWG Integration
 
 Skills: \`$HERMES_HOME/skills/\` (kernel), \`$HERMES_HOME/skills/.aiwg/\` (standard).
-Find: \`aiwg discover "rule <topic>" --type rule\`. Fetch: \`aiwg show rule <name>\`.
+Find: \`aiwg discover "rule <topic>" --type rule\`. Fetch: \`aiwg show rule <name> --body\`.
 MCP is optional; \`mcp_aiwg_rule_show\` exposes the same rule catalog.
 `;
 
@@ -361,7 +358,7 @@ MCP is optional; \`mcp_aiwg_rule_show\` exposes the same rule catalog.
   if (dryRun) {
     console.log(`[dry-run] Would write AGENTS.md (${output.length} chars, ${Math.round(output.length / 4)} tokens estimated)`);
   } else {
-    fs.writeFileSync(destPath, output, 'utf8');
+    writeContextFileSync(destPath, output, 'utf8');
     const charCount = output.length;
     const tokenEstimate = Math.round(charCount / 4);
     let budgetNote;
@@ -403,7 +400,7 @@ when the full AIWG project context is needed.
   if (dryRun) {
     console.log(`[dry-run] Would write .hermes.md (${body.length} chars)`);
   } else {
-    fs.writeFileSync(destPath, mergeHermesContext(destPath, body, 'routing'), 'utf8');
+    writeContextFileSync(destPath, mergeHermesContext(destPath, body, 'routing'), 'utf8');
     console.log(`  Created .hermes.md (${body.length} chars)`);
   }
   return 1;
@@ -533,7 +530,7 @@ async function deploySelected(opts) {
   // Generate AGENTS.md (with inlined CRITICAL rule priming, #1318/#1532)
   // AND .hermes.md thin pointer (resolves #1319 doc-debt, was claimed in
   // CHANGELOG but not previously implemented).
-  if (!skillsOnly && !opts.commandsOnly && !opts.rulesOnly) {
+  if (opts.contextFiles !== false && !skillsOnly && !opts.commandsOnly && !opts.rulesOnly) {
     const artifacts = collectFrameworkArtifacts(srcRoot, normalizedMode, {
       includeAgents: true,
       includeCommands: false,
@@ -560,7 +557,7 @@ async function deploySelected(opts) {
   if (!opts.quiet) {
     console.log('');
     console.log(`Skills root: ${kernelSkillsPath}`);
-    console.log('Rules are in AGENTS.md as compressed directives; full bodies via `aiwg show rule <name>`.');
+    console.log('Rules are in AGENTS.md as compressed directives; full bodies via `aiwg show rule <name> --body`.');
     console.log('Optional: configure config.yaml to connect AIWG MCP server.');
     console.log('See: docs/integrations/hermes-quickstart.md (optional MCP setup)');
   }

package/tools/agents/providers/muse-hooks.mjs

@@ -43,9 +43,7 @@
  * Servers inherit the operator's process environment; pass `MUSE_SESSION_ID`
  * through at runtime instead of hardcoding a session id into `env`.
  *
- * This module is intentionally dependency-free (node builtins +
- * muse-paths.mjs only) so provider-policy-style import graphs never pull it
- * in transitively.
+ * MCP writes use the shared config writer, resolved for source and packaged installs.
  *
  * @issue #228
  */
@@ -53,9 +51,13 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { importImpl } from '../../_resolve-impl.mjs';
 import { stripJsonComments } from './base.mjs';
 import { resolveMuseXdgSkillsDir, museXdgSkillsDirRemediation } from './muse-paths.mjs';
 
+const { assertConfigDestination, writeConfigAtomic, writeConfigTransaction } = await importImpl(import.meta.url, 'mcp/config-file.mjs');
+
 // ---------------------------------------------------------------------------
 // Shared JSON helpers
 // ---------------------------------------------------------------------------
@@ -631,7 +633,7 @@ export function mergeMcpProfile(existingDoc, opts = {}) {
  * preserving unknown keys, timestamped backup before writing, atomic write,
  * dry-run diff with zero writes, fail closed on unparseable settings.
  */
-export function deployMuseMcp(opts = {}) {
+export async function deployMuseMcp(opts = {}) {
   const { dryRun = false, quiet = false, mcp = false, env = process.env, userHome = os.homedir() } = opts;
   const log = quiet ? () => {} : (msg) => console.log(msg);
 
@@ -642,6 +644,8 @@ export function deployMuseMcp(opts = {}) {
 
   const settingsPath = assertMuseUserSettingsPath(env, userHome);
   const configDir = path.dirname(settingsPath);
+  await assertConfigDestination(settingsPath);
+  await assertConfigDestination(path.join(configDir, MUSE_MCP_SIDECAR_NAME));
   const { doc: existingDoc, raw: existingRaw, existed } = readSettingsDoc(settingsPath);
   const sidecar = readMcpSidecar(configDir);
   const profile = aiwgMcpServerProfile();
@@ -680,14 +684,15 @@ export function deployMuseMcp(opts = {}) {
     return { settingsPath, changed: true, plan, wrote: false, warnings };
   }
 
-  fs.mkdirSync(configDir, { recursive: true });
   let backupPath = null;
   if (existed) {
-    backupPath = `${settingsPath}.aiwg-backup-${new Date().toISOString().replace(/[:.]/g, '-')}`;
-    fs.copyFileSync(settingsPath, backupPath);
+    backupPath = `${settingsPath}.aiwg-backup-${new Date().toISOString().replace(/[:.]/g, '-')}-${randomUUID()}`;
+    await writeConfigAtomic(backupPath, existingRaw, { userScope: true });
   }
-  atomicWrite(settingsPath, afterText);
-  atomicWrite(sidecar.path, canonicalJson({ version: 1, servers: ['aiwg'] }));
+  await writeConfigTransaction([
+    { file: settingsPath, content: afterText, options: { userScope: true } },
+    { file: sidecar.path, content: canonicalJson({ version: 1, servers: ['aiwg'] }), options: { userScope: true } },
+  ]);
 
   log(`Muse MCP: merged AIWG stdio profile into ${settingsPath}`);
   for (const step of plan) log(`  ${step}`);
@@ -700,11 +705,13 @@ export function deployMuseMcp(opts = {}) {
  * Removal path: drop the AIWG-managed `aiwg` server key (only when recorded
  * in the sidecar) and delete the sidecar. Operator servers are never touched.
  */
-export function pruneMuseMcp(opts = {}) {
+export async function pruneMuseMcp(opts = {}) {
   const { dryRun = false, quiet = false, env = process.env, userHome = os.homedir() } = opts;
   const log = quiet ? () => {} : (msg) => console.log(msg);
   const settingsPath = assertMuseUserSettingsPath(env, userHome);
   const configDir = path.dirname(settingsPath);
+  await assertConfigDestination(settingsPath);
+  await assertConfigDestination(path.join(configDir, MUSE_MCP_SIDECAR_NAME));
 
   if (!fs.existsSync(settingsPath)) {
     log(`Muse MCP: no ${settingsPath}; nothing to prune.`);
@@ -731,10 +738,10 @@ export function pruneMuseMcp(opts = {}) {
     return { settingsPath, pruned: true, wrote: false };
   }
 
-  const backupPath = `${settingsPath}.aiwg-backup-${new Date().toISOString().replace(/[:.]/g, '-')}`;
-  fs.copyFileSync(settingsPath, backupPath);
-  atomicWrite(settingsPath, canonicalJson(merged));
-  if (fs.existsSync(sidecar.path)) fs.unlinkSync(sidecar.path);
+  const backupPath = `${settingsPath}.aiwg-backup-${new Date().toISOString().replace(/[:.]/g, '-')}-${randomUUID()}`;
+  await writeConfigAtomic(backupPath, existingRaw, { userScope: true });
+  await writeConfigAtomic(settingsPath, canonicalJson(merged), { userScope: true });
+  if (await assertConfigDestination(sidecar.path)) fs.unlinkSync(sidecar.path);
   log(`Muse MCP: removed mcp_servers.aiwg from ${settingsPath} (backup: ${backupPath}).`);
   return { settingsPath, pruned: true, wrote: true, backupPath };
 }

package/tools/agents/providers/muse.mjs

@@ -35,6 +35,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import {
+  withRuleDeployment,
   collectFrameworkArtifacts,
   createAgentsMdFromTemplate,
   deploySkillsWithKernelRouting,
@@ -226,7 +227,7 @@ export async function postDeploy(targetDir, opts = {}) {
   // bridge, managed hooks, and an opted-in MCP profile must not be skipped.
   const fullDeploy = !opts.commandsOnly && !opts.rulesOnly && (!opts.skillsOnly || opts.kernelOnly === true);
   if (opts.createAgentsMd || fullDeploy) {
-    createAgentsMd(targetDir, opts.srcRoot, opts.dryRun);
+    if (opts.contextFiles !== false) createAgentsMd(targetDir, opts.srcRoot, opts.dryRun);
   }
 
   // #228 — managed project hooks (.muse/hooks.json). Default on, mirroring
@@ -240,7 +241,7 @@ export async function postDeploy(targetDir, opts = {}) {
   // #228 — optional MCP settings profile. Explicit opt-in only (--mcp);
   // default `aiwg use --provider muse` never touches user settings.
   if (fullDeploy && opts.mcp === true) {
-    deployMuseMcp(opts);
+    await deployMuseMcp(opts);
   }
 
   if (!opts.quiet) {
@@ -265,6 +266,10 @@ export async function postDeploy(targetDir, opts = {}) {
 }
 
 export async function deploy(opts = {}) {
+  return withRuleDeployment(opts, { name, paths, kernelSkillsPath }, deploySelected);
+}
+
+async function deploySelected(opts) {
   const {
     srcRoot,
     target,