@aiwg/cli 2026.9.7 → 2026.9.9

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

@@ -35,6 +35,92 @@ export const WORKSPACE_REPO_ACTIONS = [
     'service-action',
     'destructive',
 ];
+export const PROJECT_CLASSIFICATIONS = ['private', 'sanitized', 'public'];
+/** Normalize the string-or-object `project` field to the object form. */
+/**
+ * Validate the `project` block. Accepts the bare-string form unconditionally so
+ * existing configs keep loading (#2535).
+ */
+export function validateProjectConfig(project) {
+    const errors = [];
+    if (project === undefined || typeof project === 'string')
+        return errors;
+    if (typeof project !== 'object' || project === null || Array.isArray(project)) {
+        errors.push('project: must be a string (name) or an object');
+        return errors;
+    }
+    const value = project;
+    if (value.classification !== undefined
+        && !PROJECT_CLASSIFICATIONS.includes(value.classification)) {
+        errors.push(`project.classification: must be one of ${PROJECT_CLASSIFICATIONS.join(' | ')}`);
+    }
+    for (const key of ['name', 'description']) {
+        if (value[key] !== undefined && typeof value[key] !== 'string') {
+            errors.push(`project.${key}: must be a string`);
+        }
+    }
+    if (value.pii !== undefined && typeof value.pii !== 'boolean') {
+        errors.push('project.pii: must be a boolean');
+    }
+    if (value.handling !== undefined) {
+        if (typeof value.handling !== 'object' || value.handling === null || Array.isArray(value.handling)) {
+            errors.push('project.handling: must be an object');
+        }
+        else {
+            const handling = value.handling;
+            for (const key of ['excerptable', 'publishable', 'mirror']) {
+                if (handling[key] !== undefined && typeof handling[key] !== 'boolean') {
+                    errors.push(`project.handling.${key}: must be a boolean`);
+                }
+            }
+        }
+    }
+    return errors;
+}
+export function resolveProject(project) {
+    if (project === undefined)
+        return undefined;
+    if (typeof project === 'string')
+        return { name: project };
+    return project;
+}
+/**
+ * Handling defaults derived from the classification when not stated explicitly.
+ * A `private` repo is closed by default; anything else stays permissive, so
+ * declaring a classification never silently tightens an existing project.
+ */
+export function resolveProjectHandling(project) {
+    const closed = project?.classification === 'private';
+    return {
+        excerptable: project?.handling?.excerptable ?? !closed,
+        publishable: project?.handling?.publishable ?? !closed,
+        mirror: project?.handling?.mirror ?? !closed,
+    };
+}
+/** Deprecated spellings mapped to their current value. */
+export const FORCE_PUSH_POLICY_ALIASES = {
+    'main-only-blocked': 'own-branch-only',
+};
+/**
+ * The rename also narrowed the permission: `main-only-blocked` allowed force-push on
+ * *any* feature branch, `own-branch-only` restricts it to the agent's own. Callers
+ * surface this rather than migrating silently, because accepting the alias quietly
+ * would change what an agent is permitted to do.
+ */
+export const FORCE_PUSH_POLICY_ALIAS_NOTE = "'main-only-blocked' is a deprecated alias for 'own-branch-only'. The permission also narrowed: "
+    + 'the old value allowed force-push on any feature branch, the new one only on the agent\'s own branch.';
+/**
+ * Normalize a force-push policy, mapping deprecated spellings forward. Returns the
+ * canonical value and the alias it came from, if any.
+ */
+export function normalizeForcePushPolicy(value) {
+    if (value === undefined)
+        return { policy: undefined };
+    const alias = FORCE_PUSH_POLICY_ALIASES[value];
+    if (alias)
+        return { policy: alias, deprecatedFrom: value };
+    return { policy: value };
+}
 const DEFAULT_BRANCH_NAMING = {
     prefix_by_type: {
         feat: 'feat/{issue}-{slug}',
@@ -70,7 +156,7 @@ export function resolveDelivery(delivery) {
         committer: delivery?.committer,
         signing: delivery?.signing,
         release_signing: delivery?.release_signing,
-        force_push_policy: delivery?.force_push_policy ?? 'never',
+        force_push_policy: normalizeForcePushPolicy(delivery?.force_push_policy).policy ?? 'never',
         auto_close_issues: delivery?.auto_close_issues ?? true,
         issue_comment_on_cycle: delivery?.issue_comment_on_cycle ?? true,
     };
@@ -770,7 +856,10 @@ export async function readAiwgConfig(projectDir) {
     if (authorizationErrors.length > 0) {
         throw new Error(`Invalid .aiwg/aiwg.config:\n${authorizationErrors.map(item => item.message).join('\n')}`);
     }
-    const threatAssessmentErrors = validateThreatAssessmentConfig(parsed.security?.threatAssessment);
+    const threatAssessmentErrors = [
+        ...validateThreatAssessmentConfig(parsed.security?.threatAssessment),
+        ...validateProjectConfig(parsed.project),
+    ];
     if (threatAssessmentErrors.length > 0) {
         throw new Error(`Invalid .aiwg/aiwg.config:\n${threatAssessmentErrors.join('\n')}`);
     }
@@ -788,7 +877,10 @@ export async function readAiwgConfig(projectDir) {
  * sync so split-root health remains deterministic.
  */
 export async function writeAiwgConfig(projectDir, config) {
-    const threatAssessmentErrors = validateThreatAssessmentConfig(config.security?.threatAssessment);
+    const threatAssessmentErrors = [
+        ...validateThreatAssessmentConfig(config.security?.threatAssessment),
+        ...validateProjectConfig(config.project),
+    ];
     if (threatAssessmentErrors.length > 0) {
         throw new Error(`Invalid .aiwg/aiwg.config:\n${threatAssessmentErrors.join('\n')}`);
     }

package/dist/src/config/cli.js

@@ -142,6 +142,14 @@ async function handleSet(config, args) {
 // Set validates enum membership for known fields (delivery.mode,
 // delivery.merge_style, delivery.force_push_policy, remotes.issue_provider)
 // before writing.
+/** Deprecated values accepted on `set` and normalized to their current spelling. */
+const ENUM_ALIASES = {
+    'delivery.force_push_policy': { 'main-only-blocked': 'own-branch-only' },
+};
+/** Extra context printed alongside an alias normalization, where semantics also changed. */
+const ENUM_ALIAS_NOTES = {
+    'delivery.force_push_policy': "The permission also narrowed: the old value allowed force-push on any feature branch, the new one only on the agent's own branch.",
+};
 const ENUM_RULES = {
     'delivery.mode': ['direct', 'feature-branch', 'pr-required'],
     'delivery.merge_style': ['rebase-merge', 'squash', 'merge', 'fast-forward-only'],
@@ -210,8 +218,15 @@ async function projectConfigGet(key, args) {
 async function projectConfigSet(key, raw, args) {
     const { readAiwgConfig, writeAiwgConfig, getProjectDir, emptyConfig, validateExternalLinks, } = await import('./aiwg-config.js');
     const projectDir = getProjectDir(undefined, args);
-    // Validate enum fields before writing
+    // Validate enum fields before writing. Deprecated spellings normalize forward with a
+    // notice rather than failing, so a config written before a rename stays settable (#2532).
     const allowed = ENUM_RULES[key];
+    const aliased = ENUM_ALIASES[key]?.[raw];
+    if (aliased) {
+        process.stderr.write(`Note: '${raw}' is a deprecated alias for '${aliased}'; writing '${aliased}'.\n`
+            + (ENUM_ALIAS_NOTES[key] ? `      ${ENUM_ALIAS_NOTES[key]}\n` : ''));
+        raw = aliased;
+    }
     if (allowed && !allowed.includes(raw)) {
         throw new AiwgError({
             code: 'ERR_INVALID_VALUE',

package/dist/src/config/gitignore.js

@@ -24,6 +24,9 @@ const GITIGNORE_PROBE_BASENAME = '.aiwg-ignore-probe';
  */
 export const AIWG_RUNTIME_PATTERNS = [
     '.aiwg/working/',
+    // Transactional preimages written before AIWG rewrites operator files.
+    // Recoverable local evidence, not project content (#2542).
+    '.aiwg/backups/',
     // .aiwg/.index/ is the artifact graph index (JSON nodes/edges + checksum
     // manifest). It is a pure build artifact, fully regenerable from corpus
     // content via `aiwg index build --all`, so it is ignored rather than committed.
@@ -56,6 +59,8 @@ export const PROVIDER_CONVENTIONAL_PATTERNS = [
  */
 export const CLAUDE_SESSION_PATTERNS = [
     '.claude/settings.local.json',
+    // Timestamped backups AIWG writes before merging hook entries (#2542).
+    '.claude/settings.json.bak.*',
 ];
 /** All recommended patterns combined */
 export const ALL_RECOMMENDED_PATTERNS = [

package/dist/src/extensions/claude-hooks-installer.js

@@ -68,11 +68,17 @@ function normalizeHooks(raw) {
     return [{}, false];
 }
 /**
- * Detect whether the existing settings carries the AIWG signature
- * (any hook entry tagged `_aiwg_managed: true`). Accepts both the
+ * Detect whether the existing settings carries the AIWG signature — either a hook
+ * entry tagged `_aiwg_managed: true`, or the top-level `aiwg` stamp written when
+ * AIWG creates the file itself (tools/agents/providers/claude.mjs). Without the
+ * latter, a greenfield deploy backs up the settings.json it created seconds
+ * earlier and reports it as protected operator content (#2542). Accepts both the
  * current object form and the legacy array form.
  */
 function hasAiwgMarker(settings) {
+    const stamp = settings.aiwg;
+    if (stamp && typeof stamp === 'object')
+        return true;
     const hooksField = settings.hooks;
     if (!hooksField)
         return false;
@@ -167,7 +173,7 @@ export async function installAiwgHooks(opts) {
                 const backup = `${result.settingsPath}.bak.${new Date().toISOString().replace(/[:.]/g, '-')}`;
                 await fs.copyFile(result.settingsPath, backup);
                 result.backupPath = backup;
-                result.warnings.push(`Backed up pre-existing settings.json to ${backup}`);
+                result.warnings.push(`Backed up operator-authored settings.json to ${backup}`);
             }
         }
         catch (err) {
@@ -202,18 +208,28 @@ export async function installAiwgHooks(opts) {
             // those files no longer exist on disk after refresh, causing
             // `MODULE_NOT_FOUND` at `node:internal/modules/cjs/loader` on every
             // hook invocation. (Fixes regression report on Claude Code 2.1.157.)
+            // Match by `_aiwg_id` first, then by the script path. An entry invoking an
+            // AIWG-owned hook script without the managed tag is AIWG residue from an
+            // earlier install; appending a managed entry beside it registers the hook
+            // twice and runs it twice per event. Adopt it instead. (#2543)
             let updated = false;
             for (const group of groups) {
                 if (!Array.isArray(group.hooks))
                     continue;
                 for (const h of group.hooks) {
-                    if (h._aiwg_id !== hookId)
+                    const sameId = h._aiwg_id === hookId;
+                    const sameScript = typeof h.command === 'string' && h.command.includes(script);
+                    if (!sameId && !sameScript)
                         continue;
-                    if (h.command !== command || h.type !== 'command' || h._aiwg_managed !== true) {
+                    const adopting = !sameId && sameScript;
+                    if (h.command !== command || h.type !== 'command' || h._aiwg_managed !== true || h._aiwg_id !== hookId) {
                         h.type = 'command';
                         h.command = command;
                         h._aiwg_managed = true;
-                        result.warnings.push(`Refreshed stale ${event} → ${hookId} command path`);
+                        h._aiwg_id = hookId;
+                        result.warnings.push(adopting
+                            ? `Adopted pre-existing untagged ${event} → ${hookId} entry instead of registering a duplicate`
+                            : `Refreshed stale ${event} → ${hookId} command path`);
                     }
                     updated = true;
                 }

package/dist/src/lint/runner.js

@@ -29,6 +29,100 @@ function parseFrontmatter(content) {
     return result;
 }
 const DEFAULT_REFERENCE_PATTERN = '\\bREF-\\d{3,}\\b';
+/**
+ * Verification targets — things the inducting agent could have checked.
+ *
+ * Requiring one of these is what separates "the agent skipped a cheap check"
+ * from "the paper's own claim is unverified". Only the first is a provenance
+ * gap; the second is legitimate analysis, and #2523 explicitly does not ask
+ * agents to stop declaring limitations. Validated against a 2,544-reference
+ * corpus, where grammar-only matching made ~45% of hits paper-claim prose
+ * ("scaling behavior above 7B is unverified", "Not confirmed (34% vs 51%)").
+ */
+/**
+ * Split a markdown line into clauses.
+ *
+ * Corpus prose keeps whole paragraphs, bullet bodies and changelog table rows on
+ * a single line, so "same line" is far too coarse a scope for relating an
+ * unperformed action to its target. Sentence and cell boundaries are the unit
+ * that actually corresponds to one statement.
+ */
+function splitClauses(line) {
+    return line
+        .split(/(?<=[.;:!?])\s+|\s+\u2014\s+|\s+--\s+|\|/g)
+        .map((c) => c.trim())
+        .filter(Boolean);
+}
+export const DEFAULT_VERIFICATION_TARGETS = [
+    'openreview',
+    '(?:acl )?anthology',
+    'proceedings',
+    'camera[- ]ready',
+    'published version',
+    '\\bPMLR\\b',
+    '\\bDBLP\\b',
+    '\\bOpenAlex\\b',
+    'semantic scholar',
+    '\\bpubpeer\\b',
+    '\\bunpaywall\\b',
+    'retraction|correction notice|expression of concern',
+    'citation (?:census|count)',
+    'influential citation',
+    '\\bPDF\\b',
+    'full[- ]text',
+    '\\be-?print\\b',
+    '(?:code|project|dataset|repository|repo)\\s+(?:page|url|link|release|availability)',
+    '\\bvenue\\b',
+    '\\bacceptance\\b',
+    'source[_ ]type',
+];
+/**
+ * Phrases that assert a check was not performed. Drawn from real induction
+ * output — each of these has appeared in a corpus reference doc (#2523).
+ * Only counted when a verification target appears on the same line.
+ */
+export const DEFAULT_UNCERTAINTY_PATTERNS = [
+    '(?:was|were|is|are) not (?:retrieved|run|performed|attempted|fetched|queried|checked|acquired|probed|verified|confirmed)',
+    'not (?:retrieved|run|performed|attempted|fetched|queried|checked|acquired|probed|verified|confirmed)\\b',
+    // Requires the action to be stated as unperformed. Without the trailing verb
+    // this matched bare "no search" in unrelated prose and scope statements like
+    // "no exhaustive census is claimed", neither of which is a skipped check.
+    'no (?:\\w+[ -]){0,4}(?:quer(?:y|ies)|search|census|fetch|check|lookup|probe)(?:es|s)?\\s+(?:was |were )?(?:performed|run|attempted|made|conducted|executed)',
+    '\\b(?:is|remains) unverified\\b',
+    '\\bunconfirmed\\b',
+    'rests on .{0,60} rather than an independent',
+];
+export const DEFAULT_OBSTACLE_PATTERNS = [
+    '\\bHTTP\\s?[45]\\d{2}\\b',
+    '\\b(?:401|403|404|429|451|503)\\b',
+    'paywall',
+    'closed[- ]access',
+    'requires? (?:a )?(?:credential|token|API key|subscription|login|account)',
+    '\\b(?:HF_TOKEN|API[_ ]KEY)\\b',
+    'rate[- ]limit',
+    'anti[- ]bot',
+    'cloudflare',
+    'captcha',
+    'endpoint unknown',
+    'no (?:known )?endpoint',
+    // Obstacle vocabulary observed in a real corpus: these are named obstacles,
+    // so the statement is already a real outcome rather than a silent skip.
+    'proof[- ]of[- ]work',
+    'challenge (?:artifact|page|response)',
+    'returned challenge',
+    '\\bgated\\b',
+    'did not render',
+    'green OA',
+    // Explicit scope declarations: saying what is deliberately not claimed is an
+    // outcome, unlike omitting the check and not saying so.
+    'is not (?:claimed|asserted)',
+    'NOT (?:recorded|asserted) as',
+    'evidence boundary',
+    'completion_evidence',
+    'status:\\s*(?:incomplete|blocked)',
+    '\\b(?:queried|fetched|checked|probed|confirmed|resolved)\\s+(?:on\\s+)?\\d{4}-\\d{2}-\\d{2}',
+    '\\bdeferred\\b.{0,40}\\b(?:because|since|due to)\\b',
+];
 /**
  * Build a target-wide artifact ID index once per lint run.
  *
@@ -136,6 +230,50 @@ function runCheck(check, content, frontmatter, filePath, targetDir, allFiles, re
             }
             break;
         }
+        case 'unregistered-uncertainty': {
+            // An uncertainty written only into prose is invisible to the verification
+            // contract: it was never a declared check, so it never surfaces as
+            // `incomplete` and the "never report skipped verification as success" rule
+            // is never violated. Flag the bare form; accept it once a specific
+            // obstacle is named or an outcome is recorded (#2523).
+            const uncertainty = (check.uncertaintyPatterns ?? DEFAULT_UNCERTAINTY_PATTERNS)
+                .map((p) => new RegExp(p, 'i'));
+            const targets = (check.verificationTargets ?? DEFAULT_VERIFICATION_TARGETS)
+                .map((p) => new RegExp(p, 'i'));
+            const obstacle = (check.obstaclePatterns ?? DEFAULT_OBSTACLE_PATTERNS)
+                .map((p) => new RegExp(p, 'i'));
+            const within = check.obstacleWithinLines ?? 2;
+            const lines = content.split('\n');
+            for (let i = 0; i < lines.length; i++) {
+                // Both conditions must hold in the SAME CLAUSE: an unperformed action
+                // AND something the agent could have acted on. Without the target, the
+                // match is as likely to be the paper's own limitation, which must stay
+                // untouched. Without clause scoping, a long markdown line relates two
+                // unrelated clauses — real corpus prose puts whole paragraphs and
+                // changelog tables on one line, which produced most false positives.
+                const clause = splitClauses(lines[i]).find((c) => uncertainty.some((re) => re.test(c)) && targets.some((re) => re.test(c)));
+                if (!clause)
+                    continue;
+                // Look in the matching line and the following `within` lines: the
+                // obstacle normally sits in the same sentence or the next one.
+                const window = lines.slice(i, i + within + 1).join(' ');
+                if (obstacle.some((re) => re.test(window)))
+                    continue;
+                diagnostics.push({
+                    ruleId: '',
+                    ruleName: '',
+                    // Left unset so the rule's declared severity applies (see runRule).
+                    // This is a prose heuristic, so the shipped rule declares `warn`; an
+                    // operator can raise it to error once a corpus is clean.
+                    severity: undefined,
+                    file: filePath,
+                    line: i + 1,
+                    message: `Uncertainty stated without a named obstacle or recorded outcome: ${clause.trim().slice(0, 160)}`,
+                    fix: 'Resolve it if it costs about one request against a known endpoint, or name the specific obstacle (HTTP status, credential required, rate limited, paywalled) so it lands as incomplete/blocked rather than narrative.',
+                });
+            }
+            break;
+        }
         case 'pattern-match': {
             if (!check.pattern)
                 break;

package/dist/src/smiths/context-pipeline/workspace-context.js

@@ -33,6 +33,12 @@ const LEGACY_ROOT_FILES = [
     '.github/copilot-instructions.md',
     'AIWG.md',
 ];
+/**
+ * Operator-content volume above which a provider-named source is surfaced for a scope
+ * decision instead of being routed on filename alone (#2537). A genuine provider adapter
+ * is a few hundred bytes; a migrated project contract is tens of KB.
+ */
+const SCOPE_REVIEW_BYTES = 4096;
 const GENERATED_BLOCKS = [
     [PROVIDER_BOOTSTRAP_START, PROVIDER_BOOTSTRAP_END],
     ['<!-- AIWG:context-hook:start -->', '<!-- AIWG:context-hook:end -->'],
@@ -697,6 +703,21 @@ export async function auditWorkspaceContext(projectPath) {
     const providerSources = rootOperator.filter((source) => source.path !== 'WORKSPACE.md' && !neutralSources.includes(source.path)).map((source) => source.path);
     const providerOutputs = providerSources.map((source) => providerContextOutput(projectPath, source));
     const workspaceExists = sources.some((source) => source.path === 'WORKSPACE.md');
+    // Filename is the default scope signal, but a project that used CLAUDE.md as its
+    // main context file before WORKSPACE.md existed has project-neutral methodology in
+    // a provider-named file. Report volume and destination per source, and surface the
+    // substantial ones as a decision rather than routing them silently (#2537).
+    const routing = rootOperator.map((source) => {
+        const neutral = neutralSources.includes(source.path);
+        return {
+            source: source.path,
+            operatorBytes: Buffer.byteLength(source.operatorContent, 'utf8'),
+            destination: neutral ? 'WORKSPACE.md' : providerContextOutput(projectPath, source.path),
+            scope: neutral ? 'project-neutral' : `${source.provider ?? 'provider'}-only`,
+            provider: neutral ? null : source.provider,
+        };
+    }).sort((a, b) => b.operatorBytes - a.operatorBytes);
+    const scopeReview = routing.filter((entry) => entry.scope !== 'project-neutral' && entry.operatorBytes >= SCOPE_REVIEW_BYTES);
     return {
         version: 1,
         projectPath,
@@ -708,6 +729,8 @@ export async function auditWorkspaceContext(projectPath) {
         conflicts,
         sensitiveFindings,
         plan: {
+            routing,
+            scopeReview,
             neutralSources,
             providerSources,
             nestedSources: sources.filter((source) => source.scope === 'nested').map((source) => source.path),
@@ -945,8 +968,35 @@ export async function rollbackWorkspaceContext(projectPath, requestedId) {
     await atomicWrite(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
     return { id, restored: manifest.files.map((file) => file.path) };
 }
+/**
+ * Blank out fenced code blocks and inline code spans, preserving offsets and line
+ * structure, so link extraction sees only prose. Illustrative paths inside an
+ * example block are documentation, not context links the graph should resolve (#2536).
+ */
+function maskCodeRegions(content) {
+    const lines = content.split('\n');
+    let fence = null;
+    const masked = lines.map((line) => {
+        const openOrClose = /^\s{0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+        if (fence) {
+            // A closing fence uses the same character, is at least as long, and carries no info string.
+            if (openOrClose && openOrClose[1][0] === fence.marker && openOrClose[1].length >= fence.length && openOrClose[2].trim() === '') {
+                fence = null;
+            }
+            return ' '.repeat(line.length);
+        }
+        if (openOrClose) {
+            fence = { marker: openOrClose[1][0], length: openOrClose[1].length };
+            return ' '.repeat(line.length);
+        }
+        // Inline code spans: a run of N backticks closes on the next run of exactly N.
+        return line.replace(/(`+)(?:[^`]|(?!\1)`)*?\1/g, (span) => ' '.repeat(span.length));
+    });
+    return masked.join('\n');
+}
 function markdownLinks(content) {
-    return [...content.matchAll(/\[[^\]]+\]\((\.\/?[^)#]+)(?:#[^)]+)?\)/g)].map((match) => match[1]);
+    const prose = maskCodeRegions(content);
+    return [...prose.matchAll(/\[[^\]]+\]\((\.\/?[^)#]+)(?:#[^)]+)?\)/g)].map((match) => match[1]);
 }
 export async function workspaceLinkedFiles(projectPath) {
     const content = await readOptional(path.join(projectPath, 'WORKSPACE.md'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cli",
-  "version": "2026.9.7",
+  "version": "2026.9.9",
   "description": "Lightweight AIWG CLI for signed, versioned web-backed resources.",
   "type": "module",
   "license": "MIT",

package/tools/agents/deploy-agents.mjs

@@ -505,6 +505,7 @@ function parseArgs() {
     asPlugin: false,        // Generate .factory-plugin/ bundle (Factory provider only)
     deployBehaviors: false, // Deploy behaviors in addition to agents
     skipCommandsMigration: false, // Skip commands → skills migration (warns about duplicates)
+    warnOnSkippedCommandsMigration: true, // Emit the duplicate warning when the migration is skipped
     // Managed-marker provenance (#2502). Deployers that are not shipping the
     // bundled framework corpus (project-local bundles, in particular) must
     // override these so `aiwg refresh` does not mistake their artifacts for
@@ -544,6 +545,8 @@ function parseArgs() {
     else if (a === '--quiet' || a === '-q') cfg.quiet = true;
     else if (a === '--as-plugin') cfg.asPlugin = true;
     else if (a === '--skip-commands-migration') cfg.skipCommandsMigration = true;
+    // Structural opt-out: skip the migration without claiming the operator declined it (#2541).
+    else if (a === '--no-commands-warning') cfg.warnOnSkippedCommandsMigration = false;
     else if (a === '--copy-all' || a === '--copy-standard-skills') cfg.copyStandardSkills = true;
     else if (a === '--deploy-source' && args[i + 1]) cfg.deploySource = String(args[++i]);
     else if (a === '--deploy-version' && args[i + 1]) cfg.deployVersion = String(args[++i]);
@@ -1010,6 +1013,7 @@ export async function main() {
     asPlugin: cfg.asPlugin,
     deployBehaviors: cfg.kernelOnly ? false : cfg.deployBehaviors,
     skipCommandsMigration: cfg.skipCommandsMigration,
+    warnOnSkip: cfg.warnOnSkippedCommandsMigration !== false,
     // #1217 / #1219: --copy-all flag forces legacy per-project mirror
     // for the standard tier. Default is no-copy + index-driven discovery.
     // Replaces the legacy AIWG_COPY_STANDARD_SKILLS env var (removed rc.30).

package/tools/agents/providers/base.mjs

@@ -476,6 +476,41 @@ export function injectPlatformInContent(content, targetPlatform) {
  * copies destined for such providers must drop the field entirely. An
  * absent field is the documented "compatible with all platforms" default.
  */
+/**
+ * Remove the `triggers:` field from a deployed rule's frontmatter.
+ *
+ * Rules declare trigger phrases so `aiwg discover` can reach them by the
+ * question an agent asks rather than by their policy name (#2544). That is
+ * index-time metadata: no provider matches a *rule* by trigger, and the agent
+ * reading the deployed rule gains nothing from the list. Shipping it spends
+ * startup context on noise, which is exactly the budget #2540 is defending —
+ * ~2KB across the 16 rules covered today, and ~16KB if every rule adopts.
+ *
+ * Skills are untouched: several providers do match skills by trigger.
+ */
+export function stripTriggersFromContent(content) {
+  const fmMatch = content.match(/^(---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))([\s\S]*)$/);
+  if (!fmMatch) return content;
+
+  const [, open, fm, close, body] = fmMatch;
+  // Block list form:
+  //   triggers:
+  //     - "am I allowed to do this"
+  let updated = fm.replace(
+    /^triggers:[ \t]*\r?\n(?:[ \t]+-[ \t]+\S[^\r\n]*(?:\r?\n|$))*/m,
+    '',
+  );
+  // Inline form: triggers: ["a", "b"]
+  if (updated === fm) updated = fm.replace(/^triggers:[^\r\n]*(?:\r?\n|$)/m, '');
+
+  if (updated === fm) return content;
+  // An otherwise-empty frontmatter block is dropped rather than left as `---\n---`.
+  if (updated.trim().length === 0) return body.replace(/^\r?\n/, '');
+  // Removing a block mid-frontmatter can leave a trailing blank line before the
+  // closing fence; the deployed file should not carry it.
+  return open + updated.replace(/\s+$/, '') + close + body;
+}
+
 export function stripPlatformsFromContent(content) {
   const fmMatch = content.match(/^(---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))([\s\S]*)$/);
   if (!fmMatch) return content;
@@ -707,6 +742,13 @@ export function deployFiles(files, destDir, opts, transformFn) {
     const srcContent = fs.readFileSync(f, 'utf8');
     let transformedContent = transformFn ? transformFn(f, srcContent, opts) : srcContent;
 
+    // Rule triggers are index metadata, not something the reading agent needs.
+    // Keyed on the source path so every provider's rule deploy gets it without
+    // eight call sites opting in, and so skill triggers are never touched (#2544).
+    if (/(?:^|[\\/])rules[\\/][^\\/]+$/.test(f)) {
+      transformedContent = stripTriggersFromContent(transformedContent);
+    }
+
     // Inject target platform into agent .md files that use platforms: [all]
     if (injectPlatform && provider && /platforms:\s*\[all\]/.test(transformedContent)) {
       const platformName = PROVIDER_TO_PLATFORM[provider] || provider;
@@ -2932,8 +2974,47 @@ export function cleanupOldRuleFiles(rulesDir, opts = {}) {
  * @param {boolean} opts.skipCommandsMigration - User opted out; warn about duplicates instead
  * @returns {boolean} true if any AIWG command file was removed (or would be in dry-run)
  */
+/**
+ * Commands directories already warned about this process. The stale-command
+ * condition belongs to the directory, not to each deployed framework/addon, so
+ * `aiwg use all` must not repeat it once per unit (#2541).
+ */
+const warnedCommandsDirs = new Set();
+
+/**
+ * AIWG-managed command filenames in a directory — sidecar entries or files
+ * carrying the managed marker. Operator-authored commands and current
+ * skill-command wrappers are excluded.
+ */
+function listManagedCommandFiles(commandsDir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(commandsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const sidecar = readSidecarManifest(commandsDir) || { managed: {} };
+  const managed = sidecar.managed || {};
+  const names = [];
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    if (!entry.name.toLowerCase().endsWith('.md')) continue;
+    if (managed[entry.name]?.kind === 'skill-command') continue;
+    let owned = Object.prototype.hasOwnProperty.call(managed, entry.name);
+    if (!owned) {
+      try {
+        owned = MANAGED_MARKER_RE.test(fs.readFileSync(path.join(commandsDir, entry.name), 'utf8'));
+      } catch {
+        owned = false;
+      }
+    }
+    if (owned) names.push(entry.name);
+  }
+  return names;
+}
+
 export function migrateCommandsDirectory(commandsDir, opts = {}) {
-  const { dryRun = false, skipCommandsMigration = false, verbose = false } = opts;
+  const { dryRun = false, skipCommandsMigration = false, verbose = false, warnOnSkip = true } = opts;
 
   if (!fs.existsSync(commandsDir)) return false;
 
@@ -2941,11 +3022,27 @@ export function migrateCommandsDirectory(commandsDir, opts = {}) {
   if (entries.length === 0) return false;
 
   if (skipCommandsMigration) {
+    // Structural opt-outs (project-local addon bundles) skip the migration because
+    // it does not apply to them, not because the operator declined it. Warning
+    // there is noise, and it fired once per bundle (#2541).
+    if (!warnOnSkip) return false;
+
     const rel = path.relative(process.cwd(), commandsDir);
+    // The condition is a property of the directory, not of each deployed unit;
+    // emit it once per run no matter how many units pass through.
+    if (warnedCommandsDirs.has(commandsDir)) return false;
+    warnedCommandsDirs.add(commandsDir);
+
+    const stale = listManagedCommandFiles(commandsDir);
+    if (stale.length === 0) return false;
+
     console.warn(`\nWarning: commands migration skipped for ${rel}`);
-    console.warn('  Duplicate entries may appear in the command palette because old command');
-    console.warn('  files overlap with newly deployed skills. Remove AIWG command files manually');
-    console.warn(`  to fix: rm ${rel}/<command>.md`);
+    console.warn('  Duplicate entries may appear in the command palette because these old');
+    console.warn('  AIWG command files overlap with newly deployed skills:');
+    for (const name of stale) console.warn(`    ${path.join(rel, name)}`);
+    console.warn('  Resolve automatically by re-running without --skip-commands-migration,');
+    console.warn('  or remove them directly:');
+    console.warn(`    rm ${stale.map((name) => path.join(rel, name)).join(' ')}`);
     return false;
   }