@open-agent-toolkit/cli 0.0.30 → 0.0.32

package/dist/commands/instructions/instructions.utils.js

@@ -1,6 +1,7 @@
-import { readdir, readFile, stat } from 'node:fs/promises';
-import { dirname, join, relative } from 'node:path';
+import { lstat, readdir, readFile, readlink, realpath, stat, } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
 export const EXPECTED_CLAUDE_CONTENT = '@AGENTS.md\n';
+export const DEFAULT_INSTRUCTION_SYNC_STRATEGY = 'pointer';
 const ROOT_EXCLUDED_DIRECTORIES = new Set(['.git', '.oat', '.worktrees']);
 const GLOBAL_EXCLUDED_DIRECTORIES = new Set(['node_modules']);
 function getErrorCode(error) {
@@ -11,12 +12,37 @@ function getErrorCode(error) {
 function normalizeLineEndings(content) {
     return content.replaceAll('\r\n', '\n');
 }
+export function resolveInstructionSyncStrategy(strategy) {
+    return strategy ?? DEFAULT_INSTRUCTION_SYNC_STRATEGY;
+}
+function getValidInstructionDetail(strategy) {
+    switch (strategy) {
+        case 'symlink':
+            return 'symlink valid';
+        case 'copy':
+            return 'copy valid';
+        default:
+            return 'pointer valid';
+    }
+}
+function getInvalidInstructionDetail(strategy) {
+    switch (strategy) {
+        case 'symlink':
+            return 'expected symlink to AGENTS.md';
+        case 'copy':
+            return 'expected hard copy of AGENTS.md content';
+        default:
+            return `expected ${JSON.stringify(EXPECTED_CLAUDE_CONTENT)}`;
+    }
+}
 function toPosixPath(pathValue) {
     return pathValue.replaceAll('\\', '/');
 }
 function normalizeEntries(entries) {
     return [...entries].sort((left, right) => {
-        return (left.agentsPath.localeCompare(right.agentsPath) ||
+        const leftSortPath = left.agentsPath ?? left.claudePath;
+        const rightSortPath = right.agentsPath ?? right.claudePath;
+        return (leftSortPath.localeCompare(rightSortPath) ||
             left.claudePath.localeCompare(right.claudePath) ||
             left.status.localeCompare(right.status) ||
             left.detail.localeCompare(right.detail));
@@ -30,9 +56,23 @@ function normalizeActions(actions) {
             left.reason.localeCompare(right.reason));
     });
 }
-async function scanAgentsFiles(repoRoot, dependencies) {
+function recordInstructionFile(directoryEntries, directoryPath, entryName, entryPath) {
+    const current = directoryEntries.get(directoryPath) ?? {};
+    if (entryName === 'AGENTS.md') {
+        current.agentsPath = entryPath;
+        current.brokenAgentsPath = undefined;
+        current.brokenAgentsErrorCode = undefined;
+    }
+    else {
+        current.claudePath = entryPath;
+        current.brokenClaudePath = undefined;
+        current.brokenClaudeErrorCode = undefined;
+    }
+    directoryEntries.set(directoryPath, current);
+}
+async function scanInstructionDirectories(repoRoot, dependencies, debug) {
     const queue = [repoRoot];
-    const agentsFiles = [];
+    const directoryEntries = new Map();
     while (queue.length > 0) {
         const currentDirectory = queue.shift();
         if (!currentDirectory) {
@@ -46,7 +86,7 @@ async function scanAgentsFiles(repoRoot, dependencies) {
         }
         catch (error) {
             const errorCode = getErrorCode(error);
-            dependencies.debug?.(`Skipping directory scan for ${toPosixPath(currentDirectory)} (${errorCode ?? 'unknown error'})`);
+            debug?.(`Skipping directory scan for ${toPosixPath(currentDirectory)} (${errorCode ?? 'unknown error'})`);
             continue;
         }
         for (const entry of entries) {
@@ -63,8 +103,8 @@ async function scanAgentsFiles(repoRoot, dependencies) {
                 continue;
             }
             if (entry.isFile()) {
-                if (entry.name === 'AGENTS.md') {
-                    agentsFiles.push(entryPath);
+                if (entry.name === 'AGENTS.md' || entry.name === 'CLAUDE.md') {
+                    recordInstructionFile(directoryEntries, currentDirectory, entry.name, entryPath);
                 }
                 continue;
             }
@@ -77,38 +117,157 @@ async function scanAgentsFiles(repoRoot, dependencies) {
             }
             catch (error) {
                 const errorCode = getErrorCode(error);
-                dependencies.debug?.(`Skipping symlink target stat for ${toPosixPath(entryPath)} (${errorCode ?? 'unknown error'})`);
+                if (entry.name === 'CLAUDE.md') {
+                    const current = directoryEntries.get(currentDirectory) ?? {};
+                    current.claudePath = entryPath;
+                    current.brokenClaudePath = entryPath;
+                    current.brokenClaudeErrorCode = errorCode ?? 'unknown error';
+                    directoryEntries.set(currentDirectory, current);
+                    continue;
+                }
+                if (entry.name === 'AGENTS.md') {
+                    const current = directoryEntries.get(currentDirectory) ?? {};
+                    current.brokenAgentsPath = entryPath;
+                    current.brokenAgentsErrorCode = errorCode ?? 'unknown error';
+                    directoryEntries.set(currentDirectory, current);
+                    continue;
+                }
+                debug?.(`Skipping symlink target stat for ${toPosixPath(entryPath)} (${errorCode ?? 'unknown error'})`);
                 continue;
             }
             if (entryStats.isDirectory()) {
                 continue;
             }
-            if (entryStats.isFile() && entry.name === 'AGENTS.md') {
-                agentsFiles.push(entryPath);
+            if (entryStats.isFile() &&
+                (entry.name === 'AGENTS.md' || entry.name === 'CLAUDE.md')) {
+                recordInstructionFile(directoryEntries, currentDirectory, entry.name, entryPath);
             }
         }
     }
-    return agentsFiles.sort((left, right) => left.localeCompare(right));
+    return directoryEntries;
 }
-export async function scanInstructionFiles(repoRoot, overrides = {}) {
+export async function scanInstructionFiles(repoRoot, options = {}, overrides = {}) {
+    const strategy = resolveInstructionSyncStrategy(options.strategy);
     const dependencies = {
+        lstat,
+        realpath,
         readdir,
         readFile,
+        readlink,
         stat,
         ...overrides,
     };
-    const agentsFiles = await scanAgentsFiles(repoRoot, dependencies);
+    const instructionDirectories = await scanInstructionDirectories(repoRoot, dependencies, options.debug);
     const entries = [];
-    for (const agentsPath of agentsFiles) {
-        const claudePath = join(dirname(agentsPath), 'CLAUDE.md');
+    for (const [directoryPath, directoryEntry] of instructionDirectories) {
+        const agentsPath = directoryEntry.agentsPath ?? null;
+        const brokenAgentsPath = directoryEntry.brokenAgentsPath ?? null;
+        const brokenAgentsErrorCode = directoryEntry.brokenAgentsErrorCode ?? 'unknown error';
+        const brokenClaudePath = directoryEntry.brokenClaudePath ?? null;
+        const brokenClaudeErrorCode = directoryEntry.brokenClaudeErrorCode ?? 'unknown error';
+        const claudePath = directoryEntry.claudePath ?? join(directoryPath, 'CLAUDE.md');
+        if (!agentsPath && brokenAgentsPath) {
+            entries.push({
+                agentsPath: brokenAgentsPath,
+                claudePath,
+                status: 'content_mismatch',
+                detail: brokenAgentsErrorCode === 'ENOENT'
+                    ? 'broken AGENTS.md symlink'
+                    : `unreadable AGENTS.md symlink target (${brokenAgentsErrorCode})`,
+            });
+            continue;
+        }
+        if (brokenClaudePath) {
+            entries.push({
+                agentsPath,
+                claudePath,
+                status: 'content_mismatch',
+                detail: brokenClaudeErrorCode === 'ENOENT'
+                    ? 'broken CLAUDE.md symlink'
+                    : `unreadable CLAUDE.md symlink target (${brokenClaudeErrorCode})`,
+            });
+            continue;
+        }
+        if (!agentsPath) {
+            try {
+                await dependencies.readFile(claudePath, 'utf8');
+            }
+            catch (error) {
+                entries.push({
+                    agentsPath: null,
+                    claudePath,
+                    status: 'content_mismatch',
+                    detail: `unable to read CLAUDE.md (${getErrorCode(error) ?? 'unknown'})`,
+                });
+                continue;
+            }
+            entries.push({
+                agentsPath: null,
+                claudePath,
+                status: 'stray',
+                detail: 'CLAUDE.md found without AGENTS.md',
+            });
+            continue;
+        }
+        let claudeStats;
         try {
-            const claudeContent = await dependencies.readFile(claudePath, 'utf8');
-            if (normalizeLineEndings(claudeContent) === EXPECTED_CLAUDE_CONTENT) {
+            claudeStats = await dependencies.lstat(claudePath);
+        }
+        catch (error) {
+            const errorCode = getErrorCode(error);
+            if (errorCode === 'ENOENT') {
+                entries.push({
+                    agentsPath,
+                    claudePath,
+                    status: 'missing',
+                    detail: 'CLAUDE.md missing',
+                });
+            }
+            else {
+                entries.push({
+                    agentsPath,
+                    claudePath,
+                    status: 'content_mismatch',
+                    detail: `unable to read CLAUDE.md (${errorCode ?? 'unknown error'})`,
+                });
+            }
+            continue;
+        }
+        if (strategy === 'symlink') {
+            if (!claudeStats.isSymbolicLink()) {
+                entries.push({
+                    agentsPath,
+                    claudePath,
+                    status: 'content_mismatch',
+                    detail: getInvalidInstructionDetail(strategy),
+                });
+                continue;
+            }
+            let claudeTarget;
+            try {
+                claudeTarget = await dependencies.readlink(claudePath);
+            }
+            catch (error) {
+                const errorCode = getErrorCode(error);
+                entries.push({
+                    agentsPath,
+                    claudePath,
+                    status: 'content_mismatch',
+                    detail: `unable to read CLAUDE.md symlink target (${errorCode ?? 'unknown error'})`,
+                });
+                continue;
+            }
+            const resolvedTarget = resolve(dirname(claudePath), claudeTarget);
+            const [canonicalTarget, canonicalAgentsPath] = await Promise.all([
+                dependencies.realpath(resolvedTarget).catch(() => resolvedTarget),
+                dependencies.realpath(agentsPath).catch(() => agentsPath),
+            ]);
+            if (canonicalTarget === canonicalAgentsPath) {
                 entries.push({
                     agentsPath,
                     claudePath,
                     status: 'ok',
-                    detail: 'pointer valid',
+                    detail: getValidInstructionDetail(strategy),
                 });
             }
             else {
@@ -116,9 +275,23 @@ export async function scanInstructionFiles(repoRoot, overrides = {}) {
                     agentsPath,
                     claudePath,
                     status: 'content_mismatch',
-                    detail: `expected ${JSON.stringify(EXPECTED_CLAUDE_CONTENT)}`,
+                    detail: getInvalidInstructionDetail(strategy),
                 });
             }
+            continue;
+        }
+        if (claudeStats.isSymbolicLink()) {
+            entries.push({
+                agentsPath,
+                claudePath,
+                status: 'content_mismatch',
+                detail: getInvalidInstructionDetail(strategy),
+            });
+            continue;
+        }
+        let claudeContent;
+        try {
+            claudeContent = await dependencies.readFile(claudePath, 'utf8');
         }
         catch (error) {
             const errorCode = getErrorCode(error);
@@ -138,6 +311,44 @@ export async function scanInstructionFiles(repoRoot, overrides = {}) {
                     detail: `unable to read CLAUDE.md (${errorCode ?? 'unknown error'})`,
                 });
             }
+            continue;
+        }
+        const expectedContent = strategy === 'copy'
+            ? await (async () => {
+                try {
+                    return await dependencies.readFile(agentsPath, 'utf8');
+                }
+                catch (error) {
+                    const errorCode = getErrorCode(error);
+                    entries.push({
+                        agentsPath,
+                        claudePath,
+                        status: 'content_mismatch',
+                        detail: `unable to read AGENTS.md (${errorCode ?? 'unknown error'})`,
+                    });
+                    return null;
+                }
+            })()
+            : EXPECTED_CLAUDE_CONTENT;
+        if (expectedContent === null) {
+            continue;
+        }
+        if (normalizeLineEndings(claudeContent) ===
+            normalizeLineEndings(expectedContent)) {
+            entries.push({
+                agentsPath,
+                claudePath,
+                status: 'ok',
+                detail: getValidInstructionDetail(strategy),
+            });
+        }
+        else {
+            entries.push({
+                agentsPath,
+                claudePath,
+                status: 'content_mismatch',
+                detail: getInvalidInstructionDetail(strategy),
+            });
         }
     }
     return normalizeEntries(entries);
@@ -151,6 +362,7 @@ export function buildInstructionsSummary(entries, actions) {
         missing: normalizedEntries.filter((entry) => entry.status === 'missing')
             .length,
         contentMismatch: normalizedEntries.filter((entry) => entry.status === 'content_mismatch').length,
+        stray: normalizedEntries.filter((entry) => entry.status === 'stray').length,
         created: normalizedActions.filter((action) => action.type === 'create')
             .length,
         updated: normalizedActions.filter((action) => action.type === 'update')
@@ -181,7 +393,7 @@ export function formatInstructionsReport(payload, repoRoot) {
     const lines = [
         `instructions ${payload.mode}`,
         `status: ${payload.status}`,
-        `summary: scanned=${payload.summary.scanned}, ok=${payload.summary.ok}, missing=${payload.summary.missing}, content_mismatch=${payload.summary.contentMismatch}, created=${payload.summary.created}, updated=${payload.summary.updated}, skipped=${payload.summary.skipped}`,
+        `summary: scanned=${payload.summary.scanned}, ok=${payload.summary.ok}, missing=${payload.summary.missing}, content_mismatch=${payload.summary.contentMismatch}, stray=${payload.summary.stray}, created=${payload.summary.created}, updated=${payload.summary.updated}, skipped=${payload.summary.skipped}`,
     ];
     if (payload.entries.length === 0) {
         lines.push('entries: none');
@@ -189,10 +401,11 @@ export function formatInstructionsReport(payload, repoRoot) {
     else {
         lines.push('entries:');
         for (const entry of payload.entries) {
-            const agentsPath = repoRoot
-                ? toPosixPath(relative(repoRoot, entry.agentsPath)) || '.'
-                : toPosixPath(entry.agentsPath);
-            lines.push(`- ${agentsPath} -> ${entry.status} (${entry.detail})`);
+            const displayPath = entry.agentsPath ?? entry.claudePath;
+            const relativePath = repoRoot
+                ? toPosixPath(relative(repoRoot, displayPath)) || '.'
+                : toPosixPath(displayPath);
+            lines.push(`- ${relativePath} -> ${entry.status} (${entry.detail})`);
         }
     }
     if (payload.actions.length === 0) {

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

@@ -1,4 +1,6 @@
-import type { InstructionsSyncCommandDependencies } from '../../instructions/instructions.types.js';
+import { rm } from 'node:fs/promises';
+import { type InstructionsSyncCommandDependencies } from '../../instructions/instructions.types.js';
 import { Command } from 'commander';
+export declare function removeInstructionFile(path: string, remove?: typeof rm): Promise<void>;
 export declare function createInstructionsSyncCommand(overrides?: Partial<InstructionsSyncCommandDependencies>): Command;
 //# sourceMappingURL=sync.d.ts.map

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":"AAGA,OAAO,KAAK,EAGV,mCAAmC,EACpC,MAAM,2CAA2C,CAAC;AAUnD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmHpC,wBAAgB,6BAA6B,CAC3C,SAAS,GAAE,OAAO,CAAC,mCAAmC,CAAM,GAC3D,OAAO,CA+DT"}
+{"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;AAYnD,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;AA+SD,wBAAgB,6BAA6B,CAC3C,SAAS,GAAE,OAAO,CAAC,mCAAmC,CAAM,GAC3D,OAAO,CA6FT"}

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

@@ -1,26 +1,96 @@
-import { writeFile } from 'node:fs/promises';
+import { lstat, readFile, rm, symlink, writeFile } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
 import { buildCommandContext } from '../../../app/command-context.js';
-import { buildInstructionsPayload, EXPECTED_CLAUDE_CONTENT, formatInstructionsReport, scanInstructionFiles, } from '../../instructions/instructions.utils.js';
+import { INSTRUCTION_SYNC_STRATEGIES, } from '../../instructions/instructions.types.js';
+import { buildInstructionsPayload, DEFAULT_INSTRUCTION_SYNC_STRATEGY, EXPECTED_CLAUDE_CONTENT, formatInstructionsReport, 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';
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
+export async function removeInstructionFile(path, remove = rm) {
+    await remove(path, { force: true });
+}
 function defaultDependencies() {
     return {
         buildCommandContext,
+        lstat,
+        readFile,
+        removeFile: removeInstructionFile,
         resolveProjectRoot,
         scanInstructionFiles,
+        symlinkFile: async (target, path) => {
+            await symlink(target, path, 'file');
+        },
         writeFile,
     };
 }
-function planSyncActions({ entries, force, }) {
+function getSyncReason(actionType, strategy) {
+    const label = strategy === 'symlink'
+        ? 'symlink'
+        : strategy === 'copy'
+            ? 'hard copy'
+            : 'pointer file';
+    return actionType === 'create'
+        ? `missing CLAUDE.md ${label}`
+        : `overwrite CLAUDE.md with canonical ${label}`;
+}
+function getSyncedDetail(strategy) {
+    switch (strategy) {
+        case 'symlink':
+            return 'symlink synced';
+        case 'copy':
+            return 'copy synced';
+        default:
+            return 'pointer synced';
+    }
+}
+function getAgentsPath(entry) {
+    return entry.agentsPath ?? join(dirname(entry.claudePath), 'AGENTS.md');
+}
+function getErrorCode(error) {
+    return error && typeof error === 'object' && 'code' in error
+        ? String(error.code)
+        : null;
+}
+function hasUnreadableCanonicalAgents(entry) {
+    return (entry.agentsPath !== null &&
+        (entry.detail === 'broken AGENTS.md symlink' ||
+            entry.detail.startsWith('unreadable AGENTS.md symlink target') ||
+            entry.detail.startsWith('unable to read AGENTS.md')));
+}
+function hasUnreadableClaudeSource(entry) {
+    return (entry.agentsPath === null &&
+        (entry.detail === 'broken CLAUDE.md symlink' ||
+            entry.detail.startsWith('unreadable CLAUDE.md symlink target') ||
+            entry.detail.startsWith('unable to read CLAUDE.md')));
+}
+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);
+}
+function planSyncActions({ entries, force, strategy, }) {
     const actions = [];
     for (const entry of entries) {
+        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: 'update',
+                target: entry.claudePath,
+                reason: getSyncReason('update', strategy),
+                result: 'planned',
+            });
+            continue;
+        }
         if (entry.status === 'missing') {
             actions.push({
                 type: 'create',
                 target: entry.claudePath,
-                reason: 'missing CLAUDE.md pointer file',
+                reason: getSyncReason('create', strategy),
                 result: 'planned',
             });
             continue;
@@ -28,6 +98,28 @@ function planSyncActions({ entries, force, }) {
         if (entry.status !== 'content_mismatch') {
             continue;
         }
+        if (hasUnreadableClaudeSource(entry)) {
+            actions.push({
+                type: 'skip',
+                target: entry.claudePath,
+                reason: 'CLAUDE.md unreadable; repair manually',
+                result: 'skipped',
+            });
+            continue;
+        }
+        if (hasUnreadableCanonicalAgents(entry)) {
+            const unreadableAgentsPath = entry.agentsPath;
+            if (!unreadableAgentsPath) {
+                throw new CliError(`Unable to resolve unreadable AGENTS.md path for ${entry.claudePath}`, 2);
+            }
+            actions.push({
+                type: 'skip',
+                target: unreadableAgentsPath,
+                reason: 'canonical AGENTS.md unreadable; repair manually',
+                result: 'skipped',
+            });
+            continue;
+        }
         if (!force) {
             actions.push({
                 type: 'skip',
@@ -40,20 +132,76 @@ function planSyncActions({ entries, force, }) {
         actions.push({
             type: 'update',
             target: entry.claudePath,
-            reason: 'overwrite CLAUDE.md with canonical pointer',
+            reason: getSyncReason('update', strategy),
             result: 'planned',
         });
     }
     return actions;
 }
-async function applySyncActions(actions, dependencies) {
+async function applySyncActions(actions, entries, dependencies, strategy) {
     const appliedActions = [];
+    const entriesByTarget = new Map();
+    for (const entry of entries) {
+        entriesByTarget.set(entry.claudePath, entry);
+        entriesByTarget.set(getAgentsPath(entry), entry);
+    }
     for (const action of actions) {
         if (action.result !== 'planned') {
             appliedActions.push(action);
             continue;
         }
-        await dependencies.writeFile(action.target, EXPECTED_CLAUDE_CONTENT, 'utf8');
+        const entry = entriesByTarget.get(action.target);
+        if (!entry) {
+            throw new CliError(`Unable to resolve instruction entry for ${action.target}`, 2);
+        }
+        const agentsPath = getAgentsPath(entry);
+        const isAgentsAction = action.target === agentsPath;
+        if (isAgentsAction) {
+            try {
+                await dependencies.lstat(agentsPath);
+                throw new CliError(`Canonical AGENTS.md appeared during sync at ${agentsPath}; re-run to reclassify before adopting stray CLAUDE.md`, 2);
+            }
+            catch (error) {
+                if (error instanceof CliError) {
+                    throw error;
+                }
+                if (getErrorCode(error) !== 'ENOENT') {
+                    throw error;
+                }
+            }
+            const adoptedContent = await dependencies.readFile(entry.claudePath, 'utf8');
+            await dependencies.writeFile(agentsPath, adoptedContent, 'utf8');
+            appliedActions.push({
+                ...action,
+                result: 'applied',
+            });
+            continue;
+        }
+        if (!entry.agentsPath && action.type !== 'update') {
+            throw new CliError(`Unable to resolve AGENTS.md for ${action.target}`, 2);
+        }
+        try {
+            if (action.type === 'update') {
+                await dependencies.removeFile(action.target);
+            }
+            if (strategy === 'symlink') {
+                const symlinkTarget = relative(dirname(action.target), agentsPath);
+                await dependencies.symlinkFile(symlinkTarget, action.target);
+            }
+            else if (strategy === 'copy') {
+                const agentsContent = await dependencies.readFile(agentsPath, 'utf8');
+                await dependencies.writeFile(action.target, agentsContent, 'utf8');
+            }
+            else {
+                await dependencies.writeFile(action.target, EXPECTED_CLAUDE_CONTENT, 'utf8');
+            }
+        }
+        catch (error) {
+            if (entry.status === 'stray') {
+                throw wrapStrayResyncError(error, agentsPath, action.target);
+            }
+            throw error;
+        }
         appliedActions.push({
             ...action,
             result: 'applied',
@@ -61,18 +209,21 @@ async function applySyncActions(actions, dependencies) {
     }
     return appliedActions;
 }
-function getPostSyncEntries(entries, actions) {
+function getPostSyncEntries(entries, actions, strategy) {
     const actionByTarget = new Map(actions.map((action) => [action.target, action]));
     return entries.map((entry) => {
         const action = actionByTarget.get(entry.claudePath);
-        if (!action) {
+        const adoptedAction = actionByTarget.get(getAgentsPath(entry));
+        if (!action && !adoptedAction) {
             return entry;
         }
-        if (action.result === 'applied' && action.type !== 'skip') {
+        if (action?.result === 'applied' &&
+            (entry.status !== 'stray' || adoptedAction?.result === 'applied')) {
             return {
                 ...entry,
+                agentsPath: getAgentsPath(entry),
                 status: 'ok',
-                detail: 'pointer synced',
+                detail: getSyncedDetail(strategy),
             };
         }
         return entry;
@@ -87,25 +238,34 @@ export function createInstructionsSyncCommand(overrides = {}) {
         ...overrides,
     };
     return new Command('sync')
-        .description('Repair AGENTS.md to CLAUDE.md pointer drift')
+        .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))
         .action(async (options, command) => {
         const context = dependencies.buildCommandContext(readGlobalOptions(command));
         try {
             const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
-            const entries = await dependencies.scanInstructionFiles(repoRoot);
+            const strategy = resolveInstructionSyncStrategy(options.strategy);
+            const entries = await dependencies.scanInstructionFiles(repoRoot, {
+                strategy,
+            });
             const plannedActions = planSyncActions({
                 entries,
                 force: options.force ?? false,
+                strategy,
             });
             const dryRun = options.dryRun ?? false;
             const actions = dryRun
                 ? plannedActions
-                : await applySyncActions(plannedActions, dependencies);
+                : await applySyncActions(plannedActions, entries, dependencies, strategy);
             const payload = buildInstructionsPayload({
                 mode: dryRun ? 'dry-run' : 'apply',
-                entries: dryRun ? entries : getPostSyncEntries(entries, actions),
+                entries: dryRun
+                    ? entries
+                    : getPostSyncEntries(entries, actions, strategy),
                 actions,
             });
             if (context.json) {

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

@@ -1,4 +1,4 @@
-import type { InstructionsValidateCommandDependencies } from '../../instructions/instructions.types.js';
+import { type InstructionsValidateCommandDependencies } from '../../instructions/instructions.types.js';
 import { Command } from 'commander';
 export declare function createInstructionsValidateCommand(overrides?: Partial<InstructionsValidateCommandDependencies>): Command;
 //# sourceMappingURL=validate.d.ts.map

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,KAAK,EAAE,uCAAuC,EAAE,MAAM,2CAA2C,CAAC;AASzG,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC,wBAAgB,iCAAiC,CAC/C,SAAS,GAAE,OAAO,CAAC,uCAAuC,CAAM,GAC/D,OAAO,CA0CT"}
+{"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;AAWnD,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAU5C,wBAAgB,iCAAiC,CAC/C,SAAS,GAAE,OAAO,CAAC,uCAAuC,CAAM,GAC/D,OAAO,CA2DT"}