@aiwg/cli 2026.10.4 → 2026.10.6

package/tools/agents/providers/base.mjs

@@ -104,7 +104,7 @@ export function listMdFiles(dir, excludePatterns = []) {
   const excluded = [...defaultExcluded, ...excludePatterns];
   return fs
     .readdirSync(dir, { withFileTypes: true })
-    .filter((e) => e.isFile() && e.name.toLowerCase().endsWith('.md') && !e.name.toLowerCase().endsWith('.soul.md') && !excluded.includes(e.name))
+    .filter((e) => e.isFile() && e.name.toLowerCase().endsWith('.md') && !e.name.toLowerCase().endsWith('.soul.md') && !e.name.toLowerCase().endsWith('.core.md') && !excluded.includes(e.name))
     .map((e) => path.join(dir, e.name));
 }
 
@@ -2474,7 +2474,7 @@ export function applyInlineRuleBudget(ruleFiles) {
 /**
  * Tier gate (#1673, enforcement-tiered deployment ADR). Only CRITICAL and HIGH
  * rules are inlined into a provider's always-on rule directory; MEDIUM/LOW are
- * left on-demand (reachable via `aiwg show rule <name>` and the assembled
+ * left on-demand (reachable via `aiwg show rule <name> --body` and the assembled
  * RULES-INDEX pointer index). Index files and rules with no enforcement marker
  * default to always-on, so an un-triaged or structural file is never dropped.
  */
@@ -2558,17 +2558,17 @@ export function renderOnDemandRuleSection(onDemandFiles, opts = {}) {
     'on demand:',
     '',
     '```bash',
-    'aiwg show rule <name>',
+    'aiwg show rule <name> --body',
     '```',
     '',
-    ...names.map((n) => `- \`${n}\` — \`aiwg show rule ${n}\``),
+    ...names.map((n) => `- \`${n}\` — \`aiwg show rule ${n} --body\``),
   ].join('\n');
 }
 
 /**
  * Write a compact on-demand rule index (#1673) into a provider's rule dir.
  * Lists the MEDIUM/LOW rules that are NOT inlined at startup, with the
- * `aiwg show rule <name>` fetch hint. Removes a stale index when empty.
+ * `aiwg show rule <name> --body` fetch hint. Removes a stale index when empty.
  */
 export function writeOnDemandRuleIndex(destDir, onDemandFiles, opts = {}) {
   const indexPath = path.join(destDir, 'RULES-ONDEMAND.md');
@@ -2588,10 +2588,10 @@ export function writeOnDemandRuleIndex(destDir, onDemandFiles, opts = {}) {
     'fetch any rule body on demand:',
     '',
     '```bash',
-    'aiwg show rule <name>',
+    'aiwg show rule <name> --body',
     '```',
     '',
-    ...names.map((n) => `- \`${n}\` — \`aiwg show rule ${n}\``),
+    ...names.map((n) => `- \`${n}\` — \`aiwg show rule ${n} --body\``),
     '',
   ];
   if (demotedNames.length > 0) {
@@ -2605,7 +2605,7 @@ export function writeOnDemandRuleIndex(destDir, onDemandFiles, opts = {}) {
       '(AIWG_RULES_INLINE_BUDGET_TOKENS) and break subagent dispatch with "Prompt is too long".',
       'Fetch any of them before work they govern:',
       '',
-      ...demotedNames.map((n) => `- \`${n}\` — \`aiwg show rule ${n}\``),
+      ...demotedNames.map((n) => `- \`${n}\` — \`aiwg show rule ${n} --body\``),
       '',
     );
   }
@@ -2803,7 +2803,9 @@ export function getAddonFiles(srcRoot, options = {}) {
 // ============================================================================
 
 /**
- * Load rules manifest from source directory
+ * Load rules manifest from source directory.
+ * Inventory metadata only: delivery is decided by rule `activation` (rule-delivery.mjs);
+ * the former manifest `tiers` deploy policy was never consulted and was removed (#3450).
  * @param {string} srcRoot - Source root directory
  * @returns {object|null} - Parsed manifest or null if not found
  */
@@ -3168,8 +3170,9 @@ export function migrateCommandsDirectory(commandsDir, opts = {}) {
     const rel = path.relative(process.cwd(), commandsDir);
     // The condition is a property of the directory, not of each deployed unit;
     // emit it once per run no matter how many units pass through.
-    if (warnedCommandsDirs.has(commandsDir)) return false;
-    warnedCommandsDirs.add(commandsDir);
+    const warned = opts.warnedCommandsDirs || warnedCommandsDirs;
+    if (warned.has(commandsDir)) return false;
+    warned.add(commandsDir);
 
     const stale = listManagedCommandFiles(commandsDir);
     if (stale.length === 0) return false;
@@ -3338,7 +3341,7 @@ export function replaceBoundRulesBlock(content, rules = []) {
   const unique = [...new Map(rules.map(rule => [rule.name, rule])).values()]
     .sort((a, b) => a.name.localeCompare(b.name));
   return `${clean}${clean.endsWith('\n') ? '' : '\n'}\n<!-- AIWG:bound-rules:start -->\n## Bound rules\n\nRequired reading on every invocation: fetch and follow every bound rule below before starting governed work. A summary or discovery pointer does not discharge this obligation.\n\n${unique.map(rule =>
-    `- ${rule.name} — ${rule.summary}\n  Fetch and follow before governed work: \`aiwg show rule ${rule.name}\`.`
+    `- ${rule.name} — ${rule.summary}\n  Fetch and follow before governed work: \`aiwg show rule ${rule.name} --body\`.`
   ).join('\n')}\n<!-- AIWG:bound-rules:end -->\n`;
 }
 
@@ -3347,8 +3350,11 @@ export function injectBoundRules(content, source, opts = {}) {
   return replaceBoundRulesBlock(content, opts.ruleDelivery.bindings.get(path.resolve(source)) || []);
 }
 
-/** All provider output is staged; the complete startup guard runs before promotion. */
+/** Rule delivery stages output and guards startup before promotion. Deferred
+ * kernel passes leave rule delivery to the final source in the invocation. */
 export async function withRuleDeployment(opts, provider, deploy) {
+  if (opts.kernelOnly && opts.deferRuleProjection && provider.name !== 'warp'
+    && !globalThis[Symbol.for('aiwg.provider-preparation-hook.v1')]) return deploy(opts);
   const { deployWithRuleDelivery } = await import('./rule-delivery.mjs');
   return deployWithRuleDelivery(opts, provider, deploy);
 }

package/tools/agents/providers/claude.mjs

@@ -416,7 +416,7 @@ export async function postDeploy(targetDir, opts) {
   }
 
   // Hook file architecture: write AIWG.md and wire @AIWG.md into CLAUDE.md
-  if (opts.srcRoot) {
+  if (opts.srcRoot && opts.contextFiles !== false) {
     deployHookFile(targetDir, opts);
   }
 }

package/tools/agents/providers/codex.mjs

@@ -35,6 +35,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 +67,6 @@ import {
   parseFrontmatter,
   resolveAiwgRoot
 } from './base.mjs';
-const modelCatalog = loadRuntimeModelCatalog(staticModelCatalog);
 
 function resolveCodexHelperRoot(srcRoot) {
   const resolved = resolveAiwgRoot(srcRoot);
@@ -101,7 +101,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 +124,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 +204,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 +239,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 +278,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 +312,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 +339,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 +394,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'));
@@ -518,7 +512,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/copilot.mjs

@@ -27,6 +27,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,
@@ -429,6 +430,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);
@@ -495,8 +497,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 +519,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

@@ -224,9 +224,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 +240,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 +260,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 +324,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 +333,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.
 `;
 
@@ -533,7 +527,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 +554,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,