@aiwg/cli 2026.9.6 → 2026.9.9

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

@@ -12,7 +12,7 @@ import { getVersionInfo } from '../../channel/manager.mjs';
 import { getLoggerInfo } from '../log.js';
 import * as ui from '../ui.js';
 import { maybePrintCommunityFooter } from '../../community/footer.js';
-import { existsSync, statSync, readdirSync } from 'fs';
+import { existsSync, statSync, readdirSync, readFileSync } from 'fs';
 import path from 'path';
 /**
  * Version command handler
@@ -30,6 +30,18 @@ export const versionHandler = {
         return { exitCode: 0 };
     },
 };
+/**
+ * Print the installation-drift notice when the canonical declaration and the
+ * running binary disagree. Keeps `aiwg version` honest about which one it is
+ * describing, and names the command that explains the rest (#2529).
+ */
+function printDrift(fp) {
+    if (!fp.drift)
+        return;
+    const method = fp.installation?.identity?.method ?? 'unrecorded';
+    const declared = fp.drift.canonicalVersion ? ` (${fp.drift.canonicalVersion})` : '';
+    ui.dim(`    ! canonical install declares ${method} at ${fp.drift.canonicalRoot}${declared} — run \`aiwg installation show\``);
+}
 function collectFingerprint(versionInfo) {
     const loggerInfo = getLoggerInfo();
     const fp = {
@@ -62,6 +74,22 @@ function collectFingerprint(versionInfo) {
             path: versionInfo.edgePath ?? versionInfo.packageRoot,
         };
     }
+    // `version` is the first thing anyone runs to answer "what am I on". If the
+    // canonical install declares a different root than the one executing, say so
+    // here rather than letting drift persist while every check looks correct.
+    const canonicalRoot = fp.installation?.identity?.root;
+    const actualRoot = fp.installation?.actualRoot;
+    if (canonicalRoot && actualRoot && path.resolve(canonicalRoot) !== path.resolve(actualRoot)) {
+        let canonicalVersion = null;
+        try {
+            const pkg = JSON.parse(readFileSync(path.join(canonicalRoot, 'package.json'), 'utf8'));
+            canonicalVersion = pkg.version ?? null;
+        }
+        catch {
+            // Canonical root may not exist or be readable; report the drift regardless.
+        }
+        fp.drift = { canonicalRoot, canonicalVersion, actualRoot };
+    }
     // Locale / timezone are useful for timezone-dependent bug reports.
     try {
         fp.locale = Intl.DateTimeFormat().resolvedOptions().locale;
@@ -96,13 +124,12 @@ async function displayVersion(opts) {
     ui.blank();
     console.log(`  ${ui.brandMark()} ${ui.bold('aiwg')}  ${ui.bold(fp.version)}  ${ui.channelLabel(fp.channel)}`);
     if (!opts.verbose) {
-        if (fp.git) {
+        if (fp.git)
             ui.dim(`    git: ${fp.git.sha} (${fp.git.branch})`);
-            ui.dim(`    path: ${fp.git.path}`);
-        }
-        else {
-            ui.dim(`    path: ${fp.packageRoot}`);
-        }
+        // Always the root that actually executed — not the declared edge checkout,
+        // which is what made drift invisible here (#2529).
+        ui.dim(`    path: ${fp.packageRoot}`);
+        printDrift(fp);
         maybePrintCommunityFooter();
         ui.blank();
         return;
@@ -110,15 +137,14 @@ async function displayVersion(opts) {
     // --verbose: the full environment fingerprint.
     if (fp.git) {
         ui.dim(`    git:       ${fp.git.sha} (${fp.git.branch})`);
-        ui.dim(`    path:      ${fp.git.path}`);
-    }
-    else {
-        ui.dim(`    path:      ${fp.packageRoot}`);
+        if (fp.git.path !== fp.packageRoot)
+            ui.dim(`    edge:      ${fp.git.path}`);
     }
+    ui.dim(`    path:      ${fp.packageRoot}`);
     ui.dim(`    channel:   ${fp.channel}`);
-    ui.dim(`    install:   ${fp.installation.identity?.method ?? 'unrecorded'} (${fp.installation.state})`);
-    ui.dim(`    canonical: ${fp.installation.identity?.root ?? '(unrecorded)'}`);
-    ui.dim(`    actual:    ${fp.installation.actualRoot}`);
+    ui.dim(`    install:   ${fp.installation?.identity?.method ?? 'unrecorded'} (${fp.installation?.state ?? 'unknown'})`);
+    ui.dim(`    canonical: ${fp.installation?.identity?.root ?? '(unrecorded)'}`);
+    ui.dim(`    actual:    ${fp.installation?.actualRoot ?? fp.packageRoot}`);
     ui.dim(`    node:      ${fp.node}`);
     ui.dim(`    platform:  ${fp.platform.os} ${fp.platform.arch} (${fp.platform.release})`);
     ui.dim(`    tty:       stdin=${fp.tty.stdin} stdout=${fp.tty.stdout} stderr=${fp.tty.stderr}`);

package/dist/src/cli/handlers/workspace-context.js

@@ -55,6 +55,14 @@ export const workspaceContextHandler = {
                     console.log(JSON.stringify(result, null, 2));
                 else {
                     console.log(`${result.dryRun ? 'Migration dry run' : 'Migration applied'}: ${result.changed ? 'changes found' : 'already canonical'}`);
+                    for (const entry of result.audit.plan.routing) {
+                        console.log(`  ${entry.source}: ${entry.operatorBytes.toLocaleString()} chars -> ${entry.destination} (${entry.scope})`);
+                    }
+                    for (const entry of result.audit.plan.scopeReview) {
+                        console.log(`  REVIEW ${entry.source} carries ${entry.operatorBytes.toLocaleString()} chars of operator content and is scoped to ${entry.scope} by filename.`);
+                        console.log('         Content in .aiwg/context/providers/ is read by that provider only.');
+                        console.log("         If this is project-neutral methodology, move it into WORKSPACE.md's Project Context section first.");
+                    }
                     for (const file of result.written)
                         console.log(`  ${result.dryRun ? 'would write' : 'wrote'} ${file}`);
                     if (result.transactionId)

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

@@ -1,4 +1,4 @@
-import { access, readFile, readdir } from 'node:fs/promises';
+import { access, readFile, readdir, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { loadGraphIndexFile } from '../../artifacts/index-reader.js';
 import { readAiwgConfig } from '../../config/aiwg-config.js';
@@ -9,38 +9,48 @@ import { diagnoseWorkspaceContext, providerContextContract, } from '../../smiths
 import { USER_SCOPE_PATHS } from '../scope-resolver.js';
 const RESTART_NOTICES = {
     claude: {
+        policy: 'restart-required',
         action: 'Restart Claude Code so the running session reloads deployed agents and skills.',
         reason: 'Claude Code reads its agent and skill registries when a session starts.',
     },
     codex: {
-        action: 'Restart or reopen Codex in this workspace so it reloads deployed agents and skills.',
-        reason: 'Codex scans project agent and skill registries when a session starts.',
+        policy: 'live-refresh',
+        action: 'Reopen Codex in this workspace if a deployed skill or agent does not appear.',
+        reason: 'Codex refreshes project skills between turns — a running session exposed newly deployed skills on the next turn without a restart (#2309).',
+        fallback: 'Codex picks up newly deployed skills on the next turn. Reopen Codex in this workspace only if a deployed skill or agent is still missing after that.',
     },
     copilot: {
+        policy: 'restart-required',
         action: 'Reload the VS Code window so Copilot reloads workspace agents and instructions.',
         reason: 'Copilot caches workspace agent definitions until the VS Code window reloads.',
     },
     cursor: {
+        policy: 'restart-required',
         action: 'Reload the Cursor workspace so it reloads agents and rules.',
         reason: 'Cursor reads workspace agents and rules when the workspace opens.',
     },
     factory: {
+        policy: 'restart-required',
         action: 'Restart the Factory droid runtime so it reloads deployed droids.',
         reason: 'Factory loads its droid registry when the runtime starts.',
     },
     opencode: {
+        policy: 'restart-required',
         action: 'Restart the OpenCode session so it reloads deployed agents.',
         reason: 'OpenCode scans its agent directory when the session starts.',
     },
     openclaw: {
+        policy: 'restart-required',
         action: 'Restart OpenClaw so it reloads its home-directory registry.',
         reason: 'OpenClaw loads its home-directory registry when the process starts.',
     },
     warp: {
+        policy: 'restart-required',
         action: 'Open a fresh Warp tab so it reloads project context.',
         reason: 'Warp reads project context when a tab starts.',
     },
     windsurf: {
+        policy: 'restart-required',
         action: 'Reload Devin Desktop so it reparses project context.',
         reason: 'Devin Desktop reads the Windsurf-compatible project context when the workspace opens.',
     },
@@ -111,6 +121,101 @@ async function countEntries(candidate) {
 function emptyCounts() {
     return { agents: 0, commands: 0, skills: 0, rules: 0, behaviors: 0 };
 }
+/**
+ * Flat-artifact attribution (#2507).
+ *
+ * Deployment counts used to be a plain `readdir` of the provider directory, so
+ * a run that wrote nothing still reported every pre-existing file as deployed —
+ * a no-op deploy over a stale, unmanaged tree was indistinguishable from a
+ * successful one. An artifact now counts as deployed only when this run wrote
+ * it (mtime at or after the invocation start) or AIWG owns it (sidecar entry or
+ * in-file managed marker). Everything else is reported as unmanaged.
+ */
+const MANAGED_SIDECAR = '.aiwg-manifest.json';
+const MANAGED_MARKER_PATTERN = /^(?:<!--\s*aiwg:managed\s|#\s*aiwg:managed\s)/m;
+const FLAT_ARTIFACT_KINDS = ['agents', 'commands', 'rules'];
+const FLAT_ARTIFACT_EXTENSIONS = ['.md', '.mdc', '.toml'];
+/** Clock skew tolerance between the recorded invocation start and file mtimes. */
+const WRITE_ATTRIBUTION_SKEW_MS = 2_000;
+const FLAT_ARTIFACT_NOUNS = {
+    agents: 'agent',
+    commands: 'command',
+    rules: 'rule',
+};
+async function readManagedSidecarNames(dir) {
+    try {
+        const raw = await readFile(path.join(dir, MANAGED_SIDECAR), 'utf8');
+        const parsed = JSON.parse(raw);
+        return new Set(Object.keys(parsed.managed ?? {}));
+    }
+    catch {
+        return new Set();
+    }
+}
+/**
+ * Split one flat artifact directory into artifacts this deployment accounts for
+ * and artifacts it does not. Returns `null` when the directory cannot be
+ * attributed (missing, unreadable, or no invocation boundary to compare
+ * against), so callers fall back to the plain entry count.
+ */
+async function tallyFlatArtifacts(dir, writtenSince) {
+    if (!dir || writtenSince === null)
+        return null;
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    const managedNames = await readManagedSidecarNames(dir);
+    const tally = { deployed: 0, unmanaged: [] };
+    for (const entry of entries) {
+        if (entry.name.startsWith('.'))
+            continue;
+        if (!entry.isFile()) {
+            // Nested directories (e.g. deployed behaviors under rules/) are counted
+            // as-is; they are not flat artifacts and have their own lifecycle.
+            tally.deployed += 1;
+            continue;
+        }
+        const lower = entry.name.toLowerCase();
+        if (!FLAT_ARTIFACT_EXTENSIONS.some((extension) => lower.endsWith(extension)))
+            continue;
+        const absolute = path.join(dir, entry.name);
+        if (managedNames.has(entry.name)) {
+            tally.deployed += 1;
+            continue;
+        }
+        let writtenThisRun = false;
+        try {
+            const info = await stat(absolute);
+            writtenThisRun = info.mtimeMs + WRITE_ATTRIBUTION_SKEW_MS >= writtenSince;
+        }
+        catch {
+            writtenThisRun = false;
+        }
+        if (writtenThisRun) {
+            tally.deployed += 1;
+            continue;
+        }
+        let owned = false;
+        try {
+            owned = MANAGED_MARKER_PATTERN.test(await readFile(absolute, 'utf8'));
+        }
+        catch {
+            // Unreadable files are not claimed as deployed, but neither are they
+            // reported as shadowing artifacts we could not inspect.
+            continue;
+        }
+        if (owned)
+            tally.deployed += 1;
+        else
+            tally.unmanaged.push(entry.name);
+    }
+    tally.unmanaged.sort((a, b) => a.localeCompare(b));
+    return tally;
+}
 function phase(id, state, required, summary, evidence) {
     return { id, state, required, summary, evidence };
 }
@@ -232,9 +337,16 @@ export async function verifyProviderDeployment(options) {
     const findings = [];
     const counts = emptyCounts();
     const restartNotice = RESTART_NOTICES[normalized] ?? null;
-    const restartAction = restartNotice?.action ?? null;
+    // A provider with no notice gets no restart claim, which is what it got
+    // before this field existed. The label is the absence of a known restart
+    // requirement, not a positive claim that the client refreshes live.
+    const reloadPolicy = restartNotice?.policy ?? 'live-refresh';
+    const restartRequired = reloadPolicy === 'restart-required';
+    // Only a `restart-required` provider gets an imperative restart step. A
+    // `live-refresh` provider keeps its rationale and a conditional fallback (#2309).
+    const restartAction = restartRequired ? (restartNotice?.action ?? null) : null;
     const restartReason = restartNotice?.reason ?? null;
-    const restartRequired = restartAction !== null;
+    const reloadFallback = restartRequired ? null : (restartNotice?.fallback ?? null);
     if (!definition) {
         findings.push(finding(normalized, 'provider-unknown', 'blocking', `No provider definition is available for '${options.provider}'.`, 'Choose a supported provider or repair the project-local provider adapter.'));
     }
@@ -249,9 +361,30 @@ export async function verifyProviderDeployment(options) {
         const artifactPaths = options.scope === 'user'
             ? USER_SCOPE_PATHS[normalized] ?? definition.paths.artifacts
             : definition.paths.artifacts;
+        const writtenSince = options.invocationStartedAt
+            ? Date.parse(options.invocationStartedAt)
+            : Number.NaN;
+        const attributionBoundary = Number.isFinite(writtenSince) ? writtenSince : null;
         for (const type of ['agents', 'commands', 'skills', 'rules', 'behaviors']) {
             const resolved = resolveProviderPathValue(artifactPaths[type], deploymentRoot);
             counts[type] = await countEntries(resolved);
+            // #2507: flat artifact directories report what this deployment accounts
+            // for, not whatever happens to be sitting in the directory.
+            const flatKind = FLAT_ARTIFACT_KINDS.find((kind) => kind === type);
+            if (!flatKind)
+                continue;
+            const tally = await tallyFlatArtifacts(resolved, attributionBoundary);
+            if (!tally)
+                continue;
+            counts[flatKind] = tally.deployed;
+            if (tally.unmanaged.length === 0)
+                continue;
+            const shown = tally.unmanaged.slice(0, 3).join(', ');
+            const remainder = tally.unmanaged.length - 3;
+            findings.push(finding(normalized, `unmanaged-artifacts:${flatKind}`, 'advisory', `${tally.unmanaged.length} unmanaged ${FLAT_ARTIFACT_NOUNS[flatKind]} file(s) left in place at ${artifactPaths[flatKind]}: `
+                + `${shown}${remainder > 0 ? `, and ${remainder} more` : ''}. `
+                + 'They are not managed by AIWG and were not counted as deployed.', `Re-run aiwg use ${options.requestedBundles[0] ?? 'all'} --provider ${normalized} --force to replace them, `
+                + `or delete ${artifactPaths[flatKind]} so AIWG can reclaim the directory.`, { kind: flatKind, unmanaged: tally.unmanaged }));
         }
         const resolvedSkillsPath = resolveProviderPathValue(artifactPaths.skills, deploymentRoot);
         const kernelPath = options.scope === 'user'
@@ -376,6 +509,8 @@ export async function verifyProviderDeployment(options) {
         restartRequired,
         restartAction,
         restartReason,
+        reloadPolicy,
+        reloadFallback,
         counts,
         phases,
         findings,
@@ -385,7 +520,9 @@ export function buildDryRunUseResult(options) {
     const providers = options.providers.map((provider) => {
         const normalized = normalizeProviderDefinitionId(provider) ?? provider;
         const restartNotice = RESTART_NOTICES[normalized] ?? null;
-        const restartAction = restartNotice?.action ?? null;
+        const reloadPolicy = restartNotice?.policy ?? 'live-refresh';
+        const restartRequired = reloadPolicy === 'restart-required';
+        const restartAction = restartRequired ? (restartNotice?.action ?? null) : null;
         const phases = [
             phase('resolve', 'planned', true, `Would resolve ${options.projectRoot}, ${normalized}, ${options.scope} scope.`),
             phase('deploy', 'planned', true, 'Would deploy the requested managed artifact surface.'),
@@ -398,9 +535,11 @@ export function buildDryRunUseResult(options) {
             provider: normalized,
             scope: options.scope,
             outcome: 'planned',
-            restartRequired: restartAction !== null,
+            restartRequired,
             restartAction,
             restartReason: restartNotice?.reason ?? null,
+            reloadPolicy,
+            reloadFallback: restartRequired ? null : (restartNotice?.fallback ?? null),
             counts: emptyCounts(),
             phases,
             findings: [],
@@ -497,6 +636,8 @@ export async function verifyConfiguredDeployments(projectRoot, filters = {}, fra
             restartRequired: false,
             restartAction: null,
             restartReason: null,
+            reloadPolicy: 'live-refresh',
+            reloadFallback: null,
             counts: emptyCounts(),
             phases: [phase('verify', 'failed', true, 'No installed provider deployment could be resolved.')],
             findings: [finding(fallback, 'deployment-not-configured', 'blocking', 'No installed provider deployment could be resolved.', 'Run aiwg use all --provider <provider>.')],
@@ -640,6 +781,14 @@ export function renderUseDeploymentResult(result, options = {}) {
             lines.push(...wrapParagraph(`Framework index built: ${result.discovery.builtAt}`, width));
         }
     }
+    const reloadFallbacks = result.providers
+        .filter((provider) => !provider.restartRequired && provider.reloadFallback)
+        .map((provider) => provider.reloadFallback);
+    if (reloadFallbacks.length > 0) {
+        lines.push('', 'If something is missing');
+        for (const note of reloadFallbacks)
+            lines.push(...wrapParagraph(note, width));
+    }
     const restartActions = result.providers
         .filter((provider) => provider.restartRequired && provider.restartAction)
         .map((provider) => provider.restartAction);

package/dist/src/cli/watch-service.js

@@ -46,10 +46,6 @@ export class WatchService {
         this.watcher.on('add', (path) => this.handleEvent('add', path));
         this.watcher.on('change', (path) => this.handleEvent('change', path));
         this.watcher.on('unlink', (path) => this.handleEvent('unlink', path));
-        this.watcher.on('ready', () => {
-            const watched = this.watcher?.getWatched() || {};
-            this.stats.filesWatched = Object.values(watched).reduce((sum, files) => sum + files.length, 0);
-        });
         this.watcher.on('error', (error) => {
             this.stats.errors++;
             console.error('Watch error:', error);
@@ -64,6 +60,53 @@ export class WatchService {
                 resolve();
             }
         });
+        // `ready` only means chokidar finished its initial scan. Because the
+        // watcher runs with `ignoreInitial: true`, a file created between the scan
+        // and the watch actually being armed is reported by neither — the event is
+        // absent rather than late, so no caller-side wait can recover it (#2518).
+        // Resolving `start()` only once every target appears in `getWatched()`
+        // makes readiness mean armed.
+        await this.waitUntilArmed(patterns);
+        const watched = this.watcher?.getWatched() ?? {};
+        this.stats.filesWatched = Object.values(watched).reduce((sum, files) => sum + files.length, 0);
+    }
+    /**
+     * Poll `getWatched()` until every requested target is present, or the budget
+     * expires. Bounded on purpose: a target that does not exist on disk can never
+     * be armed, and `start()` must not hang waiting for one.
+     *
+     * The healthy path satisfies the first synchronous check and never awaits, so
+     * a test that mocks the watcher under fake timers must report its targets
+     * from `getWatched()` — otherwise the poll waits on a clock nothing advances.
+     */
+    async waitUntilArmed(patterns, timeoutMs = 500, pollIntervalMs = 25) {
+        const deadline = Date.now() + timeoutMs;
+        while (!this.allTargetsArmed(patterns)) {
+            if (Date.now() >= deadline) {
+                return;
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+        }
+    }
+    /** True when chokidar reports a watch covering every requested target. */
+    allTargetsArmed(patterns) {
+        if (!this.watcher) {
+            return true;
+        }
+        const watched = this.watcher.getWatched();
+        // chokidar keys `getWatched()` with the spelling it was given, so resolve
+        // both sides before comparing.
+        const armed = new Set();
+        for (const [dir, entries] of Object.entries(watched)) {
+            const absoluteDir = path.resolve(dir);
+            armed.add(absoluteDir);
+            for (const entry of entries) {
+                armed.add(path.join(absoluteDir, entry));
+            }
+        }
+        // A directory target is keyed directly; a file target is listed under its
+        // parent. Either spelling resolves into the same set.
+        return patterns.every((pattern) => armed.has(path.resolve(pattern)));
     }
     /**
      * Stop watching

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/config/project-artifacts-health.mjs

@@ -89,10 +89,23 @@ export function auditProjectArtifactHealth(projectDir, env = process.env) {
       severity = 'error';
       repairable = controls.filter((item) => !item.local).every((item) => item.external);
       action = 'Run `aiwg artifacts repair --dry-run`, then `aiwg artifacts repair --apply` after reviewing the plan.';
-    } else if (divergentControl.length || divergentPayload.length) {
+    } else if (divergentControl.length) {
+      // Only control-plane divergence is genuinely manual: `repairProjectArtifacts`
+      // refuses outright on it, because AIWG.md / aiwg.config / registry.json have
+      // no safe automatic winner (#2516).
       classification = 'duplicated-divergent';
       severity = 'error';
-      action = 'Reconcile the reported local and external files manually; no automatic repair will overwrite divergent content.';
+      action = 'Reconcile the reported control-plane files manually; automatic repair refuses while they diverge.';
+    } else if (divergentPayload.length) {
+      // Divergent *payload* is repairable and always has been — repair archives the
+      // local variant under archive/local-corpus-migration/conflicts/local/, leaves
+      // the external variant untouched, and removes local only after byte
+      // verification. Reporting this as manual-only steered operators away from a
+      // working automatic path and into hand-migrating corpora (#2516).
+      classification = 'duplicated-divergent-payload';
+      severity = 'warning';
+      repairable = true;
+      action = 'Run `aiwg artifacts repair --dry-run`, then `aiwg artifacts repair --apply`; divergent local variants are archived, never overwritten.';
     } else if (localPayload.length) {
       classification = 'duplicated-identical';
       severity = 'warning';