@aiwg/cli 2026.10.3 → 2026.10.4

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

@@ -507,9 +507,14 @@ Options:
   --bundle <name>       Limit deployment verification to one bundle
   --scope <scope>       Verification scope: project or user
   --user                Alias for --scope user
+  --qualify             With --probe-workers, record installation and configured model/role approval
+  --yes                 Confirm worker qualification without a terminal
+  --dry-run             With --probe-workers, preview qualification without writes
+  --cli NAME            Limit worker probes/qualification to one configured CLI
+  --decision-offload    Show offline advisory decision readiness and adoption report
   --probe-workers       Run bounded worker CLI version probes (default: config-only, no subprocess)
   --project-local       Include project-local artifact diagnostics
-  --json                Emit machine-readable output (with --probe-workers: one worker-probe record per CLI; with --deployment: deployment verification)
+  --json                Emit machine-readable output (with --probe-workers: one worker-probe record per CLI; with --deployment: deployment verification; with --decision-offload: offline snapshot)
   --verbose, -v         Include verbose diagnostics
   --help, -h            Show this help
 `;
@@ -537,10 +542,10 @@ export const doctorHandler = {
     async execute(ctx) {
         // Validate before any early-return mode: deployment and user-scope doctor
         // never invoke doctor.mjs, so they must enforce the same flag contract.
-        const valueFlags = ['--provider', '--bundle', '--scope', '--context-baseline', '--context-budget-tokens'];
+        const valueFlags = ['--provider', '--bundle', '--scope', '--context-baseline', '--context-budget-tokens', '--cli'];
         const knownFlags = new Set([
-            ...valueFlags, '--all-providers', '--probe-workers', '--no-budget-check', '--strict-context', '--json',
-            '--deployment', '--user', '--verbose', '-v', '--project-local', '--quiet', '--help', '-h',
+            ...valueFlags, '--all-providers', '--probe-workers', '--qualify', '--yes', '--dry-run', '--no-budget-check', '--strict-context', '--json',
+            '--decision-offload', '--deployment', '--user', '--verbose', '-v', '--project-local', '--quiet', '--help', '-h',
         ]);
         const hasSwitch = (name) => hasPositionalOrSwitch(ctx.args, name, valueFlags);
         const values = new Map();
@@ -558,8 +563,14 @@ export const doctorHandler = {
                     throw new Error(`Unknown flag: ${name}`);
                 }
             }
-            if (hasSwitch('--json') && !hasSwitch('--probe-workers') && !hasSwitch('--deployment')) {
-                throw new Error('--json requires --probe-workers or --deployment');
+            if (hasSwitch('--decision-offload') && (hasSwitch('--probe-workers') || hasSwitch('--deployment') || hasSwitch('--user') || values.get('--scope') !== undefined)) {
+                throw new Error('--decision-offload is a separate offline mode; do not combine it with worker, deployment or user-scope checks');
+            }
+            if (['--qualify', '--cli', '--yes', '--dry-run'].some(flag => hasSwitch(flag) || values.get(flag)) && !hasSwitch('--probe-workers')) {
+                throw new Error('--qualify, --cli, --yes and --dry-run require --probe-workers');
+            }
+            if (hasSwitch('--json') && !hasSwitch('--probe-workers') && !hasSwitch('--deployment') && !hasSwitch('--decision-offload')) {
+                throw new Error('--json requires --probe-workers or --deployment or --decision-offload');
             }
         }
         catch (error) {
@@ -578,11 +589,13 @@ export const doctorHandler = {
                 bundle: values.get('--bundle'),
                 scope: scopeValue,
             }, ctx.frameworkRoot);
+            const { rulePinState } = await import('../../rules/pin-state.js');
+            const pins = rulePinState(ctx.cwd, ctx.frameworkRoot);
             return {
                 exitCode: result.exitCode,
                 message: hasSwitch('--json')
-                    ? JSON.stringify(result, null, 2)
-                    : renderUseDeploymentResult(result),
+                    ? JSON.stringify({ ...result, rule_pins: { rules: pins.rules, warnings: pins.warnings } }, null, 2)
+                    : renderUseDeploymentResult(result) + '\n' + pins.rules.map(rule => `${rule.name}: pinned kernel (canonical ${rule.canonical_activation})`).concat(pins.warnings).join('\n'),
                 rawOutput: hasSwitch('--json'),
             };
         }
@@ -595,7 +608,7 @@ export const doctorHandler = {
         if (userScopeRequested && !hasSwitch('--probe-workers')) {
             return await runUserScopeDoctor(hasSwitch('--verbose') || hasSwitch('-v'));
         }
-        const frameworkRoot = await getFrameworkRoot();
+        const frameworkRoot = hasSwitch('--decision-offload') ? ctx.frameworkRoot : await getFrameworkRoot();
         const runner = createScriptRunner(frameworkRoot);
         // Run core doctor diagnostics
         const result = await runner.run('tools/cli/doctor.mjs', ctx.args, { cwd: ctx.cwd });
@@ -603,7 +616,7 @@ export const doctorHandler = {
         // printed exactly one JSON document (or a usage error) on its own
         // stdio — every section below writes human-readable text, so returning
         // here keeps stdout to the JSON document alone.
-        if (hasSwitch('--json') || result.exitCode === 2)
+        if (hasSwitch('--decision-offload') || hasSwitch('--json') || hasSwitch('--qualify') || hasSwitch('--cli') || hasSwitch('--dry-run') || result.exitCode === 2)
             return result;
         let agentSkillsFailure = false;
         try {
@@ -801,6 +814,9 @@ export const contextFirewallHandler = {
     description: 'Audit provider context and manage its reviewed baseline',
     category: 'maintenance',
     aliases: ['-context-firewall', '--context-firewall'],
+    async help() {
+        return { exitCode: 0, message: CONTEXT_FIREWALL_HELP, rawOutput: true };
+    },
     async execute(ctx) {
         if (ctx.args.includes('--help') || ctx.args.includes('-h')) {
             return { exitCode: 0, message: CONTEXT_FIREWALL_HELP };

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

@@ -55,6 +55,9 @@ function collectFingerprint(versionInfo) {
     const loggerInfo = getLoggerInfo();
     const fp = {
         version: versionInfo.version,
+        launcherVersion: versionInfo.launcherVersion ?? versionInfo.version,
+        runtimeVersion: versionInfo.runtimeVersion ?? versionInfo.version,
+        runtimePath: versionInfo.runtimePath ?? versionInfo.packageRoot,
         channel: versionInfo.devMode ? 'dev' : versionInfo.channel,
         packageRoot: versionInfo.packageRoot,
         node: process.version,
@@ -132,6 +135,11 @@ async function displayVersion(opts) {
     }
     ui.blank();
     console.log(`  ${ui.brandMark()} ${ui.bold('aiwg')}  ${ui.bold(fp.version)}  ${ui.channelLabel(fp.channel)}`);
+    if (info.devMode || fp.launcherVersion !== fp.runtimeVersion) {
+        ui.dim(`    launcher: ${fp.launcherVersion}`);
+        ui.dim(`    runtime: ${fp.runtimeVersion}`);
+        ui.dim(`    runtime path: ${fp.runtimePath}`);
+    }
     if (!opts.verbose) {
         if (fp.git)
             ui.dim(`    git: ${fp.git.sha} (${fp.git.branch})`);

package/dist/src/cli/router.js

@@ -75,6 +75,15 @@ export function getHookRegistry() {
  * ```
  */
 export async function run(args, options = {}) {
+    // Scheduled index maintenance has no hooks, telemetry, or deployment side effects.
+    if (args[0] === 'index' && args[1] === 'refresh'
+        && !args.includes('--help') && !args.includes('-h')) {
+        const { runIndexRefresh } = await import('../artifacts/index-refresh.js');
+        const report = await runIndexRefresh(args.slice(2), options.cwd ?? process.cwd(), options.signal);
+        if (report.totals.errors)
+            process.exit(1);
+        return;
+    }
     const started = process.hrtime.bigint();
     const registry = await initRouter();
     // Normalize `help <command>` into the same non-executing help path.
@@ -320,7 +329,12 @@ async function logCommandInvocation(input) {
  * @returns Handler context
  */
 async function buildContext(args, rawArgs, options) {
-    const frameworkRoot = await getFrameworkRoot({ createIfMissing: !args.includes('--dry-run') });
+    const readOnlyRuleInventory = rawArgs[0] === 'rules' && ['inventory', 'list'].includes(args[0]);
+    const readOnlyOffloadReport = (['doctor', '-doctor', '--doctor'].includes(rawArgs[0] ?? '') && args.includes('--decision-offload'))
+        || (rawArgs[0] === 'steward' && args[0] === 'decision-offload');
+    const frameworkRoot = await getFrameworkRoot({
+        createIfMissing: !args.includes('--dry-run') && !readOnlyRuleInventory && !readOnlyOffloadReport,
+    });
     const ctx = {
         args,
         rawArgs,

package/dist/src/cli/services/deployment-verification.js

@@ -1,5 +1,6 @@
 import { access, readFile, readdir, stat } from 'node:fs/promises';
 import path from 'node:path';
+import { loadPrebuiltDeploymentIndex } from '../../artifacts/prebuilt-deployment.js';
 import { loadGraphIndexFile } from '../../artifacts/index-reader.js';
 import { readAiwgConfig } from '../../config/aiwg-config.js';
 import { readUserRegistry } from '../../config/user-registry.js';
@@ -102,7 +103,7 @@ export function normalizeFrameworkDiscoveryInventory(stats) {
     };
 }
 function frameworkDiscoveryInventory(frameworkRoot) {
-    const stats = loadGraphIndexFile(frameworkRoot, 'stats.json', 'framework');
+    const stats = loadPrebuiltDeploymentIndex(frameworkRoot, { strictRoot: true })?.stats ?? loadGraphIndexFile(frameworkRoot, 'stats.json', 'framework');
     return stats ? normalizeFrameworkDiscoveryInventory(stats) : null;
 }
 const BUNDLE_INDEX_TOKENS = {
@@ -510,9 +511,11 @@ export async function verifyProviderDeployment(options) {
     const frameworkBundles = options.requestedBundles.filter((bundle) => !projectLocalBundles.includes(bundle));
     const indexesToVerify = [];
     if (frameworkBundles.length > 0) {
+        const prebuilt = loadPrebuiltDeploymentIndex(options.frameworkRoot, { strictRoot: true });
         indexesToVerify.push({
-            index: loadGraphIndexFile(options.frameworkRoot, 'metadata.json', 'framework'),
-            stats: loadGraphIndexFile(options.frameworkRoot, 'stats.json', 'framework'),
+            index: prebuilt?.index ?? loadGraphIndexFile(options.frameworkRoot, 'metadata.json', 'framework'),
+            stats: prebuilt?.stats ?? loadGraphIndexFile(options.frameworkRoot, 'stats.json', 'framework'),
+            prebuiltValidated: Boolean(prebuilt),
             graph: 'framework',
             bundles: frameworkBundles,
         });
@@ -521,11 +524,12 @@ export async function verifyProviderDeployment(options) {
         const graph = options.scope === 'user' ? 'user' : 'project';
         indexesToVerify.push({
             index: loadGraphIndexFile(options.projectRoot, 'metadata.json', graph),
+            stats: loadGraphIndexFile(options.projectRoot, 'stats.json', graph),
             graph,
             bundles: projectLocalBundles,
         });
     }
-    for (const { index, stats, graph, bundles } of indexesToVerify) {
+    for (const { index, stats, graph, bundles, prebuiltValidated } of indexesToVerify) {
         if (!index || !index.entries || Object.keys(index.entries).length === 0) {
             findings.push(finding(normalized, `index-unreadable:${graph}`, 'blocking', `The ${graph} capability index is missing, unreadable, or empty.`, `Run aiwg index build --graph ${graph}, then re-run the same aiwg use command.`));
             continue;
@@ -550,11 +554,14 @@ export async function verifyProviderDeployment(options) {
         if (!surfacePresent) {
             findings.push(finding(normalized, `index-surface-missing:${graph}`, 'blocking', `The ${graph} capability index does not contain the requested bundle surface.`, `Rebuild the ${graph} index from the selected AIWG source and re-run aiwg use.`, { requestedBundles: bundles, entryCount: entryPaths.length }));
         }
-        if (options.invocationStartedAt) {
-            const builtAt = Date.parse(index.builtAt);
+        if (options.invocationStartedAt && !prebuiltValidated) {
+            // No-op builds preserve metadata bytes and record the refresh in stats.
+            const refreshedAt = Math.max(...[index.builtAt, stats?.builtAt]
+                .map((timestamp) => Date.parse(timestamp ?? ''))
+                .filter(Number.isFinite));
             const startedAt = Date.parse(options.invocationStartedAt);
-            if (!Number.isFinite(builtAt) || builtAt + 2_000 < startedAt) {
-                findings.push(finding(normalized, `index-stale:${graph}`, 'blocking', `The ${graph} capability index was not refreshed during this deployment.`, `Re-run aiwg use after correcting the ${graph} index build failure.`, { graph, builtAt: index.builtAt, invocationStartedAt: options.invocationStartedAt }));
+            if (!Number.isFinite(refreshedAt) || refreshedAt + 2_000 < startedAt) {
+                findings.push(finding(normalized, `index-stale:${graph}`, 'blocking', `The ${graph} capability index was not refreshed during this deployment.`, `Re-run aiwg use after correcting the ${graph} index build failure.`, { graph, builtAt: index.builtAt, statsBuiltAt: stats?.builtAt, invocationStartedAt: options.invocationStartedAt }));
             }
         }
     }
@@ -569,7 +576,7 @@ export async function verifyProviderDeployment(options) {
         }
         const requiredContext = [
             path.join(options.projectRoot, 'WORKSPACE.md'),
-            path.join(options.projectRoot, 'AIWG.md'),
+            ...(definition?.paths.contextFiles.aiwgMd === false ? [] : [path.join(options.projectRoot, 'AIWG.md')]),
             path.join(options.projectRoot, '.aiwg', 'AIWG.md'),
         ];
         for (const contextPath of requiredContext) {
@@ -773,9 +780,12 @@ export async function buildDeploymentStatusProbe(projectRoot, frameworkRoot = pr
     const notConfigured = result.requestedBundles.length === 0
         && result.findings.length > 0
         && result.findings.every((item) => item.id === 'deployment-not-configured');
+    const { rulePinState } = await import('../../rules/pin-state.js');
+    const rulePins = rulePinState(projectRoot, frameworkRoot);
     const engaged = result.outcome === 'ready' || result.outcome === 'ready-restart-required' || result.outcome === 'degraded';
     return {
         schema: 'aiwg.status.probe.v1',
+        rule_pins: { rules: rulePins.rules, warnings: rulePins.warnings },
         generated_at: result.generatedAt,
         project_root: result.projectRoot,
         engaged,

package/dist/src/cli/services/provider-prepare-coordinator.js

@@ -0,0 +1,24 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+export async function prepareProviderDeployments(frameworkRoot, jobs) {
+    const deployerUrl = pathToFileURL(path.join(frameworkRoot, 'tools', 'agents', 'deploy-agents.mjs')).href;
+    const deployer = await import(deployerUrl);
+    // Commands-to-skills migration is interactive and changes provider inputs.
+    // Run it serially in the coordinator before the shared snapshot is created;
+    // finalization then only applies post-deploy mirrors/pruning/config writes.
+    for (const job of jobs)
+        await deployer.main(job.args, { preflightOnly: true });
+    const url = pathToFileURL(path.join(frameworkRoot, 'tools', 'agents', 'providers', 'provider-prepare-coordinator.mjs')).href;
+    const coordinator = await import(url);
+    const sourceIndex = jobs[0]?.args.findIndex(arg => arg === '--source') ?? -1;
+    const srcRoot = sourceIndex >= 0 && jobs[0]?.args[sourceIndex + 1]
+        ? path.resolve(jobs[0].args[sourceIndex + 1])
+        : frameworkRoot;
+    return coordinator.prepareProviderDeployments({ srcRoot, jobs, maxConcurrency: 2 });
+}
+export async function finalizePreparedProvider(frameworkRoot, args) {
+    const url = pathToFileURL(path.join(frameworkRoot, 'tools', 'agents', 'deploy-agents.mjs')).href;
+    const deployer = await import(url);
+    await deployer.main(args, { finalizeOnly: true });
+}
+//# sourceMappingURL=provider-prepare-coordinator.js.map

package/dist/src/cli/skill-usage.js

@@ -3,7 +3,7 @@ import { createReadStream, existsSync } from 'fs';
 import { createHash } from 'crypto';
 import { createInterface } from 'readline';
 import path from 'path';
-import os from 'os';
+import { getUserStateDir } from '../config/user-state.js';
 import { readAiwgConfig } from '../config/aiwg-config.js';
 import { PROJECT_AIWG_LOCATION_FILE, projectAiwgPath, projectControlPath, } from '../config/project-artifacts.js';
 const DEFAULT_MAX_BYTES = 1_048_576;
@@ -487,8 +487,7 @@ function resolveUsagePath(scope, projectRoot, env) {
             return null;
         return projectAiwgPath(projectRoot, 'telemetry', 'skill-usage.jsonl');
     }
-    const stateHome = env.XDG_STATE_HOME || path.join(os.homedir(), '.local', 'state');
-    return path.join(stateHome, 'aiwg', 'skill-usage.jsonl');
+    return path.join(getUserStateDir(env), 'skill-usage.jsonl');
 }
 async function appendBoundedJsonl(filePath, event, maxBytes) {
     await mkdir(path.dirname(filePath), { recursive: true });

package/dist/src/config/aiwg-config.js

@@ -1,3 +1,4 @@
+import { validateDecisionConfig } from './decision-config.js';
 /**
  * Project-Level AIWG Config
  *
@@ -8,8 +9,13 @@
  *
  * @implements #621
  */
+import { validateImportExclusions } from '../sessions/import-exclusions.js';
 import { resolveDispatchHostThresholds } from './dispatch-thresholds-runtime.mjs';
 export { DEFAULT_DISPATCH_HOST_THRESHOLDS, resolveDispatchHostThresholds } from './dispatch-thresholds-runtime.mjs';
+import { validateIndexGraphOverrides } from './index-graph-overrides.js';
+import { DEFAULT_RULES_INLINE_BUDGET_TOKENS } from '../rules/inline-budget.mjs';
+export { validateRulesConfig, resolveRulesInlineBudget } from '../rules/inline-budget.mjs';
+import { loadRulePinConfigs, installedRuleCapabilities, validateRulePinCapabilities } from '../rules/pins.mjs';
 import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
 import { readFileSync, existsSync } from 'node:fs';
@@ -297,7 +303,7 @@ export function resolveWorkerGroupInstallation(parallelism, installationId, regi
  * `options.aiwgHome`, when provided, is passed through to `ConfigLoader`
  * unchanged — it never reads or writes `process.env.AIWG_HOME`. Omitting it
  * keeps `ConfigLoader`'s own default precedence (`AIWG_HOME` env, else the
- * user-home install).
+ * running package root).
  */
 export async function validateWorkerConfigCandidate(projectDir, config, options) {
     const errors = validateParallelismConfig(config.parallelism);
@@ -456,37 +462,7 @@ export function validateIndexConfig(index) {
         errors.push(`index.graphBackend: must be one of ${GRAPH_BACKENDS.join(' | ')}`);
     }
     const isStringArray = (v) => Array.isArray(v) && v.every((x) => typeof x === 'string');
-    const graphOverrides = indexObject.graphOverrides;
-    if (graphOverrides !== undefined) {
-        if (typeof graphOverrides !== 'object' || graphOverrides === null || Array.isArray(graphOverrides)) {
-            errors.push('index.graphOverrides: must be an object mapping supported built-in graph names to overrides');
-        }
-        else {
-            for (const [name, rawOverride] of Object.entries(graphOverrides)) {
-                const where = `index.graphOverrides.${name}`;
-                if (name !== 'codebase') {
-                    errors.push(`${where}: unsupported built-in graph override (supported: codebase)`);
-                    continue;
-                }
-                if (typeof rawOverride !== 'object' || rawOverride === null || Array.isArray(rawOverride)) {
-                    errors.push(`${where}: must be an object`);
-                    continue;
-                }
-                const override = rawOverride;
-                for (const field of Object.keys(override)) {
-                    if (field !== 'scanDirs' && field !== 'extensions') {
-                        errors.push(`${where}.${field}: unknown field (supported: scanDirs, extensions)`);
-                    }
-                }
-                if (override.scanDirs !== undefined && (!isStringArray(override.scanDirs) || override.scanDirs.length === 0)) {
-                    errors.push(`${where}.scanDirs: must be a non-empty array of strings`);
-                }
-                if (override.extensions !== undefined && (!isStringArray(override.extensions) || override.extensions.length === 0)) {
-                    errors.push(`${where}.extensions: must be a non-empty array of strings`);
-                }
-            }
-        }
-    }
+    errors.push(...validateIndexGraphOverrides(indexObject.graphOverrides));
     const graphs = indexObject.graphs;
     if (graphs === undefined)
         return errors; // index with no graphs is permissible
@@ -973,6 +949,7 @@ export function emptyConfig(providers = ['claude']) {
             threatAssessment: defaultThreatAssessmentConfig(),
         },
         artifact_outputs: defaultArtifactOutputs(),
+        rules: { inline_budget_tokens: DEFAULT_RULES_INLINE_BUDGET_TOKENS },
         delivery: {
             mode: 'pr-required',
             default_branch: 'main',
@@ -1058,6 +1035,30 @@ export async function readAiwgConfigCandidate(projectDir) {
         parsed.installed = {};
     if (!parsed.scripts)
         parsed.scripts = {};
+    if (parsed.sessions !== undefined && (parsed.sessions === null || typeof parsed.sessions !== 'object' || Array.isArray(parsed.sessions)
+        || (parsed.sessions.codex_roots !== undefined && (!Array.isArray(parsed.sessions.codex_roots)
+            || !parsed.sessions.codex_roots.every((root) => typeof root === 'string' && root.trim().length > 0))))) {
+        throw new Error('sessions.codex_roots must be an array of non-empty paths');
+    }
+    if (parsed.sessions?.discovery_manifests !== undefined && (!Array.isArray(parsed.sessions.discovery_manifests)
+        || !parsed.sessions.discovery_manifests.every((file) => typeof file === 'string' && file.trim().length > 0))) {
+        throw new Error('sessions.discovery_manifests must be an array of non-empty paths');
+    }
+    if (parsed.sessions?.import !== undefined) {
+        const limits = parsed.sessions.import;
+        if (limits === null || typeof limits !== 'object' || Array.isArray(limits)) {
+            throw new Error('sessions.import must be an object');
+        }
+        if (limits.exclude !== undefined)
+            validateImportExclusions(limits.exclude);
+        for (const key of ['max_record_bytes', 'max_source_bytes']) {
+            const value = limits[key];
+            const minimum = key === 'max_source_bytes' ? 0 : 1;
+            if (value !== undefined && (typeof value !== 'number' || !Number.isSafeInteger(value) || value < minimum)) {
+                throw new Error(`sessions.import.${key} must be a ${minimum ? 'positive' : 'non-negative'} integer`);
+            }
+        }
+    }
     const externalLinkErrors = validateExternalLinks(parsed.externalLinks);
     if (externalLinkErrors.length > 0) {
         throw new Error(`Invalid .aiwg/aiwg.config:\n${externalLinkErrors.join('\n')}`);
@@ -1076,6 +1077,8 @@ export async function readAiwgConfigCandidate(projectDir) {
         ...validateThreatAssessmentConfig(parsed.security?.threatAssessment),
         ...validateProjectConfig(parsed.project),
         ...validateParallelismConfig(parsed.parallelism),
+        ...validateDecisionConfig(parsed.decision),
+        ...validateRulePinCapabilities(parsed.rules, installedRuleCapabilities(loadRulePinConfigs(projectDir, parsed)), loadRulePinConfigs(projectDir, parsed).user.rules?.pin_groups),
     ];
     if (threatAssessmentErrors.length > 0) {
         throw new Error(`Invalid .aiwg/aiwg.config:\n${threatAssessmentErrors.join('\n')}`);
@@ -1119,10 +1122,46 @@ export async function readAiwgConfig(projectDir, options) {
  * sync so split-root health remains deterministic.
  */
 export async function writeAiwgConfig(projectDir, config) {
+    // Uninstall is an explicit capability change. Retire project selectors for
+    // removed capabilities before strict validation, and tell the operator.
+    const previousFile = getConfigPath(projectDir);
+    let previous = null;
+    if (existsSync(previousFile)) {
+        try {
+            previous = JSON.parse(readFileSync(previousFile, 'utf8'));
+        }
+        catch (error) {
+            if (!(error instanceof SyntaxError))
+                throw error;
+        }
+    }
+    const pinConfigs = loadRulePinConfigs(projectDir, config);
+    const currentCapabilities = new Set(installedRuleCapabilities(pinConfigs));
+    const removed = previous ? installedRuleCapabilities({ ...pinConfigs, project: previous }).filter(id => !currentCapabilities.has(id)) : [];
+    if (removed.length && (config.rules?.always_load?.length || Object.keys(config.rules?.pin_groups ?? {}).length)) {
+        const removedSet = new Set(removed);
+        const rules = config.rules;
+        const userGroups = loadRulePinConfigs(projectDir, config).user.rules?.pin_groups ?? {};
+        const pinGroups = Object.fromEntries(Object.entries(rules.pin_groups ?? {})
+            .map(([name, ids]) => [name, ids.filter(id => !removedSet.has(id))]).filter(([, ids]) => ids.length));
+        const selectors = (rules.always_load ?? []).flatMap(selector => {
+            if (selector.group && ((!Object.hasOwn(pinGroups, selector.group) && Object.hasOwn(rules.pin_groups ?? {}, selector.group))
+                || (!Object.hasOwn(pinGroups, selector.group) && userGroups[selector.group]?.some(id => removedSet.has(id)))))
+                return [];
+            if (!selector.capabilities)
+                return [selector];
+            const capabilities = selector.capabilities.filter(id => !removedSet.has(id));
+            return capabilities.length ? [{ ...selector, capabilities }] : [];
+        });
+        config = { ...config, rules: { ...config.rules, pin_groups: pinGroups, always_load: selectors } };
+        console.warn(`Uninstalled ${removed.join(', ')}: their rules leave the effective pinned set; retired project capability selectors/groups. User pins remain visible as inactive warnings.`);
+    }
     const threatAssessmentErrors = [
         ...validateThreatAssessmentConfig(config.security?.threatAssessment),
         ...validateProjectConfig(config.project),
         ...validateParallelismConfig(config.parallelism),
+        ...validateDecisionConfig(config.decision),
+        ...validateRulePinCapabilities(config.rules, installedRuleCapabilities(loadRulePinConfigs(projectDir, config)), loadRulePinConfigs(projectDir, config).user.rules?.pin_groups),
     ];
     if (threatAssessmentErrors.length > 0) {
         throw new Error(`Invalid .aiwg/aiwg.config:\n${threatAssessmentErrors.join('\n')}`);
@@ -1379,13 +1418,24 @@ export function validateWorkerGroupReferences(parallelism, selection, qualifiedR
                 errors.push(`OG_CONFIG_REFERENCE /defaults/workerSelection/roleGuidance/${role}/groups: Unknown group ${group}`);
     }
     if (qualifiedRoles)
-        for (const [id, group] of Object.entries(parallelism.groups ?? {})) {
-            for (const role of group.requiredRoles ?? [])
-                if (!group.members.some(m => m.enabled !== false && parallelism.clis?.[m.cli]?.enabled !== false && m.roles.includes(role) && qualifiedRoles[`${id}/${m.id}`]?.includes(role)))
-                    errors.push(`OG_ADAPTER_UNQUALIFIED /parallelism/groups/${id}/requiredRoles: No qualified route covers ${role}`);
-        }
+        errors.push(...validateWorkerGroupQualifications(parallelism, qualifiedRoles)
+            .map(diagnostic => `${diagnostic.code} ${diagnostic.pointer}: ${diagnostic.message}`));
     return errors;
 }
+/** Structured qualification gaps retain role scope for readiness projections. */
+export function validateWorkerGroupQualifications(parallelism, qualifiedRoles) {
+    const diagnostics = [];
+    for (const [id, group] of Object.entries(parallelism.groups ?? {})) {
+        for (const role of group.requiredRoles ?? []) {
+            if (!group.members.some(m => m.enabled !== false && parallelism.clis?.[m.cli]?.enabled !== false
+                && m.roles.includes(role) && qualifiedRoles[`${id}/${m.id}`]?.includes(role))) {
+                diagnostics.push({ code: 'OG_ADAPTER_UNQUALIFIED', pointer: `/parallelism/groups/${id}/requiredRoles`,
+                    message: `No qualified route covers ${role}`, roles: [role] });
+            }
+        }
+    }
+    return diagnostics;
+}
 /** A configured hard ceiling is eligible only where a qualified control enforces it. */
 export function validateWorkerBudgetEnforcement(budgets, enforceable) {
     if (budgets?.enforcement !== 'hard')