@aiwg/cli 2026.10.5 → 2026.10.7

package/tools/agents/deploy-agents.mjs

@@ -32,6 +32,7 @@
  *   --model-tier <tier>      Override all artifacts with economy|standard|premium
  *   --as-agents-md               Aggregate to single AGENTS.md (OpenAI/Codex)
  *   --create-agents-md           Create/update AGENTS.md template
+  --no-context-files           Preserve WORKSPACE.md, AIWG.md and AGENTS.md (including managed blocks)
  *   --skip-commands-migration    Skip deleting the commands directory (warns about duplicate TUI entries) (Factory/Codex/OpenCode/Cursor)
  *   --deploy-source <name>       Managed-marker source for deployed artifacts (default: bundled)
  *   --deploy-version <version>   Managed-marker version for deployed artifacts (default: source package.json)
@@ -75,6 +76,8 @@ const staticModelCatalog = _require('../../agentic/code/providers/model-catalog.
 let fs;
 try { const gfs = _require('graceful-fs'); gfs.gracefulify(realFs); fs = realFs; } catch { fs = realFs; }
 import path from 'path';
+import { importImpl } from '../_resolve-impl.mjs';
+const { resolveDeployVersion } = await importImpl(import.meta.url, 'providers/deploy-version.mjs');
 import os from 'os';
 import readline from 'readline';
 import { fileURLToPath } from 'url';
@@ -96,20 +99,6 @@ import {
   resolveAiwgRoot,
   updateSidecarManifest,
 } from './providers/base.mjs';
-const modelCatalog = loadRuntimeModelCatalog(staticModelCatalog);
-
-/**
- * Read version from package.json at the source root.
- * Falls back to 'unknown' if unavailable.
- */
-function getDeployVersion(srcRoot) {
-  try {
-    const pkg = JSON.parse(fs.readFileSync(path.join(srcRoot, 'package.json'), 'utf8'));
-    return pkg.version || 'unknown';
-  } catch {
-    return 'unknown';
-  }
-}
 
 // ============================================================================
 // Provider Registry
@@ -421,10 +410,8 @@ function pruneStaleAiwgArtifacts(provider, target, srcRoot, opts, explicitSource
   }
 
   if (opts.kernelOnly) {
-    // A kernel-only run deploys skills and nothing else (deployCommands /
-    // deployRules / deployBehaviors are all forced false above), so it has no
-    // basis for judging any flat artifact stale. The empty desired set below
-    // exists for one narrow migration: clearing agents/commands/rules left by
+    // Kernel-only delivers skills and rules. The empty desired set below
+    // applies only to bulk agents/commands left by
     // the pre-#152 bulk default, when the bulk install is the only thing this
     // project ever deployed.
     //
@@ -438,7 +425,7 @@ function pruneStaleAiwgArtifacts(provider, target, srcRoot, opts, explicitSource
       }
       return;
     }
-    for (const type of ['agents', 'commands', 'rules']) {
+    for (const type of ['agents', 'commands']) {
       const relPath = provider.paths?.[type];
       if (!relPath || relPath.endsWith('.md')) continue;
       const destDir = path.isAbsolute(relPath) ? relPath : path.join(target, relPath);
@@ -499,6 +486,8 @@ export function parseArgs(args = process.argv.slice(2)) {
     efficiencyModel: null,
     asAgentsMd: false,
     createAgentsMd: false,
+    contextFiles: true,
+    projectScope: false,
     deployCommands: false,
     deploySkills: false,
     deployRules: false,
@@ -509,6 +498,8 @@ export function parseArgs(args = process.argv.slice(2)) {
     strict: false,
     reportOnly: true,
     kernelOnly: false,
+    deferRuleProjection: false,
+    additionalSources: [],
     filter: null,           // Glob pattern for agent names
     filterRole: null,       // Filter by role: reasoning|coding|efficiency
     save: false,            // Save model config to project models.json
@@ -532,6 +523,11 @@ export function parseArgs(args = process.argv.slice(2)) {
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
     if (a === '--source' && args[i + 1]) cfg.source = path.resolve(args[++i]);
+    else if (a === '--additional-source') {
+      const source = args[++i];
+      if (!source || source.startsWith('--')) throw new Error('--additional-source requires a source directory');
+      cfg.additionalSources.push(path.resolve(source));
+    }
     else if (a === '--target' && args[i + 1]) cfg.target = path.resolve(args[++i]);
     else if (a === '--mode' && args[i + 1]) cfg.mode = String(args[++i]).toLowerCase();
     else if (a === '--scope') {
@@ -540,6 +536,7 @@ export function parseArgs(args = process.argv.slice(2)) {
         throw new Error(`--scope expected 'user' or 'project', got '${scope ?? '(missing)'}'`);
       }
       cfg.userScope = scope === 'user';
+      cfg.projectScope = scope === 'project';
     }
     else if (a === '--user') cfg.userScope = true;
     else if (a === '--dry-run') cfg.dryRun = true;
@@ -563,6 +560,8 @@ export function parseArgs(args = process.argv.slice(2)) {
     else if (a === '--allow-over-budget') cfg.allowOverBudget = true;
     else if (a === '--report-only') cfg.reportOnly = true;
     else if (a === '--kernel-only') cfg.kernelOnly = true;
+    // Internal use orchestration: the final source owns rule presentation.
+    else if (a === '--defer-rule-projection') cfg.deferRuleProjection = true;
     else if (a === '--deploy-behaviors') cfg.deployBehaviors = true;
     else if (a === '--filter' && args[i + 1]) cfg.filter = args[++i];
     else if (a === '--filter-role' && args[i + 1]) cfg.filterRole = args[++i];
@@ -579,12 +578,12 @@ export function parseArgs(args = process.argv.slice(2)) {
     // managed-hooks opt-out (default on, mirroring the Claude autoInstall policy).
     else if (a === '--mcp') cfg.mcp = true;
     else if (a === '--no-hooks') cfg.hooks = false;
+    else if (a === '--no-context-files') cfg.contextFiles = false;
     else if (a === '--deploy-source' && args[i + 1]) cfg.deploySource = String(args[++i]);
     else if (a === '--listing-budget') cfg.listingBudget = true;
     else if (a === '--deploy-version' && args[i + 1]) cfg.deployVersion = String(args[++i]);
     else if (a === '--help' || a === '-h') {
-      printHelp();
-      process.exit(0);
+      cfg.help = true;
     }
   }
   return cfg;
@@ -610,7 +609,7 @@ Options:
   --commands-only          Deploy only commands (skip agents)
   --skills-only            Deploy only skills (skip agents)
   --rules-only             Deploy only rules (skip agents)
-  --kernel-only            Deploy kernel skills only and prune managed bulk artifacts
+  --kernel-only            Deploy kernel skills and rules; prune managed bulk agents/commands
   --dry-run                Show what would be deployed without writing
   --force                  Overwrite existing files
   --provider <name>        Target provider (see below)
@@ -630,6 +629,7 @@ Options:
                            (.muse/hooks.json; installed by default)
   --as-agents-md               Aggregate to single AGENTS.md (Codex)
   --create-agents-md           Create/update AGENTS.md template
+  --no-context-files           Preserve WORKSPACE.md, AIWG.md and AGENTS.md (including managed blocks)
   --skip-commands-migration    Skip deleting the commands directory before skills deployment
   --listing-budget             Honor the provider startup-listing cap even with --copy-all
   --deploy-source <name>       Managed-marker source stamped into deployed artifacts.
@@ -743,7 +743,7 @@ function resolveProvider(name) {
       console.error('');
       for (const line of UNSUPPORTED_PROVIDER_HINTS[candidate]) console.error(line);
     }
-    process.exit(1);
+    throw new Error(`Unknown provider: ${name}`);
   }
   return resolved;
 }
@@ -753,14 +753,17 @@ function resolveProvider(name) {
  */
 async function loadProvider(providerName) {
   const resolved = resolveProvider(providerName);
-  const providerPath = `./providers/${resolved}.mjs`;
+  // Resolve against this module, not the caller's cwd: in-process callers
+  // (including module runners such as Vitest) cannot resolve a bare relative
+  // specifier held in a variable.
+  const providerUrl = new URL(`./providers/${resolved}.mjs`, import.meta.url).href;
 
   try {
-    const provider = await import(providerPath);
+    const provider = await import(providerUrl);
     return provider.default || provider;
   } catch (err) {
     console.error(`Failed to load provider '${resolved}':`, err.message);
-    process.exit(1);
+    throw err;
   }
 }
 
@@ -896,7 +899,7 @@ function deepMerge(target, source) {
  * @param {string} targetDir - Resolved target directory
  * @returns {Promise<boolean>} true = proceed with migration, false = skip
  */
-async function promptCommandsMigration(cfg, provider, targetDir) {
+async function promptCommandsMigration(cfg, provider, targetDir, interactive = process.stdout.isTTY) {
   // Home-directory providers share commands across projects — do not delete.
   if (provider.capabilities?.homeDirectoryDeploy) return false;
   // Some providers intentionally expose both surfaces with different runtime
@@ -914,7 +917,7 @@ async function promptCommandsMigration(cfg, provider, targetDir) {
   if (entries.length === 0) return false;
 
   // Non-interactive context: migrate silently.
-  if (cfg.quiet || !process.stdout.isTTY) return true;
+  if (cfg.quiet || !interactive) return true;
 
   const rel = path.relative(process.cwd(), commandsDir);
   console.log(`\n⚠  Commands → Skills Migration`);
@@ -948,6 +951,8 @@ async function promptCommandsMigration(cfg, provider, targetDir) {
 
 export async function main(args = process.argv.slice(2), internal = {}) {
   const cfg = parseArgs(args);
+  if (cfg.help) { printHelp(); return 0; }
+  const modelCatalog = loadRuntimeModelCatalog(staticModelCatalog);
 
   // Resolve source directory (default to repo root relative to this script)
   const __filename = fileURLToPath(import.meta.url);
@@ -956,8 +961,7 @@ export async function main(args = process.argv.slice(2), internal = {}) {
 
   // Validate source directory
   if (!fs.existsSync(srcRoot)) {
-    console.error(`Source directory not found: ${srcRoot}`);
-    process.exit(1);
+    throw new Error(`Source directory not found: ${srcRoot}`);
   }
 
   // Validate target directory
@@ -1020,6 +1024,10 @@ export async function main(args = process.argv.slice(2), internal = {}) {
 
   // Load provider module
   const provider = await loadProvider(cfg.provider);
+  if (cfg.additionalSources.length && provider.name !== 'omp') throw new Error('--additional-source requires the OMP provider');
+  for (const source of cfg.additionalSources) {
+    if (!fs.statSync(source).isDirectory()) throw new Error(`Additional source is not a directory: ${source}`);
+  }
   if (!cfg.quiet) console.log(`\nLoaded provider: ${provider.name}`);
 
   // Build options for provider
@@ -1038,11 +1046,15 @@ export async function main(args = process.argv.slice(2), internal = {}) {
     codingModel: cfg.codingModel,
     efficiencyModel: cfg.efficiencyModel,
     modelsConfig,
+    modelCatalog,
+    // Warnings belong to this pass, just as they do in an isolated CLI run.
+    warnedCommandsDirs: new Set(),
     asAgentsMd: cfg.asAgentsMd,
-    createAgentsMd: cfg.createAgentsMd,
+    createAgentsMd: cfg.contextFiles && cfg.createAgentsMd,
+    contextFiles: cfg.contextFiles,
     deployCommands: cfg.kernelOnly ? false : cfg.deployCommands,
     deploySkills: cfg.kernelOnly ? true : cfg.deploySkills,
-    deployRules: cfg.kernelOnly ? false : cfg.deployRules,
+    deployRules: !cfg.deferRuleProjection && (cfg.kernelOnly || cfg.deployRules),
     deployBehaviors: cfg.kernelOnly ? false : cfg.deployBehaviors,
     commandsOnly: cfg.commandsOnly,
     skillsOnly: cfg.skillsOnly || cfg.kernelOnly,
@@ -1051,6 +1063,8 @@ export async function main(args = process.argv.slice(2), internal = {}) {
     reportOnly: cfg.reportOnly,
     allowOverBudget: cfg.allowOverBudget === true,
     kernelOnly: cfg.kernelOnly,
+    deferRuleProjection: cfg.deferRuleProjection,
+    additionalSources: cfg.additionalSources,
     filter: cfg.filter,
     filterRole: cfg.filterRole,
     save: cfg.save,
@@ -1070,17 +1084,23 @@ export async function main(args = process.argv.slice(2), internal = {}) {
     mcp: cfg.mcp === true,
     hooks: cfg.hooks !== false,
     listingBudget: cfg.listingBudget === true,
-    deployVersion: cfg.deployVersion || getDeployVersion(srcRoot),
+    deployVersion: resolveDeployVersion(resolveAiwgRoot(srcRoot) || srcRoot, cfg.deployVersion),
     deploySource: cfg.deploySource || 'bundled',
   };
-  const { isRuleDeploymentPreparationActive } = await import('./providers/rule-delivery.mjs');
-  const preparationActive = isRuleDeploymentPreparationActive();
+  if (provider.name === 'hermes' && cfg.projectScope && !cfg.userScope) {
+    throw new Error('Hermes does not support --scope project: skills are discovered only under HERMES_HOME/skills (default ~/.hermes/skills). Use --scope user or an isolated HERMES_HOME profile shared with Hermes.');
+  }
+  // Deferred kernel source passes must not load the projection dependency
+  // graph. Preparation still owns their staged deployment when a hook is active.
+  const preparationActive = cfg.kernelOnly && cfg.deferRuleProjection
+    ? Boolean(globalThis[Symbol.for('aiwg.provider-preparation-hook.v1')])
+    : (await import('./providers/rule-delivery.mjs')).isRuleDeploymentPreparationActive();
 
   // Commands → Skills migration: prompt then delete the commands directory
   // so stale command files don't create duplicates in the provider TUI.
   if (!preparationActive && !internal.finalizeOnly) {
     if (!cfg.dryRun && !cfg.skipCommandsMigration) {
-      const doMigrate = await promptCommandsMigration(cfg, provider, cfg.target);
+      const doMigrate = await promptCommandsMigration(cfg, provider, cfg.target, internal.capture ? false : process.stdout.isTTY);
       if (doMigrate) {
         const commandsRelPath = provider.paths?.commands;
         if (commandsRelPath) {
@@ -1106,7 +1126,13 @@ export async function main(args = process.argv.slice(2), internal = {}) {
 
   // Delegate to provider
   try {
-    if (!internal.finalizeOnly) await provider.deploy(opts);
+    if (!internal.finalizeOnly) {
+      if (cfg.kernelOnly && (!cfg.deferRuleProjection || preparationActive)
+        && !['claude', 'codex', 'cursor', 'hermes', 'warp', 'openclaw', 'pi', 'copilot', 'factory', 'opencode', 'windsurf', 'antigravity', 'muse', 'omp', 'grok-build'].includes(provider.name)) {
+        const { deployWithRuleDelivery } = await import('./providers/rule-delivery.mjs');
+        await deployWithRuleDelivery(opts, provider, staged => provider.deploy(staged));
+      } else await provider.deploy(opts);
+    }
     if (preparationActive) return;
 
     const mirroredCommandCount = mirrorSkillsAsCommands(provider, cfg.target, srcRoot, opts);
@@ -1138,11 +1164,13 @@ export async function main(args = process.argv.slice(2), internal = {}) {
     if (cfg.dryRun) {
       console.error('(dry-run mode - no files were modified)');
     }
-    process.exit(1);
+    return 1;
   }
+  return 0;
 }
 
 const invokedPath = process.argv[1] ? path.resolve(process.argv[1]) : null;
 if (invokedPath === fileURLToPath(import.meta.url)) {
-  await main();
+  try { process.exitCode = (await main()) ?? 0; }
+  catch (error) { console.error(error.message); process.exitCode = 1; }
 }

package/tools/agents/providers/antigravity.mjs

@@ -2,6 +2,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import {
+  withRuleDeployment,
   collectFrameworkArtifacts,
   createAgentsMdFromTemplate,
   deployFiles,
@@ -96,7 +97,7 @@ export async function postDeploy(target, opts) {
     throw new Error('Antigravity global skill deployment is disabled: official 1.1.26 path documentation conflicts');
   }
   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) {
     console.log('Antigravity resources are project scoped. Restart agy after resource changes; authenticate with the provider separately.');
@@ -106,6 +107,10 @@ export async function postDeploy(target, opts) {
 export function getFileExtension() { return '.md'; }
 
 export async function deploy(opts) {
+  return withRuleDeployment(opts, { name, paths, kernelSkillsPath }, deploySelected);
+}
+
+async function deploySelected(opts) {
   if (opts.global || opts.user || opts.scope === 'user') {
     throw new Error('Antigravity global skill deployment is disabled: official 1.1.26 path documentation conflicts');
   }

package/tools/agents/providers/base.mjs

@@ -17,10 +17,13 @@ import { createHash } from 'crypto';
 import { createRequire } from 'module';
 import { importImpl } from '../../_resolve-impl.mjs';
 
+import { writeContextFileSync } from './context-write.mjs';
+
 const { parseRuleFrontmatter, inferRuleActivation } = await importImpl(import.meta.url, 'rules/activation.mjs');
 const { resolveRulesInlineBudget, DEFAULT_RULES_INLINE_BUDGET_TOKENS } = await importImpl(import.meta.url, 'rules/inline-budget.mjs');
 export { DEFAULT_RULES_INLINE_BUDGET_TOKENS, parseRuleFrontmatter as parseRuleActivation };
 const { boundedExecFileSync } = await importImpl(import.meta.url, 'process/bounded-child-process.mjs');
+const { helperEnvironment } = await importImpl(import.meta.url, 'process/cli-command.mjs');
 const { extractFrameworkSlug, sameSkillOwner, canDeploySkill, pruneRecordedSkillFiles, releaseSkillOwnership } =
   await importImpl(import.meta.url, 'providers/skill-ownership.mjs');
 export { extractFrameworkSlug, sameSkillOwner, pruneRecordedSkillFiles, releaseSkillOwnership };
@@ -104,7 +107,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));
 }
 
@@ -1840,6 +1843,7 @@ export function buildRemotesTopologyBlock(targetDir) {
   function getUrl(remote) {
     try {
       return boundedExecFileSync('git', ['-C', targetDir, 'remote', 'get-url', '--', remote], 'quick', {
+        env: helperEnvironment(),
         stdio: ['ignore', 'pipe', 'ignore'],
         encoding: 'utf8',
       }).trim();
@@ -1949,7 +1953,7 @@ export function createManagedMdFromTemplate(target, destFilename, srcRoot, templ
     if (dryRun) {
       console.log(`[dry-run] Would ${verb} ${destFilename} AIWG-managed section`);
     } else {
-      fs.writeFileSync(destPath, content, 'utf8');
+      writeContextFileSync(destPath, content, 'utf8');
       console.log(`${verb[0].toUpperCase()}${verb.slice(1)} ${destFilename} AIWG-managed section`);
     }
   };
@@ -2474,7 +2478,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 +2562,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 +2592,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 +2609,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 +2807,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 +3174,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 +3345,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 +3354,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

@@ -1,3 +1,4 @@
+import { importImpl } from '../../_resolve-impl.mjs';
 /**
  * Claude Code Provider
  *
@@ -61,6 +62,8 @@ import {
   interpolateContextTokens
 } from './base.mjs';
 
+import { writeContextFileSync } from './context-write.mjs';
+
 // ============================================================================
 // Provider Configuration
 // ============================================================================
@@ -416,7 +419,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);
   }
 }
@@ -472,7 +475,7 @@ function deployHookFile(targetDir, opts) {
   } else {
     let content = fs.readFileSync(templatePath, 'utf8');
     content = interpolateHookTokens(content, effectiveCounts, targetDir);
-    fs.writeFileSync(hookDest, content, 'utf8');
+    writeContextFileSync(hookDest, content, 'utf8');
     console.log('Created AIWG.md (hook file)');
   }
 
@@ -496,7 +499,7 @@ function deployHookFile(targetDir, opts) {
           }
         }
         lines.splice(insertAt, 0, '', directive, '');
-        fs.writeFileSync(claudeDest, lines.join('\n'), 'utf8');
+        writeContextFileSync(claudeDest, lines.join('\n'), 'utf8');
         console.log('Added @AIWG.md directive to CLAUDE.md');
       }
     }