@aiwg/cli 2026.10.4 → 2026.10.6

package/tools/agents/providers/rule-delivery.mjs

@@ -1,4 +1,4 @@
-/** Activation-selected deployment, shared by the six provider projections (#2939). */
+/** Activation-selected deployment shared by provider projections. */
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
@@ -6,12 +6,14 @@ import { stringify } from 'yaml';
 import { createHash, randomUUID } from 'node:crypto';
 import { importImpl } from '../../_resolve-impl.mjs';
 import {
-  listMdFiles, discoverAddons, getFrameworksForMode, collectBehaviorDirs,
+  listMdFiles, listSkillDirs, getAddonSkillDirs, deploySkillsWithKernelRouting, isKernelSkill,
+  discoverAddons, getFrameworksForMode, collectBehaviorDirs,
   resolveAiwgRoot, ruleEnforcementLevel, stripTriggersFromContent,
   addManagedMarker, contentHash, replaceBoundRulesBlock, deployEmulatedBehaviors, filterAgentFiles,
 } from './base.mjs';
 
-const { parseRuleFrontmatter, inferRuleActivation, RULE_BINDING_TYPES } = await importImpl(import.meta.url, 'rules/activation.mjs');
+const { parseRuleFrontmatter, inferRuleActivation, RULE_BINDING_TYPES, readCoreBody, validateCoreSet, CORE_RULES_START, CORE_RULES_END } = await importImpl(import.meta.url, 'rules/activation.mjs');
+const { resolveDeployVersion } = await importImpl(import.meta.url, 'providers/deploy-version.mjs');
 const { trackTemporaryDirectory } = await importImpl(import.meta.url, 'utils/temporary-directory.js');
 const { loadRulePinConfigs, installedRuleCapabilities, resolveRulePins } = await importImpl(import.meta.url, 'rules/pins.mjs');
 const { guardRulesInlineBudget } = await importImpl(import.meta.url, 'rules/inline-budget.mjs');
@@ -65,15 +67,62 @@ function promoteDirectories(source, destination, skip = () => false, prefix = ''
 }
 const read = file => fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
 const structural = file => /^(RULES-INDEX|RULES-ONDEMAND)\.(md|mdc)$/.test(path.basename(file));
+// Verified startup owners from provider-definitions.ts. These providers do not
+// need a prose fetch of AIWG.md to activate their compact core contracts.
+const inlineStartup = {
+  copilot: '.github/copilot-instructions.md', factory: 'AGENTS.md', opencode: 'AGENTS.md',
+  windsurf: 'AGENTS.md', antigravity: 'AGENTS.md', muse: 'AGENTS.md',
+  omp: '.omp/AGENTS.md', 'grok-build': 'AGENTS.md',
+};
 
 /** Collect selected source contracts, before any tier filter or projection. */
 export function collectDeploymentRuleSources(opts) {
-  if (opts.ruleSources) return [...new Set([...opts.ruleSources, ...(opts.previousRuleSources || []).filter(file => fs.existsSync(file))])];
-  const roots = [opts.srcRoot];
-  for (const framework of getFrameworksForMode(opts.srcRoot, opts.mode)) roots.push(framework.path);
-  for (const addon of discoverAddons(opts.srcRoot)) roots.push(addon.path);
-  const files = [...(opts.previousRuleSources || []).filter(file => fs.existsSync(file)), ...roots.flatMap(root => listMdFiles(path.join(root, 'rules')))].filter(file => !structural(file));
-  const behaviors = collectBehaviorDirs(opts.srcRoot).map(dir => path.join(dir, 'BEHAVIOR.md'));
+  if (opts.ruleSources) {
+    // Pin-only callers enumerate rule files separately from behavior contracts.
+    // Retain earlier behaviors only while their owning bundle is still selected.
+    const selected = new Set(collectDeploymentRuleSources({ ...opts, ruleSources: undefined }));
+    const behaviors = (opts.previousRuleSources || []).filter(file => path.basename(file) === 'BEHAVIOR.md' && selected.has(file));
+    return [...new Set([...opts.ruleSources, ...behaviors])];
+  }
+  const corpus = resolveAiwgRoot(opts.srcRoot) || opts.srcRoot;
+  const bundles = [];
+  const frameworks = getFrameworksForMode(corpus, 'all');
+  for (const kind of ['frameworks', 'addons', 'extensions', 'plugins']) {
+    const dir = path.join(corpus, 'agentic', 'code', kind);
+    if (!fs.existsSync(dir)) continue;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const root = path.join(dir, entry.name);
+      const manifest = JSON.parse(read(path.join(root, 'manifest.json')) || '{}');
+      bundles.push({ root, manifest, id: manifest.id || manifest.framework || entry.name,
+        aliases: [entry.name, ...(manifest.modeAliases || []), ...(manifest.aliases || []),
+          ...(kind === 'frameworks' ? frameworks.find(framework => framework.path === root)?.aliases || [] : [])] });
+    }
+  }
+  const configs = opts.pinConfigs || loadRulePinConfigs(opts.target, opts.config);
+  // Project installation is authoritative. User-wide discoverability is not a
+  // project install, and a previous projection must never reselect retired rules.
+  const installed = configs.project.installed || {};
+  const names = Array.isArray(installed) ? installed : Object.keys(installed);
+  const selected = new Set();
+  const select = name => {
+    const id = name.replace(/^(framework|addon|extension|plugin):/, '');
+    const bundle = bundles.find(b => b.id === id || b.aliases.includes(id));
+    if (!bundle || selected.has(bundle)) return;
+    selected.add(bundle);
+    const required = Array.isArray(bundle.manifest.dependencies) ? bundle.manifest.dependencies : bundle.manifest.dependencies?.required || [];
+    for (const dep of Array.isArray(required) ? required : Object.keys(required)) select(dep);
+  };
+  for (const bundle of bundles.filter(b => b.manifest.core && b.manifest.autoInstall)) select(bundle.id);
+  for (const name of names.filter(name => name !== 'all')) select(name);
+  const invoked = bundles.find(bundle => path.resolve(bundle.root) === path.resolve(opts.srcRoot));
+  if (invoked && !opts.kernelOnly) select(invoked.id);
+  // Include the invocation being installed before its config entry is saved.
+  if (!opts.kernelOnly) for (const framework of getFrameworksForMode(opts.srcRoot, opts.mode === 'all' && names.length ? 'general' : opts.mode)) select(framework.id);
+  const roots = [...(!invoked || !opts.kernelOnly ? [opts.srcRoot] : []), ...(opts.additionalSources || []), ...[...selected].map(bundle => bundle.root)];
+  for (const entry of Object.values(installed)) if (entry?.localPath) roots.push(path.resolve(opts.target, entry.localPath));
+  const files = roots.flatMap(root => listMdFiles(path.join(root, 'rules'))).filter(file => !structural(file));
+  const behaviors = roots.flatMap(root => walk(path.join(root, 'behaviors')).filter(file => path.basename(file) === 'BEHAVIOR.md'));
   return [...new Set([...files, ...behaviors])];
 }
 
@@ -85,12 +134,16 @@ export async function prepareRuleDelivery(opts) {
     const behavior = path.basename(file) === 'BEHAVIOR.md';
     const rule = { ...parsed.rule, file, content, body: parsed.body, behavior,
       name: behavior ? `behavior/${path.basename(path.dirname(file))}` : parsed.data.name || path.basename(file, '.md') };
-    if (!rule.tagged) rule.activation = behavior ? 'kernel' : inferRuleActivation(ruleEnforcementLevel(content));
+    if (!rule.tagged) rule.activation = inferRuleActivation();
+    // Core rules (#3450) carry a compact body beside the full rule; the full text is never inlined.
+    if (rule.activation === 'core') rule.coreBody = readCoreBody(file);
     for (const diagnostic of parsed.diagnostics) {
-      console.warn(`${opts.logicalInputPath ? opts.logicalInputPath(file) : file}: ${diagnostic.code}: ${diagnostic.code === 'missing-activation' ? `Missing activation; inferred ${rule.activation} delivery (migration fallback).` : diagnostic.message}`);
+      console.warn(`${opts.logicalInputPath ? opts.logicalInputPath(file) : file}: ${diagnostic.code}: ${diagnostic.code === 'missing-activation' ? `Missing activation; inferred ${rule.activation} delivery (migration fallback); add explicit activation frontmatter.` : diagnostic.message}`);
     }
     return rule;
   });
+  const coreErrors = validateCoreSet([...new Map(rules.filter(rule => rule.coreBody !== undefined).map(rule => [rule.name, { name: rule.name, text: rule.coreBody }])).values()]);
+  if (coreErrors.length) throw new Error(coreErrors.join('; '));
   const configs = opts.pinConfigs || loadRulePinConfigs(opts.target, opts.config);
   const installed = installedRuleCapabilities(configs);
   const root = resolveAiwgRoot(opts.srcRoot) || opts.srcRoot;
@@ -110,7 +163,8 @@ export async function prepareRuleDelivery(opts) {
   const pinsByFile = new Map(pinned.rules.map(rule => [rule.file, rule]));
   for (const rule of rules) {
     const pin = pinsByFile.get(rule.file);
-    if (!pin) continue;
+    // A core rule is already delivered in full; a pin must not re-promote it to a kernel body.
+    if (!pin || rule.activation === 'core') continue;
     rule.canonicalActivation = rule.activation;
     rule.pinMatches = pin.matches;
     rule.pinned = true;
@@ -148,22 +202,19 @@ export async function prepareRuleDelivery(opts) {
           if (error.code !== 'ENOENT' && !(error instanceof SyntaxError)) throw error;
         }
       }
-      const indexTemp = fs.mkdtempSync(path.join(os.tmpdir(), 'aiwg-rule-index-'));
-      try {
-        const { buildIndex } = await importImpl(import.meta.url, 'artifacts/index-builder.js');
-        await buildIndex(root, { scope: root === opts.srcRoot && !fs.existsSync(path.join(root, 'agentic')) ? '.' : 'agentic/code', outputDir: indexTemp, force: true, quiet: true });
-        rebuilt = true;
-        const index = JSON.parse(read(path.join(indexTemp, '.aiwg', '.index', 'metadata.json')));
-        const entries = Object.values(index.entries).map(entry => ({ ...entry, path: path.resolve(root, entry.path) }));
-        if (cacheFile) {
-          fs.mkdirSync(cacheDir, { recursive: true });
-          // Workers may publish the same immutable source snapshot concurrently.
-          const temporary = `${cacheFile}.${process.pid}.tmp`;
-          fs.writeFileSync(temporary, JSON.stringify(entries.map(entry => ({ ...entry, path: opts.logicalInputPath ? opts.logicalInputPath(entry.path) : entry.path }))));
-          fs.renameSync(temporary, cacheFile);
-        }
-        return entries;
-      } finally { fs.rmSync(indexTemp, { recursive: true, force: true }); }
+      const { collectRuleBindingEntries } = await importImpl(import.meta.url, 'artifacts/index-builder.js');
+      const sourceEntries = await collectRuleBindingEntries(root,
+        root === opts.srcRoot && !fs.existsSync(path.join(root, 'agentic')) ? '.' : 'agentic/code');
+      rebuilt = true;
+      const entries = sourceEntries.map(entry => ({ ...entry, path: path.resolve(root, entry.path) }));
+      if (cacheFile) {
+        fs.mkdirSync(cacheDir, { recursive: true });
+        // Workers may publish the same immutable source snapshot concurrently.
+        const temporary = `${cacheFile}.${process.pid}.tmp`;
+        fs.writeFileSync(temporary, JSON.stringify(entries.map(entry => ({ ...entry, path: opts.logicalInputPath ? opts.logicalInputPath(entry.path) : entry.path }))));
+        fs.renameSync(temporary, cacheFile);
+      }
+      return entries;
     };
     const localEntries = opts.bindingEntries || loadEntries(opts.target, Boolean(packageRelations));
     let entries = [...localEntries];
@@ -244,20 +295,22 @@ export async function prepareRuleDelivery(opts) {
 
 export function renderRuleKernelIndex(rules, nativePaths = false) {
   const summary = rules.filter(rule => rule.tagged && (rule.canonicalActivation || rule.activation) === 'summary');
-  const paths = nativePaths ? [] : rules.filter(rule => rule.tagged && (rule.canonicalActivation || rule.activation) === 'paths');
-  if (!summary.length && !paths.length) return '';
+  const paths = rules.filter(rule => rule.tagged && (rule.canonicalActivation || rule.activation) === 'paths');
+  const kernels = rules.filter(rule => rule.tagged && (rule.canonicalActivation || rule.activation) === 'kernel');
+  if (!summary.length && !paths.length && !kernels.length) return '';
   const lines = ['# Rule kernel index', ''];
-  for (const rule of summary) lines.push(`- ${rule.name} — ${rule.summary} Fetch and follow: \`aiwg show rule ${rule.name}\`.`, '');
+  for (const rule of kernels) lines.push(`- ${rule.name} — ${rule.summary || 'Fetch and follow the full rule before governed work.'} Fetch and follow: \`aiwg show rule ${rule.name} --body\`.`, '');
+  for (const rule of summary) lines.push(`- ${rule.name} — ${rule.summary} Fetch and follow: \`aiwg show rule ${rule.name} --body\`.`, '');
   if (paths.length) {
-    lines.push('## Path rules (prompt emulation)', '',
-      'Before reading or changing files, compare intended project-relative paths with the globs below and fetch matching rules before their first read/write. If paths are initially unknown, check when they become known. An agent-only task has no path match. This is prompt emulation, not a filesystem hook.', '');
-    for (const rule of paths) lines.push(`- ${rule.name} | ${rule.paths.map(glob => `\`${glob}\``).join(', ')} | ${rule.summary} | \`aiwg show rule ${rule.name}\``, '');
+    lines.push(nativePaths ? '## Path rules (native)' : '## Path rules (prompt emulation)', '',
+      nativePaths ? 'The provider loads these rules for matching paths; full contracts remain available through the commands below.' : 'Before reading or changing files, compare intended project-relative paths with the globs below and fetch matching rules before their first read/write. If paths are initially unknown, check when they become known. An agent-only task has no path match. This is prompt emulation, not a filesystem hook.', '');
+    for (const rule of paths) lines.push(`- ${rule.name} | ${rule.paths.map(glob => `\`${glob}\``).join(', ')} | ${rule.summary} | \`aiwg show rule ${rule.name} --body\``, '');
   }
   return lines.join('\n');
 }
 
 function managed(content, opts) {
-  return addManagedMarker(content, opts.deployVersion || 'unknown', opts.deploySource || 'bundled');
+  return addManagedMarker(content, opts.deployVersion, opts.deploySource || 'bundled');
 }
 function put(file, content) {
   fs.mkdirSync(path.dirname(file), { recursive: true });
@@ -277,6 +330,15 @@ function putStartup(file, body) {
 /** Tagged rules bypass legacy aggregate writers. Untagged projections retain their tier policy. */
 function projectRules(opts, provider) {
   const { rules } = opts.ruleDelivery;
+  if (opts.contextFiles !== false && provider.name === 'hermes') {
+    // The old context generator carries hardcoded corpus directives. Only the
+    // selected contracts below may activate policy; preserve operator prose.
+    const file = path.join(opts.target, 'AGENTS.md');
+    const content = read(file);
+    const clean = content.replace(/(<!-- AIWG:hermes-context:start -->)([\s\S]*?)(<!-- AIWG:hermes-context:end -->)/g,
+      (_, start, body, end) => start + body.replace(/^### Rule: [\s\S]*?(?=^#{1,3} |(?![\s\S]))/gm, '') + end);
+    if (clean !== content) put(file, clean);
+  }
   const nativePaths = ['claude', 'cursor'].includes(provider.name);
   const rulesDir = path.isAbsolute(provider.paths.rules || '') ? provider.paths.rules : path.join(opts.target, provider.paths.rules || `.${provider.name}/rules`);
   const tagged = rules.filter(rule => rule.tagged);
@@ -285,9 +347,14 @@ function projectRules(opts, provider) {
     const name = rule.behavior ? `behaviors/${path.basename(path.dirname(rule.file))}` : path.basename(rule.file, '.md');
     put(path.join(rulesDir, `${name}${extension}`), managed(content, opts));
   };
+  // Legacy projectors may have enumerated the whole corpus. Rebuild managed
+  // rule output from the canonical selection; preserve operator-owned files.
+  for (const file of walk(rulesDir)) {
+    if (/\.(md|mdc)$/.test(file) && /aiwg:managed/.test(read(file))) fs.rmSync(file);
+  }
   const priorManifestPath = path.join(rulesDir, '.aiwg-manifest.json');
   const priorSources = fs.existsSync(priorManifestPath) ? JSON.parse(read(priorManifestPath)).ruleSources || [] : [];
-  for (const source of priorSources.filter(file => !fs.existsSync(file))) {
+  for (const source of priorSources.filter(file => !rules.some(rule => rule.file === file))) {
     const name = path.basename(source) === 'BEHAVIOR.md' ? `behaviors/${path.basename(path.dirname(source))}` : path.basename(source, '.md');
     for (const ext of ['.md', '.mdc']) {
       const stale = path.join(rulesDir, name + ext);
@@ -302,6 +369,26 @@ function projectRules(opts, provider) {
       if (/aiwg:managed/.test(read(dest))) fs.rmSync(dest);
     }
   }
+  // Core rules (#3450): compact bodies in the provider's always-loaded surface,
+  // independent of deploy mode. Native providers get one core-<name> file each;
+  // the others get a marked section first in their managed startup block.
+  const cores = [...new Map(tagged.filter(rule => rule.activation === 'core').map(rule => [rule.name, rule])).values()];
+  if (fs.existsSync(rulesDir)) {
+    for (const entry of fs.readdirSync(rulesDir).filter(name => /^core-.+\.(md|mdc)$/.test(name))) {
+      if (/aiwg:managed/.test(read(path.join(rulesDir, entry)))) fs.rmSync(path.join(rulesDir, entry));
+    }
+  }
+  if (nativePaths) {
+    for (const rule of cores) {
+      const body = provider.name === 'cursor' ? `---\nalwaysApply: true\n---\n${rule.coreBody}\n` : `${rule.coreBody}\n`;
+      const dest = path.join(rulesDir, `core-${path.basename(rule.file, '.md')}${extension}`);
+      if (fs.existsSync(dest) && !/aiwg:managed/.test(read(dest)) && !opts.force) {
+        console.warn(`Unmanaged core rule left in place: ${dest}. Re-run with --force to replace it.`);
+        continue;
+      }
+      put(dest, managed(body, opts));
+    }
+  }
   for (const rule of tagged) {
     if (rule.activation === 'kernel' || (nativePaths && rule.activation === 'paths')) {
       let content = stripTriggersFromContent(rule.content);
@@ -316,6 +403,16 @@ function projectRules(opts, provider) {
       writeRule(rule, content);
     }
   }
+  // Explicit local/external bundle deployments predate activation metadata.
+  // Keep their native rule files reachable while they migrate; missing metadata
+  // in the shipped corpus still uses the on-demand fallback (#3463).
+  for (const rule of rules.filter(rule => !rule.tagged && !rule.behavior)) {
+    const source = opts.logicalInputPath ? opts.logicalInputPath(rule.file) : rule.file;
+    if (/(?:^|\/)agentic\/code\//.test(source.replaceAll('\\', '/'))) continue;
+    let content = stripTriggersFromContent(rule.content);
+    if (provider.name === 'cursor') content = provider.transformRule(rule.file, content, opts);
+    writeRule(rule, content);
+  }
   // A legacy consolidated index can mention now-bound rules. Replace it with an
   // activation-selected index when migration starts; pure legacy deployments keep it.
   // Hermes's 20K context limit requires a fixed provider projection: only
@@ -325,8 +422,7 @@ function projectRules(opts, provider) {
   const isCritical = rule => String(rule.enforcement || '').trim().toLowerCase() === 'critical';
   const deferredKernels = provider.name === 'hermes'
     ? rules.filter(rule => rule.tagged && rule.activation === 'kernel' && !rule.pinned && !isCritical(rule)) : [];
-  const indexRules = deferredKernels.length ? rules.map(rule => deferredKernels.includes(rule)
-    ? { ...rule, activation: 'summary', summary: rule.summary || 'Fetch and follow the full rule before governed work.' } : rule) : rules;
+  const indexRules = rules;
   const index = renderRuleKernelIndex(indexRules, nativePaths);
   if (tagged.length) {
     for (const ext of ['.md', '.mdc']) {
@@ -335,6 +431,11 @@ function projectRules(opts, provider) {
     }
     if (index) put(path.join(rulesDir, `RULES-INDEX${extension}`), managed(provider.name === 'cursor' ? `---\nalwaysApply: true\n---\n${index}` : index, opts));
   }
+  const legacyDemand = rules.filter(rule => !rule.tagged && !rule.behavior && rule.activation === 'on-demand');
+  if (legacyDemand.length) put(path.join(rulesDir, `RULES-ONDEMAND${extension}`), managed([
+    '# On-demand rules', '', 'These rules require explicit activation metadata. Fetch the applicable full rule before governed work.', '',
+    ...legacyDemand.map(rule => `- \`${rule.name}\` — \`aiwg show rule ${rule.name} --body\``), '',
+  ].join('\n'), opts));
   fs.rmSync(path.join(rulesDir, '.aiwg-rules-budget.json'), { force: true });
   const manifestPath = path.join(rulesDir, '.aiwg-manifest.json');
   const manifest = fs.existsSync(manifestPath) ? JSON.parse(read(manifestPath)) : { managed: {} };
@@ -345,7 +446,7 @@ function projectRules(opts, provider) {
   }
   for (const name of Object.keys(manifest.managed)) if (!fs.existsSync(path.join(rulesDir, name))) delete manifest.managed[name];
   put(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
-  if (!nativePaths) {
+  if (!nativePaths && opts.contextFiles !== false) {
     // The conventional directory is not a loader: startup reaches the complete
     // selected bodies through the provider's existing context owner.
     const kernels = rules.filter(rule => rule.activation === 'kernel' &&
@@ -354,8 +455,9 @@ function projectRules(opts, provider) {
     const routing = routes.length ? `## Invoked artifact definitions\n\nRead the complete definition before invoking its artifact:\n${routes.map(route => `- ${route}`).join('\n')}` : '';
     let startupIndex = index;
     let startupRouting = routing;
-    const fetchKernels = deferredKernels.length ? 'Before every task and subagent task, fetch and follow the kernel rules listed below with `aiwg show rule <name>` before governed work. Their full rules are binding.' : '';
-    const renderBody = () => [...kernels.map(rule => `## Rule: ${rule.name}\n\n${rule.body.trim()}`), fetchKernels, startupIndex, startupRouting].filter(Boolean).join('\n\n');
+    const fetchKernels = deferredKernels.length ? 'Before every task and subagent task, fetch and follow the kernel rules listed below with `aiwg show rule <name> --body` before governed work. Their full rules are binding.' : '';
+    const coreSection = cores.length ? `${CORE_RULES_START}\n## Core rules\n\n${cores.map(rule => rule.coreBody).join('\n\n')}\n${CORE_RULES_END}` : '';
+    const renderBody = () => [coreSection, ...kernels.map(rule => `## Rule: ${rule.name}\n\n${rule.body.trim()}`), fetchKernels, startupIndex, startupRouting].filter(Boolean).join('\n\n');
     const dest = path.join(opts.target, 'AGENTS.md');
     if (provider.name === 'hermes' && block(read(dest), renderBody()).length > 19_000) {
       // The complete summary/path index and definition routes can themselves
@@ -379,7 +481,7 @@ function projectRules(opts, provider) {
     if (!body) {
       // No activation-selected startup contract: retain legacy context owners
       // without inventing an empty policy file or a dangling bootstrap read.
-      const contexts = ['AIWG.md', 'AGENTS.md', 'WARP.md', '.hermes.md'].map(name => path.join(opts.target, name));
+      const contexts = ['AIWG.md', 'AGENTS.md', 'WARP.md', '.hermes.md', inlineStartup[provider.name]].filter(Boolean).map(name => path.join(opts.target, name));
       if (opts.activeWorkspace) contexts.push(path.join(opts.activeWorkspace, 'AGENTS.md'));
       for (const file of contexts) {
         if (!fs.existsSync(file)) continue;
@@ -389,7 +491,12 @@ function projectRules(opts, provider) {
       }
       return;
     }
-    if (provider.name === 'hermes') {
+    if (inlineStartup[provider.name]) {
+      // Retire the B1 indirect startup block when migrating to the actual loader.
+      const former = path.join(opts.target, 'AIWG.md');
+      if (fs.existsSync(former)) put(former, block(read(former), ''));
+      putStartup(path.join(opts.target, inlineStartup[provider.name]), body);
+    } else if (provider.name === 'hermes') {
       const dest = path.join(opts.target, 'AGENTS.md');
       putStartup(dest, body);
       putStartup(path.join(opts.target, '.hermes.md'), 'Read and follow `AGENTS.md` in this directory before every task and subagent task.');
@@ -407,14 +514,19 @@ function projectRules(opts, provider) {
 
 /** External helpers also project skills/flows. Inject into their body, never descriptions. */
 function finishBindings(opts, provider) {
-  const roots = [opts.target, opts.deploymentHome, ...Object.values(provider.paths).filter(p => path.isAbsolute(p))];
+  const roots = [opts.target, opts.deploymentHome,
+    ...[opts.kernelSkillsPath, opts.activeWorkspace, ...Object.values(provider.paths)].filter(p => p && path.isAbsolute(p))];
   const files = [...new Set(roots.flatMap(walk))];
+  const indexRel = provider.name === 'copilot' ? '.github/RULES-BOUND.md' : `.${provider.name}/RULES-BOUND.md`;
+  const indexFile = path.join(opts.target, indexRel);
+  const anchor = target => `${target.type}-${target.name}`.toLowerCase().replace(/[^a-z0-9_-]/g, '-');
+  const sections = new Map();
   const targetsBySource = new Map();
   for (const target of opts.ruleDelivery.targets) {
     targetsBySource.set(target.source, [...(targetsBySource.get(target.source) || []), target]);
   }
   for (const file of files.filter(file => /\.(md|toml)$/.test(file))) {
-    if (!/(?:[/\\](?:skills|agents|commands)[/\\])/.test(file)) continue;
+    if (path.basename(file) !== 'SKILL.md' && !/(?:[/\\](?:skills?|agents?|droids|commands?|prompts|modes?)[/\\])/.test(file)) continue;
     if (/[/\\]rules[/\\]/.test(file) || /[/\\]\.aiwg[/\\](?!skills[/\\])/.test(file.replace(opts.target, ''))) continue;
     let content = read(file);
     if (!/aiwg:managed/.test(content) && !fs.existsSync(path.join(path.dirname(file), '.aiwg-managed')) && !fs.existsSync(path.join(path.dirname(file), '.aiwg-manifest.json'))) continue;
@@ -426,12 +538,30 @@ function finishBindings(opts, provider) {
     const flowSource = opts.flowSkillSources?.get(file);
     const targets = [...(flowSource ? targetsBySource.get(flowSource) || [] : []),
       ...(source ? targetsBySource.get(path.resolve(source)) || [] : opts.ruleDelivery.targets.filter(target =>
-        (skill ? target.type !== 'agent' : file.includes('/agents/') ? target.type === 'agent' : target.type === 'flow') &&
+        (skill ? target.type !== 'agent' : /[/\\](?:agents?|droids|modes?)[/\\]/.test(file) ? target.type === 'agent' : target.type === 'flow') &&
         [target.name, path.basename(target.source, '.md'), path.basename(path.dirname(target.source))].includes(name)))];
     const rules = targets.flatMap(target => opts.ruleDelivery.bindings.get(target.source) || []);
     if (!rules.length && !content.includes('<!-- AIWG:bound-rules:start -->')) continue;
-    if (file.endsWith('.toml')) content = content.replace(/^developer_instructions = (".*")$/m, (_, value) => `developer_instructions = ${JSON.stringify(replaceBoundRulesBlock(JSON.parse(value), rules))}`);
-    else content = replaceBoundRulesBlock(content, rules);
+    const pointer = body => {
+      const clean = replaceBoundRulesBlock(body, []);
+      if (!rules.length) return clean;
+      const identities = [...new Map(targets.map(target => [`${target.type} ${target.name}`, target])).values()];
+      for (const target of identities) {
+        const bound = opts.ruleDelivery.bindings.get(target.source) || [];
+        const unique = [...new Map(bound.map(rule => [rule.name, rule])).values()].sort((a, b) => a.name.localeCompare(b.name));
+        if (unique.length) sections.set(anchor(target), `## ${anchor(target)}\n\n` + unique.map(rule =>
+          `- ${rule.name} — ${rule.summary} Fetch and follow: \`aiwg show rule ${rule.name} --body\`.`).join('\n'));
+      }
+      // Skills must carry exact fetch commands themselves: a section pointer
+      // alone loses the invocation contract in clean installs (#3473).
+      const fetch = skill ? [...new Map(rules.map(rule => [rule.name, rule])).values()]
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map(rule => `${rule.summary}\nFetch and follow before governed work: \`aiwg show rule ${rule.name} --body\`.`).join('\n') : '';
+      return `${clean}${clean.endsWith('\n') ? '' : '\n'}\n<!-- AIWG:bound-rules:start -->\nRead and follow before governed work: ${identities.map(target =>
+        `\`${indexRel}#${anchor(target)}\``).join('; ')}.\n${fetch ? fetch + '\n' : ''}<!-- AIWG:bound-rules:end -->\n`;
+    };
+    if (file.endsWith('.toml')) content = content.replace(/^developer_instructions = (".*")$/m, (_, value) => `developer_instructions = ${JSON.stringify(pointer(JSON.parse(value)))}`);
+    else content = pointer(content);
     put(file, content);
     // Keep deployment hashes honest after projection by external helpers.
     if (sidecar?.managed?.[path.basename(file)]) {
@@ -439,6 +569,10 @@ function finishBindings(opts, provider) {
       put(sidecarPath, `${JSON.stringify(sidecar, null, 2)}\n`);
     }
   }
+  if (sections.size) put(indexFile, managed('# Bound rules\n\nFetch and follow every full rule in the invoked artifact’s section before governed work.\n\n' +
+    [...sections.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([, section]) => section).join('\n\n') + '\n', opts));
+  else if (/aiwg:managed/.test(read(indexFile))) fs.rmSync(indexFile);
+
 }
 
 /** Bindings annotate the selected deployment; they do not select standard skills
@@ -490,7 +624,8 @@ function projectBoundFlowSkills(opts, provider, selected) {
     if (!fs.existsSync(file) || receipt?.flowSource === entry.source) {
       const body = read(entry.source);
       const markdown = entry.source.endsWith('.md') ? body : `---\nname: ${name}\nnamespace: aiwg\ndescription: Invoke ${name}.\n---\n\n\`\`\`yaml\n${body}\n\`\`\`\n`;
-      const content = managed(replaceBoundRulesBlock(markdown, opts.ruleDelivery.bindings.get(entry.source)), opts);
+      const projected = provider.transformSkillMd ? provider.transformSkillMd(markdown, opts) : markdown;
+      const content = managed(replaceBoundRulesBlock(projected, opts.ruleDelivery.bindings.get(entry.source)), opts);
       put(file, content);
       put(path.join(dir, '.aiwg-managed'), 'true\n');
       put(receiptFile, `${JSON.stringify({ flowSource: entry.source,
@@ -512,7 +647,7 @@ export function warpRuleContent(content) {
 
 function startupFiles(opts, provider) {
   const bridgeNames = { claude: ['CLAUDE.md'], cursor: ['AGENTS.md'], codex: ['AGENTS.md'], hermes: ['AGENTS.md', '.hermes.md'], pi: ['AGENTS.md'], warp: ['WARP.md'], openclaw: [] };
-  const paths = ['AIWG.md', 'WORKSPACE.md', '.aiwg/AIWG.md', ...bridgeNames[provider.name]].map(name => path.join(opts.target, name));
+  const paths = ['AIWG.md', 'WORKSPACE.md', '.aiwg/AIWG.md', ...(bridgeNames[provider.name] || ['AGENTS.md']), inlineStartup[provider.name]].filter(Boolean).map(name => path.join(opts.target, name));
   if (opts.activeWorkspace) paths.push(path.join(opts.activeWorkspace, 'AGENTS.md'));
   if (['claude', 'cursor', 'openclaw'].includes(provider.name)) {
     const dir = path.isAbsolute(provider.paths.rules) ? provider.paths.rules : path.join(opts.target, provider.paths.rules);
@@ -524,10 +659,11 @@ function startupFiles(opts, provider) {
       const parsed = parseRuleFrontmatter(content);
       if (parsed.data?.paths || parsed.data?.globs) content = content.slice(0, content.length - parsed.body.length);
     }
-    // WARP.md aggregates agents and commands as well; only its rule content
-    // (managed startup blocks, legacy inline rules, and on-demand lists) counts
-    // toward the rules startup budget.
-    if (provider.name === 'warp' && path.basename(file) === 'WARP.md') content = warpRuleContent(content);
+    // WARP.md and Windsurf's AGENTS.md aggregate agents (and Warp's commands)
+    // as well; only their rule content (managed startup blocks, legacy inline
+    // rules, and on-demand lists) counts toward the rules startup budget.
+    if ((provider.name === 'warp' && path.basename(file) === 'WARP.md')
+      || (provider.name === 'windsurf' && file === path.join(opts.target, 'AGENTS.md'))) content = warpRuleContent(content);
     return { path: file, content };
   });
 }
@@ -562,17 +698,23 @@ function capturePreimage(file, ancestors = new Set()) {
 }
 // cpSync materializes links; compare its output with the recursively resolved
 // content while retaining the original link-shaped preimage for commit drift.
-function materializeInput(from, to, ancestors = new Set()) {
-  if (!fs.existsSync(from)) return;
-  const real = fs.realpathSync(from);
-  if (ancestors.has(real)) throw new Error(`Cyclic deployment input: ${from}`);
-  const stat = fs.statSync(from);
+function materializeInput(from, to, ancestors = new Set(), parentReady = false) {
+  let stat;
+  try { stat = fs.statSync(from); } catch (error) {
+    if (error.code === 'ENOENT') return;
+    throw error;
+  }
   if (stat.isDirectory()) {
+    // Only directories can lead back to an ancestor. Resolve them once and
+    // share the immutable ancestry set with their children, including aliases.
+    const real = fs.realpathSync(from);
+    if (ancestors.has(real)) throw new Error(`Cyclic deployment input: ${from}`);
+    const children = new Set([...ancestors, real]);
     fs.mkdirSync(to, { recursive: true });
-    for (const name of fs.readdirSync(from)) materializeInput(path.join(from, name), path.join(to, name), new Set([...ancestors, real]));
+    for (const name of fs.readdirSync(from)) materializeInput(path.join(from, name), path.join(to, name), children, true);
     fs.chmodSync(to, stat.mode & 0o7777);
   } else if (stat.isFile()) {
-    fs.mkdirSync(path.dirname(to), { recursive: true });
+    if (!parentReady) fs.mkdirSync(path.dirname(to), { recursive: true });
     fs.copyFileSync(from, to); fs.chmodSync(to, stat.mode & 0o7777);
   } else throw new Error(`Unsupported deployment input: ${from}`);
 }
@@ -828,6 +970,9 @@ export async function prepareRuleDeployment(original, provider, deploy) {
   const previousText = fs.existsSync(manifestFile) ? read(manifestFile) : '';
   const previous = previousText ? JSON.parse(previousText) : {};
   const corpusRoot = resolveAiwgRoot(original.srcRoot) || original.srcRoot;
+  if (!original.deployVersion || /unknown/i.test(original.deployVersion)) {
+    original = { ...original, deployVersion: resolveDeployVersion(corpusRoot, original.deployVersion) };
+  }
   const sourceTree = fs.existsSync(path.join(corpusRoot, 'agentic', 'code'))
     ? path.join(corpusRoot, 'agentic', 'code') : original.srcRoot;
   const pool = original.inputPool && inputPools.get(original.inputPool);
@@ -846,7 +991,7 @@ export async function prepareRuleDeployment(original, provider, deploy) {
   const selectedRules = collectDeploymentRuleSources({ ...original, previousRuleSources: previous.ruleSources || [] });
   const initialPreimages = [...(pool ? pool.preimages : snapshotPreimages([sourceTree, path.join(corpusRoot, 'prebuilt', 'framework-relations'), path.join(corpusRoot, 'package.json'), path.join(corpusRoot, 'schemas')])), ...snapshotPreimages([path.join(corpusRoot, '.aiwg', '.index'),
     manifestFile, path.join(original.target, '.aiwg', 'aiwg.config'), path.join(original.target, '.aiwg', 'AIWG.md'), path.join(original.target, '.aiwg', 'skills'), path.join(original.target, '.aiwg-location'), ...projectGraphFiles, ...userGraphFiles, ...localSources,
-    ...(path.resolve(original.srcRoot) === path.resolve(corpusRoot) ? [] : [original.srcRoot]), ...selectedRules, ...selectedRules.map(file => path.dirname(file)),
+    ...(path.resolve(original.srcRoot) === path.resolve(corpusRoot) ? [] : [original.srcRoot]), ...(original.additionalSources || []), ...selectedRules, ...selectedRules.map(file => path.dirname(file)),
     userConfigFile('aiwg.config'), process.env.AIWG_USER_REGISTRY_PATH || userConfigFile('installed.json'),
     ...(original.ruleSources || []), ...(previous.ruleSources || []), ...(original.bindingEntries || []).map(entry => entry.path)])];
   let manifestState = initialPreimages.find(item => item.path === path.resolve(manifestFile)).state;
@@ -928,7 +1073,7 @@ export async function prepareRuleDeployment(original, provider, deploy) {
       if (JSON.stringify(capturePreimage(to)) !== JSON.stringify(materializedPreimage(expected || { kind: 'missing' }))) throw new Error(`Project-local input changed while preparing snapshot: ${from}`);
       sourceMappings.push({ from, to });
     }
-    const externalInputs = [...new Set([...(path.resolve(original.srcRoot) === path.resolve(corpusRoot) ? [] : [original.srcRoot]), ...(original.ruleSources || []), ...(previous.ruleSources || []),
+    const externalInputs = [...new Set([...(path.resolve(original.srcRoot) === path.resolve(corpusRoot) ? [] : [original.srcRoot]), ...(original.additionalSources || []), ...(original.ruleSources || []), ...(previous.ruleSources || []),
       ...(original.bindingEntries || []).map(entry => entry.path)].map(file => path.resolve(file)))];
     for (const [index, from] of externalInputs.entries()) {
       if (sourceMappings.some(item => from === item.from || from.startsWith(`${item.from}${path.sep}`))) continue;
@@ -963,6 +1108,7 @@ export async function prepareRuleDeployment(original, provider, deploy) {
       return result.split(snapshotRoot).join(corpusRoot);
     };
     original = { ...original, config: effectiveConfig, srcRoot: mapSource(original.srcRoot), pinConfigs, mapInputPath: mapSource, logicalInputPath,
+      ...(original.additionalSources ? { additionalSources: original.additionalSources.map(mapSource) } : {}),
       ...(original.ruleSources ? { ruleSources: original.ruleSources.map(mapSource) } : {}),
       ...(original.bindingEntries ? { bindingEntries: original.bindingEntries.map(entry => ({ ...entry, path: mapSource(entry.path) })) } : {}) };
     const target = path.resolve(original.target);
@@ -979,10 +1125,13 @@ export async function prepareRuleDeployment(original, provider, deploy) {
       mappings.push({ from, to, before });
     };
     // Mount directories independently so only provider-owned surfaces are promoted.
-    for (const dir of [`.${provider.name}`, '.agents', '.aiwg/skills']) mount(path.join(target, dir), path.join(stage, dir));
+    const relativeRoots = Object.values(provider.paths).filter(dir => dir && !path.isAbsolute(dir))
+      .map(dir => dir.split(/[\\/]/)[0]).filter(dir => dir && dir !== '.' && !path.extname(dir));
+    for (const dir of new Set([`.${provider.name}`, '.agents', '.aiwg/skills', ...relativeRoots])) mount(path.join(target, dir), path.join(stage, dir));
     fs.mkdirSync(path.join(stage, '.aiwg'), { recursive: true });
     if (fs.existsSync(projectSnapshot)) materializeInput(projectSnapshot, path.join(stage, '.aiwg', 'aiwg.config'));
     const rootNames = ['AGENTS.md', 'AIWG.md', 'WORKSPACE.md', 'CLAUDE.md', 'WARP.md', '.hermes.md', '.aiwg/AIWG.md', '.aiwg/frameworks/registry.json'];
+    if (provider.name === 'windsurf') rootNames.push('.windsurfrules');
     for (const framework of getFrameworksForMode(original.srcRoot, original.mode)) {
       for (const entry of framework.manifest?.memory?.creates || []) {
         if (typeof entry?.path !== 'string' || !entry.path.startsWith('.aiwg/') || !path.extname(entry.path)) continue;
@@ -1092,11 +1241,11 @@ export async function prepareRuleDeployment(original, provider, deploy) {
     preimages.push(...snapshotPreimages([...delivery.rules.map(rule => rule.file), ...delivery.targets.map(entry => entry.source), path.join(target, '.aiwg', 'aiwg.config')]));
     const opts = { ...original, target: stage, dryRun: false, ruleDelivery: delivery,
       kernelSkillsPath: kernel, deploymentHome: home, activeWorkspace, hermesLegacySkills, legacyCodexSkills, staging: true };
-    await deploy(opts);
+    await deploySelectedSurface(opts, provider, deploy);
     if (!opts.commandsOnly && !opts.skillsOnly && !opts.rulesOnly && opts.deployBehaviors !== false) {
-      deployEmulatedBehaviors(collectBehaviorDirs(opts.srcRoot), provider.name, stage, opts);
+      deployEmulatedBehaviors(delivery.rules.filter(rule => rule.behavior).map(rule => path.dirname(rule.file)), provider.name, stage, opts);
     }
-    const selectedRoots = [original.srcRoot, ...getFrameworksForMode(original.srcRoot, original.mode).map(framework => framework.path), ...discoverAddons(original.srcRoot).map(addon => addon.path)];
+    const selectedRoots = [original.srcRoot, ...(original.additionalSources || []), ...getFrameworksForMode(original.srcRoot, original.mode).map(framework => framework.path), ...discoverAddons(original.srcRoot).map(addon => addon.path)];
     const selected = entry => selectedRoots.some(root => /^(agents|skills|commands|flows|workflows)[/\\]/.test(path.relative(root, entry.source)));
     opts.definitionRoutes = [];
     if (provider.name === 'hermes' && !opts.kernelOnly && !opts.skillsOnly && !opts.commandsOnly && !opts.rulesOnly) {
@@ -1104,7 +1253,7 @@ export async function prepareRuleDeployment(original, provider, deploy) {
       const selectedAgents = new Set(filterAgentFiles(agents.map(target => target.source), opts));
       for (const target of agents.filter(target => selectedAgents.has(target.source))) {
         const source = target.source;
-        put(path.join(stage, '.hermes', 'agents', path.basename(source)), replaceBoundRulesBlock(read(source), delivery.bindings.get(source)));
+        put(path.join(stage, '.hermes', 'agents', path.basename(source)), managed(replaceBoundRulesBlock(read(source), delivery.bindings.get(source)), opts));
         opts.definitionRoutes.push(`${target.name}: .hermes/agents/${path.basename(source)}`);
       }
     }
@@ -1115,8 +1264,10 @@ export async function prepareRuleDeployment(original, provider, deploy) {
         if (fs.existsSync(dest)) opts.definitionRoutes.push(`${entry.name}: .warp/agents/${path.basename(entry.source)}`);
       }
     }
-    if (opts.deployRules || opts.rulesOnly || (!opts.skillsOnly && !opts.commandsOnly && ['hermes', 'warp'].includes(provider.name))) projectRules(opts, provider);
-    finishBindings(opts, provider);
+    if (!opts.deferRuleProjection) {
+      if (opts.kernelOnly || opts.deployRules || opts.rulesOnly || (!opts.skillsOnly && !opts.commandsOnly && (inlineStartup[provider.name] || ['hermes', 'warp'].includes(provider.name)))) projectRules(opts, provider);
+      finishBindings(opts, provider);
+    }
     // Normalize all generated path wrappers before counting or promoting bytes.
     const normalize = content => {
       for (const mapping of [...mappings].sort((a, b) => b.to.length - a.to.length)) content = content.split(mapping.to).join(mapping.from);
@@ -1150,6 +1301,13 @@ export async function prepareRuleDeployment(original, provider, deploy) {
     const delegated = (from, rel) => mappings.some(mapping => mapping.from !== from
       && mapping.from.startsWith(`${from}${path.sep}`)
       && (path.join(from, rel) === mapping.from || path.join(from, rel).startsWith(`${mapping.from}${path.sep}`)));
+    if (original.contextFiles === false) {
+      // Keep context inputs in the snapshot for validation, but exclude them
+      // from both dry-run output and promotion (including unchanged rewrites).
+      for (let i = rootNames.length - 1; i >= 0; i--) {
+        if (['AGENTS.md', 'AIWG.md', 'WORKSPACE.md', 'CLAUDE.md', 'WARP.md', '.hermes.md', '.aiwg/AIWG.md'].includes(rootNames[i])) rootNames.splice(i, 1);
+      }
+    }
     if (pool) verifyInputPool(pool);
     if (original.previewReport) return { report: guarded.report, noop: true };
     if (original.dryRun) {
@@ -1244,7 +1402,21 @@ export function commitRuleDeploymentPlan(plan) {
         if (before.get(rel) === fileDigest(file)) continue;
         const buffer = fs.readFileSync(file);
         // Provider output includes binary skill resources; normalize text only.
-        const output = buffer.includes(0) ? buffer : Buffer.from(normalize(buffer.toString('utf8')));
+        let output = buffer.includes(0) ? buffer : Buffer.from(normalize(buffer.toString('utf8')));
+        if (path.basename(file) === '.aiwg-manifest.json') {
+          const receipt = JSON.parse(output.toString('utf8'));
+          for (const [name, record] of Object.entries(receipt.managed || {})) {
+            const recordedFile = path.resolve(path.dirname(file), name);
+            if (!within(path.dirname(file), recordedFile) || !fs.existsSync(recordedFile)) continue;
+            const recorded = fs.readFileSync(recordedFile);
+            // Do not bless operator edits whose bytes already differ from the
+            // ownership receipt. Only normalize hashes of pristine staged files.
+            if (record.hash !== `sha256:${contentHash(recorded)}`) continue;
+            const promoted = recorded.includes(0) ? recorded : Buffer.from(normalize(recorded.toString('utf8')));
+            record.hash = `sha256:${contentHash(promoted)}`;
+          }
+          output = Buffer.from(`${JSON.stringify(receipt, null, 2)}\n`);
+        }
         fs.mkdirSync(path.dirname(path.join(from, rel)), { recursive: true });
         fs.writeFileSync(path.join(from, rel), output);
       }
@@ -1258,6 +1430,13 @@ export function commitRuleDeploymentPlan(plan) {
 
 /** Stage and commit serially for existing provider callers. */
 export async function deployWithRuleDelivery(original, provider, deploy) {
+  // Kernel source passes share the same selected rule set. Deploy their
+  // skills directly; the final source projects rules and bindings across the
+  // complete destination. Full passes retain staging for bound flow skills
+  // and provider definitions, but defer rule presentation above.
+  if (original.kernelOnly && original.deferRuleProjection && !globalThis[PREPARATION_HOOK]) {
+    return deploySelectedSurface(original, provider, deploy);
+  }
   if (original.ruleDelivery) return deploy(original);
   const hook = globalThis[PREPARATION_HOOK];
   if (hook) {
@@ -1268,3 +1447,16 @@ export async function deployWithRuleDelivery(original, provider, deploy) {
   }
   return commitRuleDeploymentPlan(await prepareRuleDeployment(original, provider, deploy));
 }
+
+async function deploySelectedSurface(opts, provider, deploy) {
+  if (!opts.kernelOnly || provider.name !== 'warp') return deploy(opts);
+  // Warp's aggregate writer emits bulk definitions even in skills-only mode.
+  // Both staged and deferred kernel passes use only its shared skill router.
+  const skills = [...listSkillDirs(path.join(opts.srcRoot, 'skills')),
+    ...getFrameworksForMode(opts.srcRoot, opts.mode).flatMap(bundle => listSkillDirs(path.join(bundle.path, 'skills'))),
+    ...getAddonSkillDirs(opts.srcRoot)].filter(isKernelSkill);
+  const standard = path.join(opts.target, provider.paths.skills);
+  for (const dir of new Set([opts.kernelSkillsPath || provider.kernelSkillsPath, provider.paths.crossAgentSkills])) {
+    if (dir) deploySkillsWithKernelRouting(skills, standard, path.isAbsolute(dir) ? dir : path.join(opts.target, dir), opts);
+  }
+}