@aiwg/cli 2026.10.5 → 2026.10.7

package/dist/src/cli/handlers/use.js

@@ -1,3 +1,4 @@
+import { ContextWriteJournal } from '../../smiths/context-pipeline/context-file-safety.js';
 import { trackTemporaryDirectory } from '../../utils/temporary-directory.js';
 /**
  * Use Command Handler
@@ -43,6 +44,7 @@ import { detectScope, mirrorToUserScope, rejectOpenClawProjectScope, USER_SCOPE_
 import { maybeWarnProjectIsolation } from '../project-isolation/index.js';
 import { formatWorkspaceSignalPlan, includedBundleIds, resolveWorkspaceSignalPlan, writeWorkspaceSignalPlan, } from '../workspace-signals.js';
 import { getProviderArtifactPathStrings, getProviderDefinition, getProviderKernelSkillPath, normalizeProviderDefinitionId, } from '../../providers/provider-definitions.js';
+import { resolveDeployVersion } from '../../providers/deploy-version.mjs';
 import { deployedSkillRoots } from '../../providers/deployed-skill-roots.js';
 // Module-level guard so the iteration loops further down (which re-enter
 // execute() per framework/provider) don't re-emit the warning each pass.
@@ -152,10 +154,11 @@ const MODEL_OVERRIDE_VALUE_FLAGS = new Set([
     '--model', '--reasoning-model', '--coding-model', '--efficiency-model', '--model-tier',
 ]);
 const MODEL_DEPLOY_BOOLEAN_FLAGS = new Set(['--save', '--save-user']);
-/** Forward explicit user scope to every provider deploy subprocess. */
+/** Forward explicit scope to every provider deploy subprocess. */
 export function collectUseScopeDeployArgs(args) {
     const scope = detectScope(args);
-    return scope === 'user' || args.includes('--user') ? ['--scope', 'user'] : [];
+    return scope === 'user' || args.includes('--user') ? ['--scope', 'user']
+        : args.includes('--scope') ? ['--scope', 'project'] : [];
 }
 export function collectUseModelDeployArgs(args) {
     const forwarded = [];
@@ -410,7 +413,7 @@ export function addonPath(frameworkRoot, name) {
  * this only suppresses redundant deploy-agents subprocesses.
  */
 export function mainDeploymentIncludesAddons(provider, selectedMode, providerDeployArgs) {
-    return (((provider === 'claude' || provider === 'pi')
+    return (((provider === 'claude' || provider === 'pi' || provider === 'omp')
         && ['general', 'sdlc', 'both', 'all'].includes(selectedMode))
         || (provider === 'codex' && selectedMode === 'all'))
         && !providerDeployArgs.some(arg => arg === '--source' || arg.startsWith('--source='))
@@ -628,7 +631,7 @@ async function mirrorStandardCommandSkills(opts) {
             projectPath: opts.target,
             dryRun: opts.dryRun,
             verbose: opts.verbose,
-            deployVersion: (await getVersionInfo()).version,
+            deployVersion: deploymentVersion(opts.frameworkRoot),
             nameFilter: shouldMirrorStandardCommandSkill,
         });
         count += result.translated.length;
@@ -1326,7 +1329,7 @@ async function deployOneProjectLocalBundle(opts) {
     }
     let exitCode = 0;
     if (artifactTotal > 0) {
-        const runner = createScriptRunner(frameworkRoot);
+        const runner = createUseScriptRunner(frameworkRoot);
         const args = [
             '--source', bundle.artifactPath,
             '--deploy-commands', '--deploy-skills', '--deploy-rules',
@@ -1622,6 +1625,106 @@ const USE_FLAGS_WITH_VALUES = new Set([
     '--scope',
     '--target',
 ]);
+// Public use options, including supported deployer passthroughs. Value flags
+// also drive positional parsing, so option values cannot become bundle names.
+for (const flag of [...MODEL_DEPLOY_VALUE_FLAGS, '--reasoning', '--coding', '--efficiency']) {
+    USE_FLAGS_WITH_VALUES.add(flag);
+}
+const USE_BOOLEAN_FLAGS = new Set([
+    '--force', '--copy-all', '--copy-standard-skills', '--dry-run', '--verbose', '-v', '--quiet', '-q',
+    '--json', '--no-project-local', '--no-context-files', '--no-workspace-md',
+    '--no-aiwg-md', '--no-agents-md', '--force-context-files', '--global', '--user',
+    '--no-utils', '--ci-hooks-enabled', '--skip-conflicts', '--no-harness-agents',
+    '--workspace-signals', '--no-workspace-signals', '--yes', '-y', '--non-interactive',
+    '--allow-over-budget', '--no-hooks', '--enable-cross-provider-hooks',
+    '--skip-commands-migration', '--listing-budget', '--mcp', '--as-agents-md',
+    '--create-agents-md', '--commands-only', '--skills-only', '--rules-only',
+    '--save', '--save-user', '--help', '-h',
+]);
+export function validateUseOptions(args, preparedCapabilities = new Set()) {
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--aiwg-provider-main-prepared' && preparedCapabilities.has(args[i + 1])) {
+            i++;
+            continue;
+        }
+        if (USE_FLAGS_WITH_VALUES.has(arg)) {
+            if (!args[i + 1] || args[i + 1].startsWith('-'))
+                return `Missing value for option '${arg}'. See aiwg use --help.`;
+            i++;
+        }
+        else if (arg.startsWith('-') && !USE_BOOLEAN_FLAGS.has(arg)) {
+            return `Unknown option '${arg}'. See aiwg use --help.`;
+        }
+    }
+    return undefined;
+}
+/** Pi's agent discovery path doubles as its kernel skill directory. */
+export async function countPiAgentFiles(target, agentsPath) {
+    if (!agentsPath)
+        return 0;
+    try {
+        const dir = path.isAbsolute(agentsPath) ? agentsPath : path.join(target, agentsPath);
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        return entries.filter(entry => entry.isFile() && entry.name.endsWith('.md')).length;
+    }
+    catch {
+        return 0;
+    }
+}
+// Capture provider previews here: their staging summaries count source entries,
+// and additive passes can describe the same destination more than once.
+let usePreviewActions;
+// Recursive framework/addon/provider passes share the boundary's resolved policy.
+async function generateDeploymentContextFiles(options) {
+    const result = await generateContextFiles(options);
+    useDeployment?.contextFiles.push(result);
+    return result;
+}
+let useDeployment;
+function useDeploymentArgs(args) {
+    const forwarded = [...args];
+    if (useDeployment && !forwarded.includes('--deploy-version'))
+        forwarded.push('--deploy-version', useDeployment.version);
+    if (useDeployment?.skipContextFiles && !forwarded.includes('--no-context-files'))
+        forwarded.push('--no-context-files');
+    return forwarded;
+}
+function deploymentVersion(root) {
+    return useDeployment?.version ?? resolveDeployVersion(root);
+}
+function createUseScriptRunner(frameworkRoot) {
+    const runner = createScriptRunner(frameworkRoot);
+    return {
+        async run(script, args, options = {}) {
+            if (script === 'tools/agents/deploy-agents.mjs')
+                args = useDeploymentArgs(args);
+            if (!usePreviewActions)
+                return runner.run(script, args, options);
+            const scratch = await fs.mkdtemp(path.join(os.tmpdir(), 'aiwg-use-preview-'));
+            const removeScratch = trackTemporaryDirectory(scratch);
+            const stdoutFile = await fs.open(path.join(scratch, 'stdout'), 'w+');
+            try {
+                // Keep the shared runner's timeout/error handling and injectable
+                // execution boundary; capture only this invocation's stdout to disk.
+                const result = await runner.run(script, args, { ...options, capture: true, stdoutFd: stdoutFile.fd });
+                const stdout = await fs.readFile(path.join(scratch, 'stdout'), 'utf8');
+                for (const line of stdout.split(/\r?\n/)) {
+                    if (/^\[dry-run\] Would (write|remove|deploy|copy|create) /i.test(line))
+                        usePreviewActions.add(line);
+                }
+                return result;
+            }
+            catch (error) {
+                return { exitCode: 1, message: error instanceof Error ? error.message : String(error) };
+            }
+            finally {
+                await stdoutFile.close();
+                removeScratch();
+            }
+        },
+    };
+}
 export const OPENHUMAN_DEFAULT_HARNESS_AGENTS = [
     'architecture-designer',
     'code-reviewer',
@@ -2013,13 +2116,15 @@ async function generateGlobalProjectContext(opts) {
     if (!userPaths)
         return;
     const skipContext = opts.args.includes('--no-context-files');
+    if (skipContext)
+        return;
     const sections = await discoverDeployedArtifacts(opts.projectPath, {
         agents: userPaths.agents,
         rules: userPaths.rules,
         skills: userPaths.skills,
         behaviors: userPaths.behaviors,
     });
-    await generateContextFiles({
+    await generateDeploymentContextFiles({
         provider: opts.provider,
         projectPath: opts.projectPath,
         sections,
@@ -2082,7 +2187,7 @@ async function ensurePostDeployPhases(opts) {
         behaviors: paths.behaviors,
     });
     try {
-        await generateContextFiles({
+        await generateDeploymentContextFiles({
             provider: opts.provider,
             projectPath: opts.projectPath,
             sections,
@@ -2095,8 +2200,8 @@ async function ensurePostDeployPhases(opts) {
             },
         });
     }
-    catch {
-        // The shared verifier reports context or provider-wiring failures.
+    catch (error) {
+        throw new Error(`Context generation failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
     }
 }
 async function deploySourceDirectory(opts) {
@@ -2120,9 +2225,11 @@ async function deploySourceDirectory(opts) {
         args.push('--copy-all');
     if (opts.kernelOnly)
         args.push('--kernel-only');
+    if (opts.deferRuleProjection)
+        args.push('--defer-rule-projection');
     if (opts.quiet)
         args.unshift('--quiet');
-    const runner = createScriptRunner(opts.frameworkRoot);
+    const runner = createUseScriptRunner(opts.frameworkRoot);
     const result = await runner.run('tools/agents/deploy-agents.mjs', args, opts.quiet ? { capture: true } : {});
     if (result.exitCode === 0 && !opts.kernelOnly) {
         try {
@@ -2207,7 +2314,7 @@ async function deployOmpUserSource(opts) {
     const adapter = await import(pathToFileURL(path.join(opts.frameworkRoot, 'tools/agents/providers/omp.mjs')).href);
     await adapter.deploy({ srcRoot: opts.source, target: opts.target, provider: 'omp', scope: 'user',
         mode: opts.mode ?? 'general', deployCommands: true, deploySkills: true, deployRules: true,
-        copyStandardSkills: opts.copyAll, quiet: true, deployVersion: (await getVersionInfo()).version });
+        copyStandardSkills: opts.copyAll, quiet: true, contextFiles: !useDeployment?.skipContextFiles, deployVersion: deploymentVersion(opts.frameworkRoot) });
     const sourceBundles = new Set([opts.source]);
     const { resourceDirs } = resolveOmpPaths({ cwd: opts.target });
     const entries = {
@@ -2359,7 +2466,7 @@ const USE_HELP = `Usage: aiwg use <bundle> [options]
 Deploy an AIWG framework, addon, or extension into the current project.
 
 Bundles:
-  all                       Kernel surface only (kernel skills, rules, behaviors)
+  all                       Kernel surface only (kernel skills, kernel and core rules, behaviors)
   sdlc | research | ops | forensics | marketing | media-curator | ...
                             Full framework surface (agents, commands, skills, rules)
   <addon> | <extension>     Any installed addon or extension name
@@ -2371,15 +2478,56 @@ Options:
   --force                   Re-write every artifact, replacing files AIWG does
                             not currently manage. Use this to reclaim a
                             directory left behind by an older AIWG install.
-  --copy-all                Mirror standard-tier skills into the project instead
-                            of relying on index-driven discovery
+  --copy-all                Mirror standard-tier skills into the project; for
+                            all, restore the full agent, command and rule surface
   --dry-run                 Preview the deployment without writing files
+  --quiet, -q               Suppress deployer progress output
   --verbose, -v             Show per-artifact deploy decisions
   --json                    Emit the machine-readable deployment result
   --no-project-local        Skip project-local bundles under .aiwg/
-  --no-context-files        Skip WORKSPACE.md / AIWG.md / AGENTS.md emission
+  --no-context-files        Preserve WORKSPACE.md / AIWG.md / AGENTS.md, including managed blocks
   -h, --help                Show this help without deploying
 
+Additional options:
+  --platform <name>         Alias for --provider
+  --providers <a,b>         Providers for global bootstrap
+  --prefix <dir>            Alias for --target
+  --global, --user          Install to user scope
+  --copy-standard-skills    Alias for --copy-all (also restores the full surface)
+  --profile <name>          Select workspace profile (implicit target: all)
+  --workspace-signals       Show the workspace signal plan
+  --no-workspace-signals    Skip workspace signal resolution
+  --model <name>, --model-tier <tier>
+  --reasoning-model <name>, --coding-model <name>, --efficiency-model <name>
+  --reasoning <name>, --coding <name>, --efficiency <name>
+                            Override deployer model selection
+  --filter <glob>, --filter-role <role>
+                            Filter deployed agents
+  --save, --save-user        Persist model selection
+  --no-utils                Skip additive addon and extension passes
+  --no-workspace-md, --no-aiwg-md, --no-agents-md
+                            Suppress individual context files
+  --force-context-files     Replace context files
+  --no-hooks                Skip managed hooks
+  --enable-cross-provider-hooks
+                            Enable cross-provider hooks
+  --ci-hooks-enabled        Deploy CI workflows
+  --skip-conflicts          Skip the collision check
+  --allow-over-budget       Allow oversized startup context
+  --harness-agents <list>, --no-harness-agents
+                            Select OpenHuman harness agents
+  --skip-commands-migration Skip commands migration
+  --listing-budget          Honor startup listing caps with --copy-all
+  --mcp                     Opt in to the Muse MCP profile
+  --as-agents-md, --create-agents-md
+                            Select Codex context aggregation
+  --commands-only, --skills-only, --rules-only
+                            Limit artifact kinds
+  --yes, -y, --non-interactive
+                            Allow unattended setup
+
+Source installs are detected automatically; no development flag is needed.
+
 Deployment counts report what the run wrote or already manages. Files AIWG does
 not own are listed separately as unmanaged and are never counted as deployed.
 `;
@@ -2395,6 +2543,59 @@ export class UseHandler {
         return { exitCode: 0, message: USE_HELP, rawOutput: true };
     }
     async execute(ctx) {
+        const invalidOption = validateUseOptions(ctx.args, this.preparedProviderContinuations);
+        if (invalidOption)
+            return { exitCode: 2, message: invalidOption };
+        const previousDeployment = useDeployment;
+        useDeployment = {
+            version: previousDeployment?.version ?? resolveDeployVersion(ctx.frameworkRoot || await getFrameworkRoot()),
+            skipContextFiles: previousDeployment?.skipContextFiles || ctx.args.includes('--no-context-files'),
+            contextFiles: previousDeployment?.contextFiles ?? [],
+        };
+        const journal = previousDeployment ? undefined : new ContextWriteJournal();
+        try {
+            let result;
+            try {
+                result = await this.executeDeployment(ctx);
+            }
+            catch (error) {
+                result = { exitCode: 1, message: error instanceof Error ? error.message : String(error) };
+            }
+            if (journal) {
+                const rollback = result.exitCode !== 0 ? journal.rollback() : undefined;
+                if (ctx.args.includes('--json')) {
+                    let structured;
+                    try {
+                        structured = JSON.parse(result.message || '{}');
+                    }
+                    catch {
+                        structured = { exitCode: result.exitCode, message: result.message };
+                    }
+                    structured.contextFiles = useDeployment.contextFiles;
+                    if (rollback)
+                        structured.contextRollback = rollback;
+                    result = { ...result, message: JSON.stringify(structured, null, 2), rawOutput: true };
+                }
+                else if (rollback?.conflicts.length) {
+                    result.message = [result.message, ...rollback.conflicts.map(conflict => `Context rollback conflict: ${conflict.path}: ${conflict.reason}`)].filter(Boolean).join('\n');
+                }
+            }
+            return result;
+        }
+        finally {
+            journal?.dispose();
+            useDeployment = previousDeployment;
+        }
+    }
+    async executeDeployment(ctx) {
+        // Normalize the physical framework directory just as addon folder aliases
+        // are normalized, before orchestration/registry bookkeeping sees the name.
+        const aliasIndex = ctx.args.indexOf('sdlc-complete');
+        if (firstUsePositional(ctx.args) === 'sdlc-complete' && aliasIndex >= 0) {
+            const args = [...ctx.args];
+            args[aliasIndex] = 'sdlc';
+            ctx = { ...ctx, args };
+        }
         const requestedBundle = firstUsePositional(ctx.args)
             ?? (ctx.args[0] === '--profile' ? 'all' : undefined);
         const bypassOrchestration = this.orchestrationDepth > 0
@@ -2403,9 +2604,9 @@ export class UseHandler {
             || ctx.args.includes('--workspace-signals');
         if (bypassOrchestration)
             return this.executeCore(ctx);
-        // Child deployers share one source-index snapshot for this invocation. Each
-        // addon still resolves and validates its bindings through the common query
-        // engine, without rebuilding the entire corpus on every additive pass.
+        // Projectors share one source-index snapshot for this invocation. Full
+        // addon passes validate their bindings through the common query engine;
+        // deferred kernel passes leave the shared rule set to the final projector.
         const previousBindingCache = process.env.AIWG_RULE_BINDING_INDEX_CACHE;
         const bindingCache = previousBindingCache || await fs.mkdtemp(path.join(os.tmpdir(), 'aiwg-use-bindings-'));
         const removeBindingCache = previousBindingCache ? () => { } : trackTemporaryDirectory(bindingCache);
@@ -2457,8 +2658,13 @@ export class UseHandler {
             warn: console.warn,
             error: console.error,
         };
-        if (json) {
-            machineReadableUseDepth += 1;
+        const previewActions = dryRun ? new Set() : undefined;
+        const previousPreview = usePreviewActions;
+        if (previewActions)
+            usePreviewActions = previewActions;
+        if (json || dryRun) {
+            if (!dryRun)
+                machineReadableUseDepth += 1;
             console.log = () => { };
             console.info = () => { };
             console.warn = () => { };
@@ -2468,9 +2674,14 @@ export class UseHandler {
         try {
             coreResult = await this.executeCore({ ...ctx, args: coreArgs });
         }
+        catch (error) {
+            coreResult = { exitCode: 1, message: error instanceof Error ? error.message : String(error) };
+        }
         finally {
-            if (json) {
-                machineReadableUseDepth -= 1;
+            usePreviewActions = previousPreview;
+            if (json || dryRun) {
+                if (!dryRun)
+                    machineReadableUseDepth -= 1;
                 console.log = originalConsole.log;
                 console.info = originalConsole.info;
                 console.warn = originalConsole.warn;
@@ -2491,12 +2702,18 @@ export class UseHandler {
         else {
             if (coreResult.exitCode === 0 && !dryRun && !VALID_FRAMEWORKS.includes(requestedBundle)) {
                 for (const provider of providers) {
-                    await ensurePostDeployPhases({
-                        frameworkRoot,
-                        projectPath: projectDir,
-                        provider,
-                        args: remainingArgs,
-                    });
+                    try {
+                        await ensurePostDeployPhases({
+                            frameworkRoot,
+                            projectPath: projectDir,
+                            provider,
+                            args: remainingArgs,
+                        });
+                    }
+                    catch (error) {
+                        coreResult = { exitCode: 1, message: error instanceof Error ? error.message : String(error) };
+                        break;
+                    }
                 }
             }
             const providerResults = [];
@@ -2528,7 +2745,7 @@ export class UseHandler {
                         originalConsole.warn(`Provider receipt finalization failed for ${provider}: ${error instanceof Error ? error.message : String(error)}`);
                     }
                 }
-                providerResults.push(await verifyProviderDeployment({
+                const verified = await verifyProviderDeployment({
                     projectRoot: projectDir,
                     frameworkRoot,
                     provider,
@@ -2542,7 +2759,14 @@ export class UseHandler {
                     // yet, so receipt absence belongs in doctor/status rather than
                     // degrading an otherwise successful `aiwg use` result.
                     reportMissingReceipt: false,
-                }));
+                });
+                // Pi exposes agents through skills. The shared verifier counts skill
+                // directories at that path as agents; report only actual agent files.
+                if (provider === 'pi') {
+                    const paths = effectiveScope === 'user' ? USER_SCOPE_PATHS.pi : getProviderPaths(provider);
+                    verified.counts.agents = await countPiAgentFiles(projectDir, paths.agents);
+                }
+                providerResults.push(verified);
             }
             result = aggregateUseDeploymentResult({
                 projectRoot: projectDir,
@@ -2580,7 +2804,7 @@ export class UseHandler {
         });
         return {
             exitCode: result.exitCode,
-            message: [coreResult.message, rendered].filter(Boolean).join('\n'),
+            message: [coreResult.message, rendered, ...(previewActions ? [...previewActions].sort() : [])].filter(Boolean).join('\n'),
         };
     }
     async executeCore(ctx) {
@@ -2728,6 +2952,14 @@ export class UseHandler {
             : null;
         const projectDir = getProjectDir(ctx, remainingArgs);
         let config = await readAiwgConfig(projectDir);
+        if (detectScope(remainingArgs) === 'project' && remainingArgs.includes('--scope')) {
+            for (const requested of configuredGlobalProviders(remainingArgs, config)) {
+                const resolved = await resolveProjectLocalProviderAdapter(projectDir, requested);
+                if (normalizeProviderDefinitionId(resolved.provider) === 'hermes') {
+                    return { exitCode: 1, message: "Hermes does not support --scope project: it discovers skills only under HERMES_HOME/skills (default ~/.hermes/skills). Use --scope user or an isolated HERMES_HOME profile shared with Hermes." };
+                }
+            }
+        }
         // Auto-init when no config found (#720)
         // Check early for --provider/--platform and --providers flags
         const _providerFlagIdx = remainingArgs.findIndex(a => a === '--provider' || a === '--platform');
@@ -2766,7 +2998,9 @@ export class UseHandler {
             }
             else if (process.stdin.isTTY) {
                 // Interactive terminal with no config → run init wizard inline (#720)
-                const initResult = await initHandler.execute({ ...ctx, args: [] });
+                const initResult = await initHandler.execute({ ...ctx,
+                    args: remainingArgs.includes('--no-context-files') ? ['--no-context-files'] : [],
+                });
                 if (initResult.exitCode !== 0)
                     return initResult;
                 config = await readAiwgConfig(projectDir);
@@ -2780,7 +3014,7 @@ export class UseHandler {
                     : '';
                 return {
                     exitCode: 1,
-                    message: `Error: Framework, addon, or extension name required\nFrameworks: sdlc, marketing, media-curator, research, forensics, dfir, security-engineering, ops, validation, knowledge-base, all\nAddons: rlm, ring, daemon, aiwg-dev (full list: \`aiwg list\`)\nExtensions: sys, net, it, sec, stream, dev (full list: \`ls $AIWG_ROOT/agentic/code/extensions\`)\n'all' deploys every framework + every addon + every extension.${advisory}`,
+                    message: `Error: Framework, addon, or extension name required\nFrameworks: sdlc, marketing, media-curator, research, forensics, dfir, security-engineering, ops, validation, knowledge-base, all\nAddons: rlm, ring, daemon, aiwg-dev (full list: \`aiwg list\`)\nExtensions: sys, net, it, sec, stream, dev (full list: \`ls $AIWG_ROOT/agentic/code/extensions\`)\n'all' deploys the kernel surface (kernel skills, kernel and core rules, behaviors).${advisory}`,
                 };
             }
             const installedNames = Object.keys(config.installed);
@@ -2843,50 +3077,19 @@ export class UseHandler {
             ui.dim('  Use `aiwg use all` for the full deployment.');
             for (const providerName of providersForFiltered) {
                 const kernelOnly = !copyAll;
-                for (const selected of selectedFrameworks) {
-                    const frameworkDir = resolveFrameworkDir(selected);
-                    if (!frameworkDir)
-                        continue;
-                    const result = await deploySourceDirectory({
-                        ctx,
-                        frameworkRoot,
-                        source: path.join(frameworkRoot, 'agentic/code/frameworks', frameworkDir),
-                        provider: providerName,
-                        target,
-                        dryRun,
-                        verbose,
-                        force,
-                        copyAll,
-                        kernelOnly,
-                        quiet,
-                        modelArgs: modelDeployArgs,
-                    });
-                    if (result.exitCode !== 0)
-                        return result;
-                }
-                for (const selected of selectedAddons) {
-                    const result = await deploySourceDirectory({
-                        ctx,
-                        frameworkRoot,
-                        source: addonPath(frameworkRoot, selected),
-                        provider: providerName,
-                        target,
-                        dryRun,
-                        verbose,
-                        force,
-                        copyAll,
-                        kernelOnly,
-                        quiet,
-                        modelArgs: modelDeployArgs,
-                    });
-                    if (result.exitCode !== 0)
-                        return result;
-                }
-                for (const selected of selectedExtensions) {
+                const sources = [
+                    ...selectedFrameworks.flatMap(selected => {
+                        const directory = resolveFrameworkDir(selected);
+                        return directory ? [path.join(frameworkRoot, 'agentic/code/frameworks', directory)] : [];
+                    }),
+                    ...selectedAddons.map(selected => addonPath(frameworkRoot, selected)),
+                    ...selectedExtensions.map(selected => extensionPath(frameworkRoot, selected)),
+                ];
+                for (const [index, source] of sources.entries()) {
                     const result = await deploySourceDirectory({
                         ctx,
                         frameworkRoot,
-                        source: extensionPath(frameworkRoot, selected),
+                        source,
                         provider: providerName,
                         target,
                         dryRun,
@@ -2894,6 +3097,10 @@ export class UseHandler {
                         force,
                         copyAll,
                         kernelOnly,
+                        // Kernel rule selection is invocation-wide, independent of the
+                        // source bundle. The last pass projects once over all deployed
+                        // skills, including their bound-rule pointers and startup blocks.
+                        deferRuleProjection: kernelOnly && index < sources.length - 1,
                         quiet,
                         modelArgs: modelDeployArgs,
                     });
@@ -3086,7 +3293,7 @@ export class UseHandler {
             }
             return {
                 exitCode: 1,
-                message: `Error: Unknown target '${framework}'\nFrameworks: ${VALID_FRAMEWORKS.join(', ')}\n\n'all' deploys every framework + every addon + every extension.\nFor a single addon, run 'aiwg list' to see available addons.\nFor extensions (sys, net, it, sec, stream, dev), see $AIWG_ROOT/agentic/code/extensions/.\nFor project-local artifacts, run 'aiwg list --project-local'.\nRun 'aiwg help' for usage information.`,
+                message: `Error: Unknown target '${framework}'\nFrameworks: ${VALID_FRAMEWORKS.join(', ')}\n\n'all' deploys the kernel surface (kernel skills, kernel and core rules, behaviors).\nFor a single addon, run 'aiwg list' to see available addons.\nFor extensions (sys, net, it, sec, stream, dev), see $AIWG_ROOT/agentic/code/extensions/.\nFor project-local artifacts, run 'aiwg list --project-local'.\nRun 'aiwg help' for usage information.`,
             };
         }
         // Handle addon-only or extension-only deployment.
@@ -3113,7 +3320,7 @@ export class UseHandler {
                     message: `--scope user not supported for provider '${provider}' — see docs/customization/user-scope-deployment.md for the supported list`,
                 };
             }
-            const runner = createScriptRunner(frameworkRoot);
+            const runner = createUseScriptRunner(frameworkRoot);
             const addonBaseArgs = ['--deploy-commands', '--deploy-skills', '--deploy-rules'];
             if (remainingArgs.includes('--allow-over-budget'))
                 addonBaseArgs.push('--allow-over-budget');
@@ -3422,8 +3629,8 @@ export class UseHandler {
         const filteredArgs = removeFlagWithOptionalValue(deployArgs, preparedFlag).filter(a => a !== '--no-utils' && a !== '--no-project-local' && a !== '--ci-hooks-enabled' && a !== '--skip-conflicts' && a !== '--no-harness-agents');
         const deployFilteredArgs = removeFlagWithOptionalValue(filteredArgs, '--harness-agents');
         // Pass --quiet to suppress deploy-agents.mjs header/footer in default mode (#460)
-        // Human dry-run remains verbose; machine-readable dry-run captures the
-        // preview so stdout stays a single JSON document.
+        // Dry-run action output is captured and consolidated at the use boundary;
+        // keep it available to the collector rather than silencing child plans.
         if (machineReadableUseDepth > 0 || (!verbose && !dryRun))
             deployFilteredArgs.push('--quiet');
         // Extract provider and target from remainingArgs to pass to addon deployments
@@ -3467,10 +3674,17 @@ export class UseHandler {
                     canPrepareConcurrently = false;
                     break;
                 }
-                const args = withProviderOverride([...deployFilteredArgs], resolved.provider);
-                if (framework === 'all' && !['pi', 'omp'].includes(resolved.provider)
-                    && !remainingArgs.includes('--copy-all') && !remainingArgs.includes('--copy-standard-skills'))
-                    args.push('--kernel-only');
+                const args = useDeploymentArgs(withProviderOverride([...deployFilteredArgs], resolved.provider));
+                if (framework === 'all') {
+                    const kernelOnly = !['pi', 'omp'].includes(resolved.provider)
+                        && !remainingArgs.includes('--copy-all') && !remainingArgs.includes('--copy-standard-skills');
+                    if (kernelOnly)
+                        args.push('--kernel-only');
+                    if (!skipUtils && ((!kernelOnly && (await getAllExtensions(frameworkRoot)).length > 0)
+                        || (!mainDeploymentIncludesAddons(resolved.provider, mode, args) && (await getAllAddons(frameworkRoot)).length > 0))) {
+                        args.push('--defer-rule-projection');
+                    }
+                }
                 preparedJobs.push({ order, provider: resolved.provider, target: path.resolve(target), args });
             }
             if (canPrepareConcurrently && preparedJobs.length === providers.length) {
@@ -3539,6 +3753,21 @@ export class UseHandler {
             && !remainingArgs.includes('--copy-standard-skills');
         if (bulkKernelOnly)
             providerDeployArgs.push('--kernel-only');
+        const allAddons = skipUtils ? [] : await getAllAddons(frameworkRoot);
+        const allExtensions = skipUtils || bulkKernelOnly ? [] : await getAllExtensions(frameworkRoot);
+        const mainIncludesAddons = mainDeploymentIncludesAddons(provider, mode, providerDeployArgs);
+        // OMP's extension sources share the root transaction and binding scan.
+        // Their CLI contributions are still registered below in source order.
+        const batchedOmpExtensions = provider === 'omp' && mainIncludesAddons ? allExtensions : [];
+        for (const extension of batchedOmpExtensions) {
+            providerDeployArgs.push('--additional-source', extensionPath(frameworkRoot, extension));
+        }
+        const additiveSources = (mainIncludesAddons ? 0 : allAddons.length)
+            + allExtensions.length - batchedOmpExtensions.length;
+        // Keep the final source's rule selection and presentation, while earlier
+        // full-surface passes still deploy their own agents/skills/flow resources.
+        if (framework === 'all' && additiveSources > 0)
+            providerDeployArgs.push('--defer-rule-projection');
         if ((verbose || dryRun) && projectLocalProviderResolution.requestedProvider) {
             ui.dim(`  project-local provider '${projectLocalProviderResolution.requestedProvider}' extends '${provider}'`);
         }
@@ -3619,18 +3848,18 @@ export class UseHandler {
         const captureOpts = quiet ? { capture: true } : {};
         if (quiet) {
             const installLabel = framework === 'all'
-                ? 'Installing complete AIWG surface'
+                ? (bulkKernelOnly ? 'Installing AIWG kernel surface' : 'Installing full AIWG surface')
                 : `Installing ${framework} framework`;
             const providerLabel = getProviderDefinition(provider)?.displayName ?? provider;
             ui.blank();
             console.log(`  ${ui.brandMark()} ${ui.bold(installLabel)}  ${ui.dimText(`for ${providerLabel}`)}`);
             ui.blank();
         }
-        const runner = createScriptRunner(ctx.frameworkRoot);
+        const runner = createUseScriptRunner(ctx.frameworkRoot);
         let mainResult;
         if (mainProviderPrepared) {
             try {
-                await finalizePreparedProvider(frameworkRoot, providerDeployArgs);
+                await finalizePreparedProvider(frameworkRoot, useDeploymentArgs(providerDeployArgs));
                 mainResult = { exitCode: 0 };
             }
             catch (error) {
@@ -3690,14 +3919,11 @@ export class UseHandler {
         }
         // Deploy all addons (excluding disallow list) unless --no-utils
         if (!skipUtils) {
-            const allAddons = await getAllAddons(frameworkRoot);
             // These root collectors already deploy every eligible addon. Re-staging
             // the entire deployment per addon duplicates that work. Codex's skills
             // helper includes addons only in all mode; other modes retain their pass.
             // CLI contribution registration below still runs for every addon.
-            const selectedMode = MODE_MAP[framework];
-            const mainIncludesAddons = mainDeploymentIncludesAddons(provider, selectedMode, providerDeployArgs);
-            for (const addon of allAddons) {
+            for (const [index, addon] of allAddons.entries()) {
                 if (verbose) {
                     console.log('');
                     console.log(`Deploying ${addon} addon...`);
@@ -3706,6 +3932,9 @@ export class UseHandler {
                 const addonArgs = quiet
                     ? ['--quiet', '--source', source, ...addonBaseArgs]
                     : ['--source', source, ...addonBaseArgs];
+                if (framework === 'all' && (allExtensions.length > 0 || index < allAddons.length - 1)) {
+                    addonArgs.push('--defer-rule-projection');
+                }
                 if (!mainIncludesAddons) {
                     const result = await runner.run('tools/agents/deploy-agents.mjs', addonArgs, captureOpts);
                     if (result.exitCode !== 0)
@@ -3727,10 +3956,9 @@ export class UseHandler {
             // Deploy all extensions from agentic/code/extensions/* (#1222).
             // Extensions are addon-shaped bundles (manifest type: "addon") that live
             // in a separate top-level dir to keep ops/sysops/itops/devops grouped.
-            // `aiwg use all` was previously silent about them, leaving 6 extension
-            // bundles undeployed even when the user explicitly asked for everything.
-            const allExtensions = await getAllExtensions(frameworkRoot);
-            for (const ext of allExtensions) {
+            // Kernel mode projects its shared rule set on the final framework/addon
+            // pass. Extension-only passes would repeat that same surface.
+            for (const [index, ext] of allExtensions.entries()) {
                 if (verbose) {
                     console.log('');
                     console.log(`Deploying ${ext} extension...`);
@@ -3739,9 +3967,12 @@ export class UseHandler {
                 const extArgs = quiet
                     ? ['--quiet', '--source', source, ...addonBaseArgs]
                     : ['--source', source, ...addonBaseArgs];
-                const result = await runner.run('tools/agents/deploy-agents.mjs', extArgs, captureOpts);
-                if (result.exitCode !== 0) {
-                    return result;
+                if (framework === 'all' && index < allExtensions.length - 1)
+                    extArgs.push('--defer-rule-projection');
+                if (!batchedOmpExtensions.includes(ext)) {
+                    const result = await runner.run('tools/agents/deploy-agents.mjs', extArgs, captureOpts);
+                    if (result.exitCode !== 0)
+                        return result;
                 }
                 try {
                     await registerSourceCliCommands({
@@ -3810,7 +4041,7 @@ export class UseHandler {
                     projectPath: target,
                     dryRun,
                     verbose,
-                    deployVersion: (await getVersionInfo()).version,
+                    deployVersion: deploymentVersion(frameworkRoot),
                 });
                 if (verbose && translationResult.translated.length > 0) {
                     ui.success(`Translated ${translationResult.translated.length} skills → commands (${provider})`);
@@ -3861,7 +4092,7 @@ export class UseHandler {
                         projectPath: target,
                         dryRun,
                         verbose,
-                        deployVersion: (await getVersionInfo()).version,
+                        deployVersion: deploymentVersion(frameworkRoot),
                         nameFilter: shouldMirrorKernelCommandSkill,
                     });
                     if (verbose && kernel.translated.length > 0) {
@@ -4177,11 +4408,10 @@ export class UseHandler {
         // failed deploys produce shorter indexes, never broken links.
         //
         // Operators opt out via --no-context-files / --no-aiwg-md / --no-agents-md.
-        if (!dryRun) {
-            const skipContext = remainingArgs.includes('--no-context-files');
-            const skipWorkspaceMd = skipContext || remainingArgs.includes('--no-workspace-md');
-            const skipAiwgMd = skipContext || remainingArgs.includes('--no-aiwg-md');
-            const skipAgentsMd = skipContext || remainingArgs.includes('--no-agents-md');
+        if (!dryRun && !remainingArgs.includes('--no-context-files')) {
+            const skipWorkspaceMd = remainingArgs.includes('--no-workspace-md');
+            const skipAiwgMd = remainingArgs.includes('--no-aiwg-md');
+            const skipAgentsMd = remainingArgs.includes('--no-agents-md');
             const forceContext = remainingArgs.includes('--force-context-files');
             try {
                 const paths = getProviderPaths(provider);
@@ -4191,7 +4421,7 @@ export class UseHandler {
                     skills: paths.skills,
                     behaviors: paths.behaviors,
                 });
-                const ctxResult = await generateContextFiles({
+                const ctxResult = await generateDeploymentContextFiles({
                     provider: provider,
                     projectPath: target,
                     sections,
@@ -4245,10 +4475,8 @@ export class UseHandler {
                 }
             }
             catch (err) {
-                // Non-fatal: context-pipeline emission must not block deployment.
-                // Operator can re-run aiwg use to retry.
                 const msg = err instanceof Error ? err.message : String(err);
-                console.error(`Warning: context-pipeline emission failed: ${msg}`);
+                return { exitCode: 1, message: `Context generation failed: ${msg}` };
             }
         }
         span.end('use:complete', { framework });