@aiwg/cli 2026.10.1 → 2026.10.4

package/tools/agents/providers/base.mjs

@@ -11,10 +11,19 @@
 import realFs from 'fs';
 import path from 'path';
 import os from 'os';
+import yaml from 'yaml';
 import { classifyModelRole } from './model-role.mjs';
 import { createHash } from 'crypto';
 import { createRequire } from 'module';
-import { execSync as nodeExecSync } from 'child_process';
+import { importImpl } from '../../_resolve-impl.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 { extractFrameworkSlug, sameSkillOwner, canDeploySkill, pruneRecordedSkillFiles, releaseSkillOwnership } =
+  await importImpl(import.meta.url, 'providers/skill-ownership.mjs');
+export { extractFrameworkSlug, sameSkillOwner, pruneRecordedSkillFiles, releaseSkillOwnership };
 
 // Use graceful-fs to prevent EMFILE crashes on systems with low ulimit.
 // graceful-fs queues open() calls when FD pressure is detected and retries
@@ -240,8 +249,9 @@ export function updateSidecarManifest(dir, deployedEntries, opts) {
   const existing = readSidecarManifest(dir) || { managed: {} };
 
   for (const entry of deployedEntries) {
-    const { filename, hash, frameworkSlug, kind } = entry;
+    const { filename, hash, frameworkSlug, kind, sourcePath } = entry;
     const sidecarEntry = { hash: `sha256:${hash}`, source, version };
+    if (sourcePath) sidecarEntry.sourcePath = sourcePath;
     if (frameworkSlug) sidecarEntry.frameworkSlug = frameworkSlug;
     // `kind` marks artifacts whose lifecycle is governed elsewhere — currently
     // only `skill-command` wrappers, which follow their source skill (#2507).
@@ -252,26 +262,6 @@ export function updateSidecarManifest(dir, deployedEntries, opts) {
   writeSidecarManifest(dir, existing, dryRun);
 }
 
-// ============================================================================
-// Cross-Framework Collision Detection (#1169)
-// ============================================================================
-
-/**
- * Extract the framework slug from a source file path.
- *
- * Recognizes paths under `agentic/code/frameworks/<slug>/...` and
- * `agentic/code/addons/<slug>/...`. Returns null for paths outside
- * those namespaces (operator-authored bundles, addons under
- * `.aiwg/addons/`, etc.) — those don't get collision-tracked.
- */
-export function extractFrameworkSlug(srcPath) {
-  if (typeof srcPath !== 'string') return null;
-  // Normalize separators for cross-platform matching
-  const normalized = srcPath.replace(/\\/g, '/');
-  const m = normalized.match(/agentic\/code\/(?:frameworks|addons)\/([^/]+)\//);
-  return m ? m[1] : null;
-}
-
 // ============================================================================
 // Model Configuration
 // ============================================================================
@@ -376,41 +366,38 @@ const PROVIDER_TO_PLATFORM = {
 
 /**
  * Parse the platforms: field from a SKILL.md frontmatter block.
- * Handles both inline array (platforms: [a, b]) and multi-line list formats.
- * Returns null if no platforms field is present (= deploy to all providers).
- * Returns an empty array only if the field is explicitly empty.
+ * Accepts a string or a list of strings; all alone means unrestricted.
+ * Returns null if platforms is missing, or no frontmatter is present.
+ * Returns an empty array for malformed frontmatter or invalid platforms.
  */
 export function parseSkillPlatforms(content) {
-  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
-  if (!fmMatch) return null;
-
-  const fm = fmMatch[1];
-
-  // Inline array: platforms: [claude-code, codex] or platforms: [all]
-  const inlineMatch = fm.match(/^platforms:\s*\[([^\]]*)\]/m);
-  if (inlineMatch) {
-    const items = inlineMatch[1].split(',').map(s => s.trim()).filter(Boolean);
-    if (items.length === 0 || (items.length === 1 && items[0] === 'all')) return null;
-    return items;
+  // A leading UTF-8 BOM must not hide the frontmatter (and its restrictions).
+  if (content.charCodeAt(0) === 0xfeff) content = content.slice(1);
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)^---[ \t]*(?:\r?\n|$)/m);
+  if (!fmMatch || fmMatch.index !== 0) {
+    return /^---[ \t]*(?:\r?\n|$)/.test(content) ? [] : null;
   }
 
-  // Multi-line list:
-  //   platforms:
-  //     - claude-code
-  //     - hermes
-  const multiMatch = fm.match(/^platforms:\s*\n((?:[ \t]+-[ \t]+\S[^\n]*\n?)+)/m);
-  if (multiMatch) {
-    const items = multiMatch[1]
-      .split('\n')
-      .map(line => line.match(/^[ \t]+-[ \t]+(\S+)/)?.[1])
-      .filter(Boolean);
-    return items.length > 0 ? items : null;
+  let metadata;
+  try {
+    const document = yaml.parseDocument(fmMatch[1]);
+    if (document.errors.length > 0) return [];
+    if (!document.contents) return null; // Empty frontmatter has no restrictions.
+    metadata = document.toJS();
+  } catch {
+    return [];
   }
+  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) return [];
+  // The yaml package leaves merge keys unresolved, so platforms could arrive only
+  // through `<<`; without an explicit key that is ambiguous, so fail closed.
+  if (!Object.hasOwn(metadata, 'platforms')) return Object.hasOwn(metadata, '<<') ? [] : null;
 
-  // platforms: key present but empty
-  if (/^platforms:\s*$/m.test(fm)) return null;
-
-  return null; // Field absent = deploy to all
+  const platforms = metadata.platforms;
+  const items = typeof platforms === 'string' ? [platforms] : platforms;
+  if (!Array.isArray(items) || !items.every(item => typeof item === 'string')) return [];
+  const normalized = items.map(item => item.trim());
+  if (normalized.some(item => !item)) return [];
+  return normalized.length === 1 && normalized[0] === 'all' ? null : normalized;
 }
 
 /**
@@ -762,7 +749,7 @@ export function deployFiles(files, destDir, opts, transformFn) {
 
     // Read and transform source content (needed for content-equality check
     // and the collision-vs-duplicate distinction)
-    const srcContent = fs.readFileSync(f, 'utf8');
+    const srcContent = injectBoundRules(fs.readFileSync(f, 'utf8'), f, opts);
     let transformedContent = transformFn ? transformFn(f, srcContent, opts) : srcContent;
 
     // Rule triggers are index metadata, not something the reading agent needs.
@@ -901,7 +888,7 @@ export function deployFiles(files, destDir, opts, transformFn) {
       if (dryRun) console.log(`[dry-run] deploy ${a.src} -> ${a.dest} (${a.reason})`);
       else writeFile(a.dest, a.content, false);
       if (verbose) console.log(`deployed ${path.basename(a.src)} -> ${path.relative(process.cwd(), a.dest)} (${a.reason})`);
-      deployedEntries.push({ filename: path.basename(a.dest), hash: a.hash, frameworkSlug: a.frameworkSlug });
+      deployedEntries.push({ filename: path.basename(a.dest), hash: a.hash, frameworkSlug: a.frameworkSlug, sourcePath: path.resolve(a.src) });
     } else if (a.type === 'skip') {
       if (verbose) console.log(`skip (${a.reason}): ${path.basename(a.dest)}`);
       // Preserve existing sidecar entries for skipped files
@@ -1113,7 +1100,7 @@ export function deploySkillsWithKernelRouting(
   // Standard-dir cleanup (#1217): when we're NOT copying standard
   // skills, anything AIWG-named under standardDestDir is a legacy
   // mirror from a rc.13-or-earlier deploy. Prune to clean up.
-  let prunedFromStandardDir = 0;
+  let prunedFromStandardDir = pruneMissingStandardSkills(standardDestDir, opts);
   if (
     !copyStandardSkills &&
     standardDestDir &&
@@ -1550,6 +1537,32 @@ export function pruneStaleAiwgFiles(destDir, desiredStems, opts = {}) {
   return removed;
 }
 
+/** Source-scoped cleanup also works when a removed standard skill is absent from this deploy's input. */
+function pruneMissingStandardSkills(destDir, opts) {
+  if (!destDir || !opts?.srcRoot || opts.dryRun || !fs.existsSync(destDir)) return 0;
+  const sourceRoot = path.resolve(opts.srcRoot);
+  let pruned = 0;
+  for (const entry of fs.readdirSync(destDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const skillDir = path.join(destDir, entry.name);
+    const receipt = readSidecarManifest(skillDir);
+    if (!receipt?.skillSource || !receipt.managed?.['SKILL.md']) continue;
+    const relative = path.relative(sourceRoot, receipt.skillSource);
+    if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) continue;
+    try {
+      fs.statSync(path.join(receipt.skillSource, 'SKILL.md'));
+      continue;
+    } catch (error) {
+      if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') continue;
+    }
+    if (releaseSkillOwnership(skillDir, {
+      frameworkSlug: receipt.managed['SKILL.md'].frameworkSlug,
+      skillSource: receipt.skillSource,
+    }, opts)) pruned++;
+  }
+  return pruned;
+}
+
 /**
  * Deploy a skill directory (copy recursively).
  *
@@ -1574,6 +1587,10 @@ export function deploySkillDir(skillDir, destDir, opts) {
   }
 
   const destSkillDir = path.join(destDir, skillName);
+  const previous = readSidecarManifest(destSkillDir);
+  const frameworkSlug = extractFrameworkSlug(skillMdPath);
+  if (!canDeploySkill(previous, skillDir, opts)) return;
+  const managed = {};
   if (!dryRun) ensureDir(destSkillDir);
 
   function copyRecursive(src, dest) {
@@ -1601,6 +1618,15 @@ export function deploySkillDir(skillDir, destDir, opts) {
           }
         }
 
+        if (entry.name === 'SKILL.md') srcContent = injectBoundRules(srcContent, srcPath, opts);
+
+        const relative = path.relative(destSkillDir, destPath);
+        managed[relative] = {
+          hash: `sha256:${contentHash(srcContent)}`,
+          source: opts.deploySource || 'bundled',
+          version: opts.deployVersion || 'unknown',
+          ...(frameworkSlug ? { frameworkSlug } : {}),
+        };
         if (fs.existsSync(destPath)) {
           const destContent = fs.readFileSync(destPath, 'utf8');
           if (destContent === srcContent && !force) {
@@ -1620,6 +1646,8 @@ export function deploySkillDir(skillDir, destDir, opts) {
   }
 
   copyRecursive(skillDir, destSkillDir);
+  pruneRecordedSkillFiles(destSkillDir, previous?.managed, new Set(Object.keys(managed)), opts);
+  writeSidecarManifest(destSkillDir, { managed, skillSource: path.resolve(skillDir) }, dryRun);
 
   // Drop a `.aiwg-managed` marker so future cleanup runs can identify
   // AIWG-deployed skills regardless of frontmatter shape (some providers
@@ -1811,7 +1839,7 @@ export function buildRemotesTopologyBlock(targetDir) {
 
   function getUrl(remote) {
     try {
-      return nodeExecSync(`git -C ${JSON.stringify(targetDir)} remote get-url ${JSON.stringify(remote)}`, {
+      return boundedExecFileSync('git', ['-C', targetDir, 'remote', 'get-url', '--', remote], 'quick', {
         stdio: ['ignore', 'pipe', 'ignore'],
         encoding: 'utf8',
       }).trim();
@@ -2350,7 +2378,7 @@ export function getAddonCommandFiles(srcRoot, excludeAddons = [], options = {})
 }
 
 /**
- * Get all skill directories from all addons
+ * Get skill directories from a direct addon/framework source or all addons
  * @param {string} srcRoot - Source root directory
  * @param {string[]} excludeAddons - Addon names to exclude (default: none)
  * @returns {string[]} - Array of skill directory paths
@@ -2358,6 +2386,8 @@ export function getAddonCommandFiles(srcRoot, excludeAddons = [], options = {})
 export function getAddonSkillDirs(srcRoot, excludeAddons = []) {
   const addons = discoverAddons(srcRoot);
   const dirs = [];
+  const directDir = getDirectSourceDir(srcRoot, excludeAddons);
+  if (directDir) dirs.push(...listSkillDirs(directDir));
 
   for (const addon of addons) {
     if (excludeAddons.includes(addon.name)) continue;
@@ -2371,6 +2401,21 @@ export function getAddonSkillDirs(srcRoot, excludeAddons = []) {
   return dirs;
 }
 
+// `aiwg use <addon>` passes the component itself as --source. Keep bulk
+// repository discovery unchanged, even if the repo has a top-level skills/.
+function getDirectSourceDir(srcRoot, excludeAddons) {
+  if (fs.existsSync(path.join(srcRoot, 'agentic', 'code')) ||
+      excludeAddons.includes(path.basename(path.resolve(srcRoot)))) return null;
+  const dir = path.join(srcRoot, 'skills');
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return null;
+  const relative = path.relative(fs.realpathSync(srcRoot), fs.realpathSync(dir));
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    console.warn(`Warning: Skipping direct skills directory ${dir}: resolves outside source root ${srcRoot}`);
+    return null;
+  }
+  return dir;
+}
+
 /**
  * Get all rule files from all addons
  * @param {string} srcRoot - Source root directory
@@ -2400,15 +2445,8 @@ export function ruleEnforcementLevel(content) {
  * deployment dispatchable; `AIWG_RULES_INLINE_BUDGET_TOKENS=0` disables the
  * budget, any other value overrides it.
  */
-export const DEFAULT_RULES_INLINE_BUDGET_TOKENS = 64_000;
-const RULE_CHARS_PER_TOKEN = 4;
-
 export function resolveRulesInlineBudgetTokens(env = process.env) {
-  const raw = env.AIWG_RULES_INLINE_BUDGET_TOKENS;
-  if (raw === undefined || raw === '') return DEFAULT_RULES_INLINE_BUDGET_TOKENS;
-  const parsed = Number(raw);
-  if (!Number.isFinite(parsed) || parsed < 0) return DEFAULT_RULES_INLINE_BUDGET_TOKENS;
-  return parsed;
+  return resolveRulesInlineBudget({}, env);
 }
 
 /** Sidecar recording which rules the inline budget moved on demand (#2562). */
@@ -2424,96 +2462,13 @@ export function readRuleBudgetSidecar(destDir) {
   }
 }
 
-/**
- * Keep a provider rule directory under the inline budget (#2562).
- *
- * Rules reach the directory over several deploy passes (the framework pass,
- * then one per addon), so the budget is enforced against what is actually on
- * disk after each pass rather than against any single pass's file list. When
- * the inlined set exceeds the budget, the largest HIGH rules (then unlabelled
- * ones; never CRITICAL or the indexes) are removed from the directory and
- * recorded in the sidecar; the next pass skips re-deploying them and the
- * on-demand index lists them as binding rules fetched via `aiwg show rule`.
- * A changed budget invalidates the sidecar so the set is recomputed.
- *
- * Returns `{ demoted, removed }` — all demoted stems (sidecar state) and the
- * stems removed by this call.
- */
-export function reconcileInlineRuleBudget(destDir, budgetTokens = resolveRulesInlineBudgetTokens(), opts = {}) {
-  const sidecarPath = path.join(destDir, RULE_BUDGET_SIDECAR);
-  if (!budgetTokens || budgetTokens <= 0) {
-    if (fs.existsSync(sidecarPath) && !opts.dryRun) fs.rmSync(sidecarPath, { force: true });
-    return { demoted: [], removed: [] };
-  }
-  const previous = readRuleBudgetSidecar(destDir);
-  const carried = previous && previous.budgetTokens === budgetTokens ? previous.demoted : [];
-  let files = [];
-  try {
-    files = fs.readdirSync(destDir, { withFileTypes: true })
-      .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
-      .map((entry) => path.join(destDir, entry.name))
-      .filter((file) => {
-        const base = path.basename(file);
-        if (base === 'RULES-INDEX.md' || base === 'RULES-ONDEMAND.md') return false;
-        try { return MANAGED_MARKER_RE.test(fs.readFileSync(file, 'utf8')); } catch { return false; }
-      });
-  } catch {
-    return { demoted: carried, removed: [] };
-  }
-  const { demoted } = applyInlineRuleBudget(files, budgetTokens);
-  const removed = demoted.map((file) => artifactStem(path.basename(file)));
-  if (!opts.dryRun) {
-    for (const file of demoted) fs.rmSync(file, { force: true });
-  }
-  const all = [...new Set([...carried, ...removed])].sort();
-  if (!opts.dryRun) {
-    if (all.length > 0) {
-      fs.writeFileSync(sidecarPath, `${JSON.stringify({ budgetTokens, demoted: all }, null, 2)}\n`, 'utf8');
-    } else if (fs.existsSync(sidecarPath)) {
-      fs.rmSync(sidecarPath, { force: true });
-    }
-  }
-  return { demoted: all, removed };
+// Compatibility exports: budgets never change selection or retain demotions.
+export function reconcileInlineRuleBudget(destDir, budgetTokens, opts = {}) {
+  if (!opts.dryRun) fs.rmSync(path.join(destDir, RULE_BUDGET_SIDECAR), { force: true });
+  return { demoted: [], removed: [] };
 }
-
-/**
- * Fit an always-on rule set under the inline budget (#2562).
- *
- * CRITICAL rules and the generated indexes are never demoted. When the
- * remaining set still exceeds the budget, HIGH rules are demoted largest-first
- * (fewest rules leave the always-on set), then rules with no declared level.
- * Demoted rules stay reachable via `aiwg show rule <name>` and are listed in
- * RULES-ONDEMAND.md under their own heading. Returns `{ inline, demoted }`
- * with the original order preserved for `inline`.
- */
-export function applyInlineRuleBudget(ruleFiles, budgetTokens = resolveRulesInlineBudgetTokens()) {
-  const files = [...(ruleFiles || [])];
-  if (!budgetTokens || budgetTokens <= 0) return { inline: files, demoted: [] };
-  const sized = files.map((file) => {
-    const base = path.basename(file);
-    let content = '';
-    try { content = fs.readFileSync(file, 'utf8'); } catch { /* unreadable → keep inline */ }
-    const level = base === 'RULES-INDEX.md' || base === 'RULES-ONDEMAND.md' ? 'critical' : ruleEnforcementLevel(content);
-    return { file, tokens: Math.ceil(Buffer.byteLength(content, 'utf8') / RULE_CHARS_PER_TOKEN), level };
-  });
-  let total = sized.reduce((sum, item) => sum + item.tokens, 0);
-  if (total <= budgetTokens) return { inline: files, demoted: [] };
-  const demotable = sized
-    .filter((item) => item.level !== 'critical')
-    .sort((a, b) => {
-      const rank = (level) => (level === 'high' ? 0 : level === null ? 1 : 2);
-      return rank(a.level) - rank(b.level) || b.tokens - a.tokens;
-    });
-  const demoted = new Set();
-  for (const item of demotable) {
-    if (total <= budgetTokens) break;
-    demoted.add(item.file);
-    total -= item.tokens;
-  }
-  return {
-    inline: files.filter((file) => !demoted.has(file)),
-    demoted: files.filter((file) => demoted.has(file)),
-  };
+export function applyInlineRuleBudget(ruleFiles) {
+  return { inline: [...(ruleFiles || [])], demoted: [] };
 }
 
 /**
@@ -2527,10 +2482,14 @@ export function isAlwaysOnRule(filePath) {
   const base = path.basename(filePath);
   if (base === 'RULES-INDEX.md' || base === 'RULES-ONDEMAND.md') return true;
   try {
-    const lvl = ruleEnforcementLevel(fs.readFileSync(filePath, 'utf8'));
-    return lvl !== 'medium' && lvl !== 'low';
-  } catch {
-    return true; // unreadable → keep (safe default)
+    const content = fs.readFileSync(filePath, 'utf8');
+    const parsed = parseRuleFrontmatter(content);
+    if (!parsed.valid) throw new Error(`${filePath}: ${parsed.diagnostics.map(d => d.message).join('; ')}`);
+    const activation = parsed.rule.tagged ? parsed.rule.activation : inferRuleActivation(ruleEnforcementLevel(content));
+    return activation === 'kernel' || activation === 'paths';
+  } catch (error) {
+    if (error.code === 'ENOENT') return true;
+    throw error;
   }
 }
 
@@ -2548,7 +2507,9 @@ export function listOnDemandRuleFiles(srcRoot, excludeAddons = []) {
     for (const f of listMdFiles(dir)) {
       const b = path.basename(f);
       if (b === 'RULES-INDEX.md' || b === 'RULES-ONDEMAND.md') continue;
-      if (!isAlwaysOnRule(f)) out.push(f);
+      const parsed = parseRuleFrontmatter(fs.readFileSync(f, 'utf8'));
+      if (!parsed.valid) throw new Error(`${f}: invalid rule frontmatter`);
+      if (!parsed.rule.tagged && !isAlwaysOnRule(f)) out.push(f);
     }
   };
   for (const addon of discoverAddons(aiwgRoot)) {
@@ -2661,19 +2622,23 @@ export function getAddonRuleFiles(srcRoot, excludeAddons = [], options = {}) {
   for (const addon of addons) {
     if (excludeAddons.includes(addon.name)) continue;
 
-    // Skip addons with consolidated rule indexes — their rules are
-    // included via assembleRulesIndex() instead of individual files
-    if (addon.manifest?.consolidation?.deployIndexOnly) continue;
-
     const rulesDir = path.join(addon.path, 'rules');
     if (fs.existsSync(rulesDir)) {
-      files.push(...listMdFiles(rulesDir));
+      for (const file of listMdFiles(rulesDir)) {
+        // Consolidation remains a legacy inventory policy. Explicit activation
+        // owns delivery, including the desired set used by the outer prune.
+        if (addon.manifest?.consolidation?.deployIndexOnly) {
+          const parsed = parseRuleFrontmatter(fs.readFileSync(file, 'utf8'));
+          if (!parsed.valid) throw new Error(`${file}: invalid rule frontmatter`);
+          if (!parsed.rule.tagged) continue;
+        }
+        files.push(file);
+      }
     }
   }
 
-  // Tier gate (#1673): inline only always-on (CRITICAL/HIGH) rules. MEDIUM/LOW
-  // stay on-demand. Applied here so both the deploy enumeration and the prune
-  // desired-set (computeAllArtifactBasenames) exclude them for every provider.
+  // Activation selects bodies; only untagged rules use the old severity tier.
+  // The deploy enumeration and prune desired set must select the same bodies.
   return files.filter(isAlwaysOnRule);
 }
 
@@ -3365,3 +3330,25 @@ export const ProviderInterface = {
   // ── File Extension ────────────────────────────────────────────────
   getFileExtension(type) { return '.md'; }
 };
+
+/** Replace only the generated binding block; keep authored bytes intact. */
+export function replaceBoundRulesBlock(content, rules = []) {
+  const clean = content.replace(/\n?<!-- AIWG:bound-rules:start -->[\s\S]*?<!-- AIWG:bound-rules:end -->\n?/g, '');
+  if (!rules.length) return clean;
+  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}\`.`
+  ).join('\n')}\n<!-- AIWG:bound-rules:end -->\n`;
+}
+
+export function injectBoundRules(content, source, opts = {}) {
+  if (!opts.ruleDelivery) return content;
+  return replaceBoundRulesBlock(content, opts.ruleDelivery.bindings.get(path.resolve(source)) || []);
+}
+
+/** All provider output is staged; the complete startup guard runs before promotion. */
+export async function withRuleDeployment(opts, provider, deploy) {
+  const { deployWithRuleDelivery } = await import('./rule-delivery.mjs');
+  return deployWithRuleDelivery(opts, provider, deploy);
+}

package/tools/agents/providers/claude.mjs

@@ -29,6 +29,7 @@ import path from 'path';
 import { tmpdir } from 'os';
 import { classifyModelRole, modelForRole } from './model-role.mjs';
 import {
+  withRuleDeployment,
   ensureDir,
   listMdFiles,
   listMdFilesRecursive,
@@ -49,9 +50,7 @@ import {
   getAddonRuleFiles,
   listOnDemandRuleFiles,
   writeOnDemandRuleIndex,
-  readRuleBudgetSidecar,
   reconcileInlineRuleBudget,
-  resolveRulesInlineBudgetTokens,
   assembleRulesIndex,
   normalizeDeploymentMode,
   collectFrameworkArtifacts,
@@ -521,6 +520,10 @@ export function getFileExtension(type) {
  * Orchestrates deployment of agents, commands, skills, and rules
  */
 export async function deploy(opts) {
+  return withRuleDeployment(opts, { name, paths, kernelSkillsPath }, deploySelected);
+}
+
+async function deploySelected(opts) {
   const {
     srcRoot,
     target,
@@ -619,7 +622,7 @@ export async function deploy(opts) {
   // Deploy based on flags — track counts for summary
   const counts = { agents: 0, commands: 0, skills: 0, rules: 0, souls: 0 };
 
-  if (!commandsOnly && !skillsOnly) {
+  if (!commandsOnly && !skillsOnly && !rulesOnly) {
     // Apply filters if specified
     const filteredAgents = filterAgentFiles(agentFiles, opts);
     if (verbose && (opts.filter || opts.filterRole)) {
@@ -664,17 +667,7 @@ export async function deploy(opts) {
     pruneStaleAiwgSkills(kernelDestDir, computeAllKernelNames(srcRoot), opts);
   }
 
-  const inlineBudgetTokens = resolveRulesInlineBudgetTokens();
-  let demotedRuleNames = [];
   if (shouldDeployRules || rulesOnly) {
-    // Inline budget (#2562): rules a previous pass already moved on demand are
-    // not re-inlined; the directory is reconciled against the budget after
-    // this pass deploys (see below).
-    const sidecar = readRuleBudgetSidecar(path.join(target, paths.rules));
-    if (sidecar && sidecar.budgetTokens === inlineBudgetTokens && sidecar.demoted.length > 0) {
-      const skip = new Set(sidecar.demoted);
-      ruleFiles = ruleFiles.filter((f) => !skip.has(path.basename(f).replace(/\.md$/, '')));
-    }
     // Try assembled rules index (combines all component indexes)
     const assembled = assembleRulesIndex(srcRoot);
     if (assembled) {
@@ -707,17 +700,8 @@ export async function deploy(opts) {
     // On-demand index (#1673): list the MEDIUM/LOW rules that were tier-gated
     // out of the always-on set so agents can fetch them via `aiwg show rule`.
     const rulesDestDir = path.join(target, paths.rules);
-    // Keep the always-on directory small enough that a subagent dispatch
-    // still fits (#2562). Demoted HIGH rules remain binding and are listed
-    // in RULES-ONDEMAND.md with their fetch hint.
-    const budget = reconcileInlineRuleBudget(rulesDestDir, inlineBudgetTokens, opts);
-    demotedRuleNames = budget.demoted;
-    if (budget.removed.length > 0 && !opts.quiet) {
-      console.log(`  Inline rule budget: ${budget.removed.length} HIGH rule(s) moved on demand to fit ${inlineBudgetTokens.toLocaleString()} tokens: ${budget.removed.join(', ')} (see RULES-ONDEMAND.md)`);
-    }
-    const onDemandCount = writeOnDemandRuleIndex(rulesDestDir, listOnDemandRuleFiles(srcRoot), {
-      ...opts, demotedNames: demotedRuleNames, inlineBudgetTokens,
-    });
+    reconcileInlineRuleBudget(rulesDestDir, undefined, opts);
+    const onDemandCount = writeOnDemandRuleIndex(rulesDestDir, listOnDemandRuleFiles(srcRoot), opts);
     if (verbose && onDemandCount > 0) {
       console.log(`  On-demand rules (not inlined): ${onDemandCount} → RULES-ONDEMAND.md`);
     }

package/tools/agents/providers/codex.mjs

@@ -38,6 +38,7 @@ import { spawn } from 'child_process';
 import { load as loadYaml } from 'js-yaml';
 import { classifyModelRole, modelForRole } from './model-role.mjs';
 import {
+  withRuleDeployment,
   ensureDir,
   listMdFiles,
   listMdFilesRecursive,
@@ -269,7 +270,8 @@ export async function deployCommands(targetDir, srcRoot, opts) {
 
     const child = spawn('node', [scriptPath, ...args], {
       stdio: 'inherit',
-      cwd: helperRoot
+      cwd: helperRoot,
+      env: opts.deploymentHome ? { ...process.env, HOME: opts.deploymentHome } : process.env
     });
 
     child.on('close', (code) => {
@@ -318,7 +320,8 @@ export async function deploySkills(targetDir, srcRoot, opts) {
 
     const child = spawn('node', [scriptPath, ...args], {
       stdio: 'inherit',
-      cwd: helperRoot
+      cwd: helperRoot,
+      env: opts.deploymentHome ? { ...process.env, HOME: opts.deploymentHome } : process.env
     });
 
     child.on('close', (code) => {
@@ -332,7 +335,7 @@ export async function deploySkills(targetDir, srcRoot, 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);
+  pruneLegacyCodexSkills(opts, opts.legacyCodexSkills || legacyHomeSkillsDir);
 }
 
 /**
@@ -398,17 +401,16 @@ export function deployRules(ruleFiles, targetDir, opts) {
  * Aggregate agents to single AGENTS.md file
  */
 export function aggregateToAgentsMd(agentFiles, destPath, opts) {
-  const blocks = [];
-  for (const f of agentFiles) {
-    let content = fs.readFileSync(f, 'utf8');
-    content = transformAgent(f, content, opts);
-    if (!content.endsWith('\n')) content += '\n';
-    blocks.push(content);
+  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'));
+    const name = metadata.name || path.basename(file, '.md');
+    lines.push(`- ${name}: .codex/agents/${path.basename(file, '.md')}.toml`);
   }
-  const out = blocks.join('\n');
+  const out = `${lines.join('\n')}\n`;
   if (opts.dryRun) console.log(`[dry-run] write ${destPath}`);
   else fs.writeFileSync(destPath, out, 'utf8');
-  console.log(`wrote ${path.relative(process.cwd(), destPath)} with ${agentFiles.length} agents`);
+
 }
 
 // ============================================================================
@@ -536,6 +538,10 @@ export function getFileExtension(type) {
  * Main deployment function for Codex provider
  */
 export async function deploy(opts) {
+  return withRuleDeployment(opts, { name, paths, kernelSkillsPath }, deploySelected);
+}
+
+async function deploySelected(opts) {
   const {
     srcRoot,
     target,
@@ -628,6 +634,7 @@ export async function deploy(opts) {
       // Aggregate to single AGENTS.md
       const destPath = path.join(target, 'AGENTS.md');
       console.log(`\nAggregating ${agentFiles.length} agents to AGENTS.md...`);
+      deployAgents(agentFiles, target, opts);
       aggregateToAgentsMd(agentFiles, destPath, opts);
     } else {
       console.log(`\nDeploying ${agentFiles.length} agents...`);