@open-agent-toolkit/cli 0.3.8 → 0.3.10

package/dist/commands/instructions/sync/sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../../src/commands/instructions/sync/sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,EAAE,EAAsB,MAAM,kBAAkB,CAAC;AAI3E,OAAO,EAKL,KAAK,mCAAmC,EACzC,MAAM,2CAA2C,CAAC;AAanD,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAQ5C,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,OAAO,EAAO,GACrB,OAAO,CAAC,IAAI,CAAC,CAEf;AAgTD,wBAAgB,6BAA6B,CAC3C,SAAS,GAAE,OAAO,CAAC,mCAAmC,CAAM,GAC3D,OAAO,CAwGT"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../../src/commands/instructions/sync/sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,EAAE,EAGH,MAAM,kBAAkB,CAAC;AAI1B,OAAO,EAKL,KAAK,mCAAmC,EAEzC,MAAM,2CAA2C,CAAC;AAuBnD,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAQ5C,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,OAAO,EAAO,GACrB,OAAO,CAAC,IAAI,CAAC,CAEf;AAiiBD,wBAAgB,6BAA6B,CAC3C,SAAS,GAAE,OAAO,CAAC,mCAAmC,CAAM,GAC3D,OAAO,CAyLT"}

package/dist/commands/instructions/sync/sync.js

@@ -1,8 +1,8 @@
-import { lstat, readFile, rm, symlink, writeFile } from 'node:fs/promises';
+import { lstat, readFile, readlink, realpath, rm, symlink, writeFile, } from 'node:fs/promises';
 import { dirname, join, relative } from 'node:path';
 import { buildCommandContext } from '../../../app/command-context.js';
 import { INSTRUCTION_SYNC_STRATEGIES, } from '../../instructions/instructions.types.js';
-import { buildInstructionsPayload, DEFAULT_INSTRUCTION_SYNC_STRATEGY, EXPECTED_CLAUDE_CONTENT, formatInstructionsReport, resolveInstructionPointerExcludes, resolveInstructionSyncStrategy, scanInstructionFiles, } from '../../instructions/instructions.utils.js';
+import { buildInstructionsPayload, EXPECTED_CLAUDE_CONTENT, formatInstructionsReport, readConfiguredInstructionSyncStrategy, resolveInstructionPointerExcludes, resolveInstructionSyncStrategy, findLeftoverClaudeFiles, findLinksThrough, inspectManagedShim, buildLeftoverClaudeWarnings, buildShimRemovalBlockWarning, describeShimRemovalBlock, findShimRemovalBlockers, omitHeldBackLeftovers, markBlockedShimEntries, scanInstructionFiles, verifyManagedShimUnchanged, } from '../../instructions/instructions.utils.js';
 import { readGlobalOptions } from '../../shared/shared.utils.js';
 import { CliError } from '../../../errors/cli-error.js';
 import { resolveProjectRoot } from '../../../fs/paths.js';
@@ -13,8 +13,13 @@ export async function removeInstructionFile(path, remove = rm) {
 function defaultDependencies() {
     return {
         buildCommandContext,
+        findLeftoverClaudeFiles,
         lstat,
+        readConfiguredInstructionSyncStrategy,
         readFile,
+        readFileBytes: (path) => readFile(path),
+        readlink,
+        realpath,
         removeFile: removeInstructionFile,
         resolveInstructionPointerExcludes,
         resolveProjectRoot,
@@ -25,18 +30,28 @@ function defaultDependencies() {
         writeFile,
     };
 }
+function getShimLabel(strategy) {
+    switch (strategy) {
+        case 'symlink':
+            return 'symlink';
+        case 'copy':
+            return 'hard copy';
+        case 'none':
+            return 'removal';
+        default:
+            return 'pointer file';
+    }
+}
 function getSyncReason(actionType, strategy) {
-    const label = strategy === 'symlink'
-        ? 'symlink'
-        : strategy === 'copy'
-            ? 'hard copy'
-            : 'pointer file';
+    const label = getShimLabel(strategy);
     return actionType === 'create'
         ? `missing CLAUDE.md ${label}`
         : `overwrite CLAUDE.md with canonical ${label}`;
 }
 function getSyncedDetail(strategy) {
     switch (strategy) {
+        case 'none':
+            return 'no CLAUDE.md';
         case 'symlink':
             return 'symlink synced';
         case 'copy':
@@ -69,7 +84,66 @@ function wrapStrayResyncError(error, agentsPath, claudePath) {
     const message = error instanceof Error ? error.message : String(error);
     return new CliError(`Adopted stray instructions into ${agentsPath}, but failed to regenerate ${claudePath}: ${message}`, error instanceof CliError ? error.exitCode : 2);
 }
+/**
+ * Plan strategy `none`: remove exact managed shims, adopt strays into
+ * AGENTS.md without writing a shim back, and never write or overwrite a
+ * CLAUDE.md. `--force` has no effect here: nothing that is not an exact
+ * managed shape is ever deleted.
+ */
+function planNoShimActions(entries) {
+    const actions = [];
+    for (const entry of entries) {
+        if (entry.status === 'managed_shim' && entry.managedShim) {
+            actions.push({
+                type: 'remove',
+                target: entry.claudePath,
+                reason: `remove OAT-managed CLAUDE.md ${getShimLabel(entry.managedShim.shape)} (strategy none)`,
+                result: 'planned',
+            });
+            continue;
+        }
+        // Adopt, then remove: leaving the lone CLAUDE.md in place would make
+        // Claude Code's `agents-md` plugin stand down for the whole project.
+        if (entry.status === 'stray') {
+            actions.push({
+                type: 'create',
+                target: getAgentsPath(entry),
+                reason: 'adopt stray CLAUDE.md into canonical AGENTS.md',
+                result: 'planned',
+            });
+            actions.push({
+                type: 'remove',
+                target: entry.claudePath,
+                reason: 'remove adopted stray CLAUDE.md (strategy none)',
+                result: 'planned',
+            });
+            continue;
+        }
+        if (entry.status !== 'content_mismatch') {
+            continue;
+        }
+        if (hasUnreadableCanonicalAgents(entry) && entry.agentsPath) {
+            actions.push({
+                type: 'skip',
+                target: entry.agentsPath,
+                reason: 'canonical AGENTS.md unreadable; repair manually',
+                result: 'skipped',
+            });
+            continue;
+        }
+        actions.push({
+            type: 'skip',
+            target: entry.claudePath,
+            reason: 'CLAUDE.md unreadable; repair manually',
+            result: 'skipped',
+        });
+    }
+    return actions;
+}
 function planSyncActions({ entries, force, strategy, }) {
+    if (strategy === 'none') {
+        return planNoShimActions(entries);
+    }
     const actions = [];
     for (const entry of entries) {
         if (entry.status === 'stray') {
@@ -139,9 +213,13 @@ function planSyncActions({ entries, force, strategy, }) {
     }
     return actions;
 }
-async function applySyncActions(actions, entries, dependencies, strategy) {
+async function applySyncActions(actions, entries, dependencies, strategy, repoRoot) {
     const appliedActions = [];
     const entriesByTarget = new Map();
+    // Under `none`, what each adopted stray CLAUDE.md looked like right after its
+    // content was copied into AGENTS.md: the record its removal re-verifies
+    // against, or the reason it must be kept.
+    const adoptedStrays = new Map();
     for (const entry of entries) {
         entriesByTarget.set(entry.claudePath, entry);
         entriesByTarget.set(getAgentsPath(entry), entry);
@@ -157,6 +235,59 @@ async function applySyncActions(actions, entries, dependencies, strategy) {
         }
         const agentsPath = getAgentsPath(entry);
         const isAgentsAction = action.target === agentsPath;
+        if (action.type === 'remove') {
+            const isStray = entry.status === 'stray';
+            const planned = isStray
+                ? adoptedStrays.get(action.target)
+                : entry.managedShim;
+            if (planned === undefined) {
+                throw new CliError(`No planning record for CLAUDE.md removal at ${action.target}`, 2);
+            }
+            // Fail closed at the last moment: the file may have been edited or
+            // replaced since it was classified. Anything but the exact shim that
+            // was recorded is kept and reported, never deleted.
+            const changed = typeof planned === 'string'
+                ? planned
+                : await verifyManagedShimUnchanged(action.target, agentsPath, planned, dependencies);
+            // Also re-check, just as late, that no scanned instruction file has
+            // become a link through this CLAUDE.md: deleting it would dangle it.
+            const linkers = changed === null
+                ? await findLinksThrough(action.target, entries.flatMap((candidate) => candidate.agentsPath === null
+                    ? [candidate.claudePath]
+                    : [candidate.agentsPath, candidate.claudePath]), dependencies)
+                : [];
+            if (linkers.length > 0) {
+                const linked = linkers
+                    .map((linker) => relative(repoRoot, linker).replaceAll('\\', '/'))
+                    .join(', ');
+                appliedActions.push({
+                    type: 'skip',
+                    target: action.target,
+                    reason: isStray
+                        ? `CLAUDE.md kept after adoption into AGENTS.md (${linked} now link to it)`
+                        : `CLAUDE.md changed since planning (${linked} now link to it); kept`,
+                    result: 'skipped',
+                });
+                continue;
+            }
+            if (changed !== null) {
+                appliedActions.push({
+                    type: 'skip',
+                    target: action.target,
+                    reason: isStray
+                        ? `CLAUDE.md kept after adoption into AGENTS.md (${changed})`
+                        : `CLAUDE.md changed since planning (${changed}); kept`,
+                    result: 'skipped',
+                });
+                continue;
+            }
+            await dependencies.removeFile(action.target);
+            appliedActions.push({
+                ...action,
+                result: 'applied',
+            });
+            continue;
+        }
         if (isAgentsAction) {
             try {
                 await dependencies.lstat(agentsPath);
@@ -170,8 +301,12 @@ async function applySyncActions(actions, entries, dependencies, strategy) {
                     throw error;
                 }
             }
+            const claudeBeforeAdoption = strategy === 'none' ? await dependencies.lstat(entry.claudePath) : null;
             const adoptedContent = await dependencies.readFile(entry.claudePath, 'utf8');
             await dependencies.writeFile(agentsPath, adoptedContent, 'utf8');
+            if (claudeBeforeAdoption) {
+                adoptedStrays.set(entry.claudePath, await recordAdoptedStray(entry.claudePath, agentsPath, claudeBeforeAdoption, dependencies));
+            }
             appliedActions.push({
                 ...action,
                 result: 'applied',
@@ -181,6 +316,9 @@ async function applySyncActions(actions, entries, dependencies, strategy) {
         if (!entry.agentsPath && action.type !== 'update') {
             throw new CliError(`Unable to resolve AGENTS.md for ${action.target}`, 2);
         }
+        if (strategy === 'none') {
+            throw new CliError(`Refusing to write ${action.target}: strategy none keeps no CLAUDE.md`, 2);
+        }
         try {
             if (action.type === 'update') {
                 await dependencies.removeFile(action.target);
@@ -210,6 +348,28 @@ async function applySyncActions(actions, entries, dependencies, strategy) {
     }
     return appliedActions;
 }
+/**
+ * After a stray's content is copied into AGENTS.md under `none`, the stray is
+ * removable only if it is now an exact managed shape of that AGENTS.md (in
+ * practice a byte-identical copy) and is still the same file that was read.
+ * Otherwise return why it must be kept.
+ */
+async function recordAdoptedStray(claudePath, agentsPath, before, dependencies) {
+    const inspection = await inspectManagedShim(claudePath, agentsPath, dependencies);
+    if (inspection.kind === 'absent') {
+        return 'CLAUDE.md no longer exists';
+    }
+    if (inspection.kind === 'unmanaged' || inspection.kind === 'unreadable') {
+        return inspection.detail === 'hand-written or modified CLAUDE.md; kept'
+            ? 'its content differs from the adopted AGENTS.md'
+            : inspection.detail.replace(/; kept$/, '');
+    }
+    if (inspection.record.dev !== before.dev ||
+        inspection.record.ino !== before.ino) {
+        return 'CLAUDE.md was replaced during adoption';
+    }
+    return inspection.record;
+}
 function getPostSyncEntries(entries, actions, strategy) {
     const actionByTarget = new Map(actions.map((action) => [action.target, action]));
     return entries.map((entry) => {
@@ -218,6 +378,30 @@ function getPostSyncEntries(entries, actions, strategy) {
         if (!action && !adoptedAction) {
             return entry;
         }
+        if (strategy === 'none' &&
+            entry.status === 'stray' &&
+            adoptedAction?.result === 'applied') {
+            return action?.type === 'remove' && action.result === 'applied'
+                ? {
+                    ...entry,
+                    agentsPath: getAgentsPath(entry),
+                    status: 'ok',
+                    detail: 'adopted into AGENTS.md; CLAUDE.md removed',
+                }
+                : {
+                    ...entry,
+                    agentsPath: getAgentsPath(entry),
+                    status: 'unmanaged',
+                    detail: 'adopted into AGENTS.md; CLAUDE.md kept',
+                };
+        }
+        if (action?.type === 'remove' && action.result === 'applied') {
+            return {
+                ...entry,
+                status: 'ok',
+                detail: 'OAT-managed CLAUDE.md removed',
+            };
+        }
         if (action?.result === 'applied' &&
             (entry.status !== 'stray' || adoptedAction?.result === 'applied')) {
             return {
@@ -238,18 +422,19 @@ export function createInstructionsSyncCommand(overrides = {}) {
         ...defaultDependencies(),
         ...overrides,
     };
+    // `--strategy` has no Commander default: a filled-in default is
+    // indistinguishable from an explicit flag and would always hide
+    // `instructions.claude.shims`.
     return new Command('sync')
         .description('Repair AGENTS.md/CLAUDE.md sync drift using the selected strategy')
         .option('--dry-run', 'Preview sync changes without applying')
         .option('--force', 'Overwrite mismatched CLAUDE.md files')
-        .addOption(new Option('--strategy <strategy>', 'Sync strategy')
-        .choices([...INSTRUCTION_SYNC_STRATEGIES])
-        .default(DEFAULT_INSTRUCTION_SYNC_STRATEGY))
+        .addOption(new Option('--strategy <strategy>', 'Sync strategy for this run (overrides instructions.claude.shims)').choices([...INSTRUCTION_SYNC_STRATEGIES]))
         .action(async (options, command) => {
         const context = dependencies.buildCommandContext(readGlobalOptions(command));
         try {
             const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
-            const strategy = resolveInstructionSyncStrategy(options.strategy);
+            const strategy = resolveInstructionSyncStrategy(options.strategy, await dependencies.readConfiguredInstructionSyncStrategy(repoRoot));
             const exclusions = await dependencies.resolveInstructionPointerExcludes(repoRoot);
             // Warned before any work: an operator whose opt-out silently matches
             // nothing must hear about it even when the sync then succeeds.
@@ -260,30 +445,83 @@ export function createInstructionsSyncCommand(overrides = {}) {
                 excludedPaths: exclusions.configured,
                 strategy,
             });
-            const plannedActions = planSyncActions({
+            // Removal under `none` is all or nothing: while any CLAUDE.md,
+            // .claude/CLAUDE.md, or CLAUDE.local.md has content of its own, a
+            // partial removal would leave some directories without their
+            // AGENTS.md instructions, so every planned removal is held back.
+            // Read-only and repository-wide, like the leftover warnings below.
+            const leftoversBeforeSync = strategy === 'none'
+                ? await dependencies.findLeftoverClaudeFiles(repoRoot)
+                : [];
+            const blockers = findShimRemovalBlockers(entries, leftoversBeforeSync);
+            const unblockedActions = planSyncActions({
                 entries,
                 force: options.force ?? false,
                 strategy,
             });
+            const heldBack = unblockedActions
+                .filter((action) => action.type === 'remove')
+                .map((action) => action.target);
+            const blocked = blockers.length > 0 && heldBack.length > 0;
+            const plannedActions = blocked
+                ? unblockedActions.map((action) => action.type === 'remove'
+                    ? {
+                        type: 'skip',
+                        target: action.target,
+                        reason: describeShimRemovalBlock(repoRoot, blockers),
+                        result: 'skipped',
+                    }
+                    : action)
+                : unblockedActions;
             const dryRun = options.dryRun ?? false;
             const actions = dryRun
                 ? plannedActions
-                : await applySyncActions(plannedActions, entries, dependencies, strategy);
+                : await applySyncActions(plannedActions, entries, dependencies, strategy, repoRoot);
+            // Read-only and repository-wide, independently of the mutation
+            // exclusions: Claude Code's walk does not honor OAT's excludes. A
+            // dry run reports what would remain, so planned removals are left
+            // out.
+            const plannedRemovals = new Set(plannedActions
+                .filter((action) => action.type === 'remove')
+                .map((action) => action.target));
+            const leftoverClaudeFiles = strategy !== 'none'
+                ? []
+                : dryRun
+                    ? leftoversBeforeSync.filter((leftover) => !plannedRemovals.has(leftover.path))
+                    : await dependencies.findLeftoverClaudeFiles(repoRoot);
+            const mode = dryRun ? 'dry-run' : 'apply';
+            const reportedEntries = dryRun
+                ? entries
+                : getPostSyncEntries(entries, actions, strategy);
             const payload = buildInstructionsPayload({
-                mode: dryRun ? 'dry-run' : 'apply',
-                entries: dryRun
-                    ? entries
-                    : getPostSyncEntries(entries, actions, strategy),
+                mode,
+                strategy,
+                entries: blocked
+                    ? markBlockedShimEntries(reportedEntries)
+                    : reportedEntries,
                 actions,
                 excludedPaths: exclusions.configured,
                 effectiveExcludedPaths: exclusions.effective,
                 exclusionWarnings: exclusions.warnings,
+                warnings: [
+                    ...(blocked
+                        ? [
+                            buildShimRemovalBlockWarning(repoRoot, blockers, heldBack, mode),
+                        ]
+                        : []),
+                    ...buildLeftoverClaudeWarnings(repoRoot, blocked
+                        ? omitHeldBackLeftovers(leftoverClaudeFiles, heldBack)
+                        : leftoverClaudeFiles),
+                ],
             });
             if (context.json) {
                 context.logger.json(payload);
             }
             else {
                 context.logger.info(formatInstructionsReport(payload, repoRoot));
+                for (const warning of payload.warnings ?? []) {
+                    context.logger.warn(warning.message);
+                }
                 if (dryRun) {
                     context.logger.warn('\nDry-run only: no filesystem changes were made.');
                     if (plannedActions.length > 0) {

package/dist/commands/instructions/validate/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../../src/commands/instructions/validate/validate.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,uCAAuC,EAC7C,MAAM,2CAA2C,CAAC;AAYnD,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAW5C,wBAAgB,iCAAiC,CAC/C,SAAS,GAAE,OAAO,CAAC,uCAAuC,CAAM,GAC/D,OAAO,CAsET"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../../src/commands/instructions/validate/validate.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,uCAAuC,EAC7C,MAAM,2CAA2C,CAAC;AAmBnD,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAa5C,wBAAgB,iCAAiC,CAC/C,SAAS,GAAE,OAAO,CAAC,uCAAuC,CAAM,GAC/D,OAAO,CA+GT"}

package/dist/commands/instructions/validate/validate.js

@@ -1,6 +1,6 @@
 import { buildCommandContext } from '../../../app/command-context.js';
 import { INSTRUCTION_SYNC_STRATEGIES, } from '../../instructions/instructions.types.js';
-import { buildInstructionsPayload, DEFAULT_INSTRUCTION_SYNC_STRATEGY, formatInstructionsReport, resolveInstructionPointerExcludes, resolveInstructionSyncStrategy, scanInstructionFiles, } from '../../instructions/instructions.utils.js';
+import { buildInstructionsPayload, buildLeftoverClaudeWarnings, buildShimRemovalBlockWarning, findLeftoverClaudeFiles, findShimRemovalBlockers, omitHeldBackLeftovers, listShimRemovals, markBlockedShimEntries, formatInstructionsReport, readConfiguredInstructionSyncStrategy, resolveInstructionPointerExcludes, resolveInstructionSyncStrategy, scanInstructionFiles, } from '../../instructions/instructions.utils.js';
 import { readGlobalOptions } from '../../shared/shared.utils.js';
 import { CliError } from '../../../errors/cli-error.js';
 import { resolveProjectRoot } from '../../../fs/paths.js';
@@ -8,6 +8,8 @@ import { Command, Option } from 'commander';
 function defaultDependencies() {
     return {
         buildCommandContext,
+        findLeftoverClaudeFiles,
+        readConfiguredInstructionSyncStrategy,
         resolveInstructionPointerExcludes,
         resolveProjectRoot,
         scanInstructionFiles,
@@ -18,16 +20,15 @@ export function createInstructionsValidateCommand(overrides = {}) {
         ...defaultDependencies(),
         ...overrides,
     };
+    // `--strategy` has no Commander default; see `oat instructions sync`.
     return new Command('validate')
         .description('Validate AGENTS.md/CLAUDE.md sync integrity for the selected strategy')
-        .addOption(new Option('--strategy <strategy>', 'Sync strategy')
-        .choices([...INSTRUCTION_SYNC_STRATEGIES])
-        .default(DEFAULT_INSTRUCTION_SYNC_STRATEGY))
+        .addOption(new Option('--strategy <strategy>', 'Sync strategy to check (overrides instructions.claude.shims)').choices([...INSTRUCTION_SYNC_STRATEGIES]))
         .action(async (options, command) => {
         const context = dependencies.buildCommandContext(readGlobalOptions(command));
-        const strategy = resolveInstructionSyncStrategy(options.strategy);
         try {
             const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
+            const strategy = resolveInstructionSyncStrategy(options.strategy, await dependencies.readConfiguredInstructionSyncStrategy(repoRoot));
             const exclusions = await dependencies.resolveInstructionPointerExcludes(repoRoot);
             // Warned before any work: an operator whose opt-out silently matches
             // nothing must hear about it even when validate then reports `ok`.
@@ -38,21 +39,48 @@ export function createInstructionsValidateCommand(overrides = {}) {
                 excludedPaths: exclusions.configured,
                 strategy,
             });
+            const leftovers = strategy === 'none'
+                ? await dependencies.findLeftoverClaudeFiles(repoRoot)
+                : [];
+            // The same all-or-nothing rule sync applies: while a CLAUDE.md has
+            // content of its own, sync removes none of the shims below.
+            const blockers = findShimRemovalBlockers(entries, leftovers);
+            const wouldRemove = listShimRemovals(entries);
+            const blocked = blockers.length > 0 && wouldRemove.length > 0;
             const payload = buildInstructionsPayload({
                 mode: 'validate',
-                entries,
+                strategy,
+                entries: blocked ? markBlockedShimEntries(entries) : entries,
                 actions: [],
                 excludedPaths: exclusions.configured,
                 effectiveExcludedPaths: exclusions.effective,
                 exclusionWarnings: exclusions.warnings,
+                // Warnings, never drift: they do not change the exit code.
+                warnings: [
+                    ...(blocked
+                        ? [
+                            buildShimRemovalBlockWarning(repoRoot, blockers, wouldRemove, 'validate'),
+                        ]
+                        : []),
+                    ...buildLeftoverClaudeWarnings(repoRoot, blocked
+                        ? omitHeldBackLeftovers(leftovers, wouldRemove)
+                        : leftovers),
+                ],
             });
             if (context.json) {
                 context.logger.json(payload);
             }
             else {
                 context.logger.info(formatInstructionsReport(payload, repoRoot));
-                if (payload.status === 'drift') {
-                    const fixCommand = strategy === DEFAULT_INSTRUCTION_SYNC_STRATEGY
+                for (const warning of payload.warnings ?? []) {
+                    context.logger.warn(warning.message);
+                }
+                // While the block holds, sync cannot clear this drift; the
+                // warning above names what can.
+                if (payload.status === 'drift' && !blocked) {
+                    // Repeat the flag only when this run was given one: without it,
+                    // a bare sync resolves the same configured or default strategy.
+                    const fixCommand = options.strategy === undefined
                         ? 'Fix with: oat instructions sync'
                         : `Fix with: oat instructions sync --strategy ${strategy}`;
                     context.logger.info(fixCommand);

package/dist/commands/pjm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAuB,MAAM,sBAAsB,CAAC;AAGhF,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,uBAAuB,EAA0B,MAAM,QAAQ,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAiBxD,UAAU,sBAAsB;IAC9B,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,cAAc,EAAE,OAAO,cAAc,CAAC;IACtC,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;CACvD;AA8FD,wBAAgB,gBAAgB,CAC9B,SAAS,GAAE,OAAO,CAAC,sBAAsB,CAAM,GAC9C,OAAO,CA0LT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAuB,MAAM,sBAAsB,CAAC;AAGhF,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAIL,uBAAuB,EAExB,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAiBxD,UAAU,sBAAsB;IAC9B,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,cAAc,EAAE,OAAO,cAAc,CAAC;IACtC,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;CACvD;AA8FD,wBAAgB,gBAAgB,CAC9B,SAAS,GAAE,OAAO,CAAC,sBAAsB,CAAM,GAC9C,OAAO,CA6MT"}

package/dist/commands/pjm/index.js

@@ -8,7 +8,7 @@ import { formatDoctorResults } from '../../ui/output.js';
 import { Command } from 'commander';
 import { resolvePjmAdoption } from './adoption.js';
 import { runPjmDoctorChecks } from './doctor.js';
-import { initializeRepoReference, INSTRUCTIONS_SYNC_HINT } from './init.js';
+import { AGENTS_GUIDANCE_APPENDED_MESSAGE, AGENTS_GUIDANCE_MANUAL_MESSAGE, agentsGuidanceRefusalMessage, initializeRepoReference, INSTRUCTIONS_SYNC_HINT, } from './init.js';
 import { migratePjmRepo, readPjmMigrationPrompt } from './migrate.js';
 import { createPjmRemoteCommand } from './remote/index.js';
 const DEFAULT_DEPENDENCIES = {
@@ -134,10 +134,25 @@ export function createPjmCommand(overrides = {}) {
                     context.logger.info(`Skipped existing: ${result.skipped.join(', ')}`);
                 }
                 context.logger.info(INSTRUCTIONS_SYNC_HINT);
+                const guidanceResults = Object.values(result.guidance ?? {});
+                if (guidanceResults.some(({ action }) => action === 'appended')) {
+                    context.logger.info(AGENTS_GUIDANCE_APPENDED_MESSAGE);
+                }
                 if (guidanceIncomplete) {
-                    context.logger.warn('PJM scaffold and adoption completed; AGENTS.md guidance requires manual action.');
-                    for (const guidance of Object.values(result.guidance ?? {})) {
-                        for (const line of formatAgentsMdGuidanceResult(guidance)) {
+                    const refusedPatch = guidanceResults.find(({ manualPatch }) => manualPatch?.appendRefusal !== undefined)?.manualPatch;
+                    context.logger.warn(refusedPatch?.appendRefusal
+                        ? agentsGuidanceRefusalMessage(refusedPatch.target, refusedPatch.appendRefusal)
+                        : AGENTS_GUIDANCE_MANUAL_MESSAGE);
+                    // Both writers share one combined patch; print each distinct
+                    // guidance result once per command, not once per writer.
+                    const printed = new Set();
+                    for (const guidance of guidanceResults) {
+                        const lines = formatAgentsMdGuidanceResult(guidance);
+                        const identity = lines.join('\n');
+                        if (lines.length === 0 || printed.has(identity))
+                            continue;
+                        printed.add(identity);
+                        for (const line of lines) {
                             context.logger.info(line);
                         }
                     }

package/dist/commands/pjm/init.d.ts

@@ -16,6 +16,9 @@ export interface RepoReferenceInitResult {
     };
 }
 export declare const INSTRUCTIONS_SYNC_HINT: string;
+export declare const AGENTS_GUIDANCE_APPENDED_MESSAGE = "AGENTS.md guidance: appended the absent OAT managed blocks to the existing AGENTS.md.";
+export declare const AGENTS_GUIDANCE_MANUAL_MESSAGE: string;
+export declare function agentsGuidanceRefusalMessage(target: string, cause: string): string;
 export declare const CANONICAL_REPO_REFERENCE_PATHS: readonly [...("AGENTS.md" | "README.md" | "pjm/AGENTS.md" | "pjm/current-state.md" | "pjm/handoffs/README.md" | "pjm/roadmap.md" | "reference/AGENTS.md")[], "pjm/backlog/index.md", "pjm/backlog/completed.md", "pjm/backlog/items/.gitkeep", "pjm/backlog/archived/.gitkeep", "reference/decisions/AGENTS.md", "reference/decisions/index.md"];
 export declare const PJM_ADOPTION_SCHEMA_VERSION = 1;
 export declare function initializeRepoReference(options: InitializeRepoReferenceOptions): Promise<RepoReferenceInitResult>;

package/dist/commands/pjm/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/init.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,4BAA4B,CAAC;AAMpC,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE;QACR,iBAAiB,EAAE,mBAAmB,CAAC;QACvC,SAAS,EAAE,mBAAmB,CAAC;KAChC,CAAC;CACH;AAoBD,eAAO,MAAM,sBAAsB,QAEiD,CAAC;AAerF,eAAO,MAAM,8BAA8B,kVAIjC,CAAC;AAEX,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAiC7C,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,uBAAuB,CAAC,CAsHlC"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/init.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,4BAA4B,CAAC;AAMpC,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE;QACR,iBAAiB,EAAE,mBAAmB,CAAC;QACvC,SAAS,EAAE,mBAAmB,CAAC;KAChC,CAAC;CACH;AAsBD,eAAO,MAAM,sBAAsB,QAIoB,CAAC;AAOxD,eAAO,MAAM,gCAAgC,0FAC4C,CAAC;AAC1F,eAAO,MAAM,8BAA8B,QAG4C,CAAC;AACxF,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,MAAM,CAMR;AAeD,eAAO,MAAM,8BAA8B,kVAIjC,CAAC;AAEX,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAiC7C,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,uBAAuB,CAAC,CAsHlC"}

package/dist/commands/pjm/init.js

@@ -17,11 +17,29 @@ const TEMPLATE_TARGETS = [
     { template: 'repo-readme.md', target: 'README.md' },
     { template: 'pjm-handoffs-readme.md', target: 'pjm/handoffs/README.md' },
 ];
-// Next-step hint printed after init/backfill. `oat pjm init` never writes
-// CLAUDE.md shims itself — strategy ownership stays with `oat instructions
-// sync`, so we point the operator at it (with the `--dry-run` preview).
-export const INSTRUCTIONS_SYNC_HINT = 'Next step: run `oat instructions sync` to create CLAUDE.md shims for the ' +
-    'repo-reference AGENTS.md files (preview with `oat instructions sync --dry-run`).';
+// Next-step hint printed after init/backfill. `oat pjm init` never writes or
+// removes CLAUDE.md files itself — strategy ownership stays with
+// `oat instructions sync`, so we point the operator at it (with the
+// `--dry-run` preview). It must not promise shims: the default strategy is
+// `none` (DR-260927-claude-md-shims-are-opt), so shims are opt-in.
+export const INSTRUCTIONS_SYNC_HINT = 'Next step: run `oat instructions sync` to check the repo-reference AGENTS.md ' +
+    'files against your CLAUDE.md strategy (preview with `oat instructions sync --dry-run`). ' +
+    'No CLAUDE.md shims are created by default; opt in with ' +
+    '`oat config set instructions.claude.shims pointer`.';
+// AGENTS.md guidance messages printed by `oat pjm init`. An absent managed
+// block is appended to an existing AGENTS.md. The printed manual patch is
+// needed when a block is present but differs from the managed version, or
+// when OAT refuses to append at all (for example a hard-linked or unwritable
+// AGENTS.md); the refusal gets its own header.
+export const AGENTS_GUIDANCE_APPENDED_MESSAGE = 'AGENTS.md guidance: appended the absent OAT managed blocks to the existing AGENTS.md.';
+export const AGENTS_GUIDANCE_MANUAL_MESSAGE = 'PJM scaffold and adoption completed; AGENTS.md guidance requires manual action. ' +
+    'Absent managed blocks are appended automatically, but an existing block ' +
+    'differs from the managed version: apply the patch below, then rerun `oat pjm init`.';
+export function agentsGuidanceRefusalMessage(target, cause) {
+    return ('PJM scaffold and adoption completed; AGENTS.md guidance requires manual action. ' +
+        `OAT could not append the absent guidance blocks to ${target} (${cause}), ` +
+        'so nothing was written: apply the patch below, then rerun `oat pjm init`.');
+}
 const BACKLOG_PATHS = [
     'pjm/backlog/index.md',
     'pjm/backlog/completed.md',