@open-agent-toolkit/cli 0.3.8 → 0.3.10

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

@@ -1,8 +1,8 @@
 import { lstat, readdir, readFile, readlink, realpath, stat, } from 'node:fs/promises';
-import { dirname, join, posix, relative, resolve } from 'node:path';
-import { readOatConfig, resolveDocumentationContentRoot, } from '../../config/oat-config.js';
+import { basename, dirname, join, posix, relative, resolve } from 'node:path';
+import { DEFAULT_INSTRUCTION_SYNC_STRATEGY, readOatConfig, resolveDocumentationContentRoot, } from '../../config/oat-config.js';
 export const EXPECTED_CLAUDE_CONTENT = '@AGENTS.md\n';
-export const DEFAULT_INSTRUCTION_SYNC_STRATEGY = 'pointer';
+export { DEFAULT_INSTRUCTION_SYNC_STRATEGY };
 const ROOT_EXCLUDED_DIRECTORIES = new Set(['.git', '.oat', '.worktrees']);
 const GLOBAL_EXCLUDED_DIRECTORIES = new Set(['node_modules']);
 // The only excluded-subtree re-entry points: a root-level directory is excluded
@@ -30,11 +30,337 @@ function getErrorCode(error) {
 function normalizeLineEndings(content) {
     return content.replaceAll('\r\n', '\n');
 }
-export function resolveInstructionSyncStrategy(strategy) {
-    return strategy ?? DEFAULT_INSTRUCTION_SYNC_STRATEGY;
+function readFileBytesDefault(path) {
+    return readFile(path);
+}
+/**
+ * The exact pointer files OAT writes: `@AGENTS.md` and a newline, with the
+ * CRLF form a Windows checkout produces. Nothing else is a managed pointer --
+ * not trailing whitespace, not a missing newline, not extra lines.
+ */
+const MANAGED_POINTER_BYTES = [
+    Buffer.from(EXPECTED_CLAUDE_CONTENT, 'utf8'),
+    Buffer.from('@AGENTS.md\r\n', 'utf8'),
+];
+/**
+ * Classify one CLAUDE.md against the exact shapes OAT writes, beside its
+ * sibling AGENTS.md. This is the single definition of "OAT-managed" that both
+ * planning (the scan) and apply-time re-verification use, so the two can never
+ * disagree about what may be deleted.
+ *
+ * Anything that is not provably one of the three shapes is `unmanaged`, which
+ * is never deleted: a CLAUDE.md not named exactly `CLAUDE.md`, one inside a
+ * `.claude` directory, a symlink whose target is not the sibling AGENTS.md,
+ * and any regular file whose bytes are not exactly a pointer or an exact copy.
+ */
+export async function inspectManagedShim(claudePath, agentsPath, dependencies) {
+    const directoryPath = dirname(claudePath);
+    if (basename(claudePath) !== 'CLAUDE.md' ||
+        basename(directoryPath) === '.claude' ||
+        agentsPath !== join(directoryPath, 'AGENTS.md')) {
+        return {
+            kind: 'unmanaged',
+            detail: 'not a CLAUDE.md beside its AGENTS.md; kept',
+        };
+    }
+    let claudeStats;
+    try {
+        claudeStats = await dependencies.lstat(claudePath);
+    }
+    catch (error) {
+        const errorCode = getErrorCode(error);
+        return errorCode === 'ENOENT'
+            ? { kind: 'absent' }
+            : {
+                kind: 'unreadable',
+                detail: `unable to read CLAUDE.md (${errorCode ?? 'unknown error'})`,
+            };
+    }
+    const identity = { dev: claudeStats.dev, ino: claudeStats.ino };
+    if (claudeStats.isSymbolicLink()) {
+        let linkTarget;
+        try {
+            linkTarget = await dependencies.readlink(claudePath);
+        }
+        catch (error) {
+            return {
+                kind: 'unreadable',
+                detail: `unable to read CLAUDE.md symlink target (${getErrorCode(error) ?? 'unknown error'})`,
+            };
+        }
+        // Lexical, not realpath: only a link that names the sibling AGENTS.md is
+        // the shape OAT writes. A link that merely resolves to the same file
+        // through another path was made by someone else.
+        if (resolve(directoryPath, linkTarget) !== agentsPath) {
+            return {
+                kind: 'unmanaged',
+                detail: `CLAUDE.md symlink targets ${JSON.stringify(linkTarget)}, not the sibling AGENTS.md; kept`,
+            };
+        }
+        return {
+            kind: 'managed',
+            record: { shape: 'symlink', ...identity, linkTarget },
+        };
+    }
+    if (!claudeStats.isFile()) {
+        return {
+            kind: 'unmanaged',
+            detail: 'CLAUDE.md is not a regular file or symlink; kept',
+        };
+    }
+    // A regular CLAUDE.md that the sibling AGENTS.md resolves to -- the
+    // Claude-first `ln -s CLAUDE.md AGENTS.md` layout, or a hard link -- holds
+    // the only copy of the instructions. Comparing the two would compare the
+    // file with itself, so it is never a managed shape of any kind.
+    let agentsStats;
+    try {
+        agentsStats = await dependencies.lstat(agentsPath);
+    }
+    catch (error) {
+        return {
+            kind: 'unreadable',
+            detail: `unable to read AGENTS.md (${getErrorCode(error) ?? 'unknown error'})`,
+        };
+    }
+    let agentsResolvesToClaude = agentsStats.dev === claudeStats.dev && agentsStats.ino === claudeStats.ino;
+    if (agentsStats.isSymbolicLink()) {
+        try {
+            const [realAgents, realClaude] = await Promise.all([
+                dependencies.realpath(agentsPath),
+                dependencies.realpath(claudePath),
+            ]);
+            agentsResolvesToClaude = realAgents === realClaude;
+        }
+        catch (error) {
+            return {
+                kind: 'unreadable',
+                detail: `unable to resolve AGENTS.md (${getErrorCode(error) ?? 'unknown error'})`,
+            };
+        }
+    }
+    if (agentsResolvesToClaude) {
+        return {
+            kind: 'unmanaged',
+            detail: 'AGENTS.md resolves to this CLAUDE.md, so CLAUDE.md holds the instructions ' +
+                '(replace the AGENTS.md link with its content before removing CLAUDE.md); kept',
+        };
+    }
+    let claudeBytes;
+    try {
+        claudeBytes = await dependencies.readFileBytes(claudePath);
+    }
+    catch (error) {
+        return {
+            kind: 'unreadable',
+            detail: `unable to read CLAUDE.md (${getErrorCode(error) ?? 'unknown error'})`,
+        };
+    }
+    if (MANAGED_POINTER_BYTES.some((pointer) => pointer.equals(claudeBytes))) {
+        return { kind: 'managed', record: { shape: 'pointer', ...identity } };
+    }
+    // The copy shape is only ever judged against a distinct regular AGENTS.md:
+    // identical bytes behind a symlink prove nothing about who wrote CLAUDE.md.
+    if (!agentsStats.isFile()) {
+        return {
+            kind: 'unmanaged',
+            detail: 'AGENTS.md is not a regular file, so CLAUDE.md is not a managed copy; kept',
+        };
+    }
+    let agentsBytes;
+    try {
+        agentsBytes = await dependencies.readFileBytes(agentsPath);
+    }
+    catch (error) {
+        return {
+            kind: 'unreadable',
+            detail: `unable to read AGENTS.md (${getErrorCode(error) ?? 'unknown error'})`,
+        };
+    }
+    if (agentsBytes.equals(claudeBytes)) {
+        return { kind: 'managed', record: { shape: 'copy', ...identity } };
+    }
+    return {
+        kind: 'unmanaged',
+        detail: 'hand-written or modified CLAUDE.md; kept',
+    };
+}
+/**
+ * The path of a directory entry itself, with its parent directories resolved
+ * but the entry not followed, so a link and the file it names compare by the
+ * node they occupy rather than by spelling.
+ */
+async function canonicalNodePath(path, dependencies) {
+    try {
+        return join(await dependencies.realpath(dirname(path)), basename(path));
+    }
+    catch {
+        return null;
+    }
+}
+const MAX_LINK_HOPS = 40;
+/**
+ * The candidates whose symlink chain passes through `targetPath`: removing
+ * `targetPath` would leave each of them dangling. Every hop is followed, so a
+ * link to a link to the target counts, and a link to the target that is
+ * itself a symlink counts too. Regular files and hard links never dangle, so
+ * they are never reported.
+ */
+export async function findLinksThrough(targetPath, candidates, dependencies) {
+    const targetNode = await canonicalNodePath(targetPath, dependencies);
+    if (targetNode === null) {
+        return [];
+    }
+    const linkers = [];
+    for (const candidate of new Set(candidates)) {
+        if (candidate === targetPath ||
+            (await canonicalNodePath(candidate, dependencies)) === targetNode) {
+            continue;
+        }
+        let current = candidate;
+        for (let hop = 0; hop < MAX_LINK_HOPS; hop += 1) {
+            let stats;
+            try {
+                stats = await dependencies.lstat(current);
+            }
+            catch {
+                break;
+            }
+            if (!stats.isSymbolicLink()) {
+                break;
+            }
+            let linkTarget;
+            try {
+                linkTarget = await dependencies.readlink(current);
+            }
+            catch {
+                break;
+            }
+            const next = resolve(dirname(current), linkTarget);
+            if ((await canonicalNodePath(next, dependencies)) === targetNode) {
+                linkers.push(candidate);
+                break;
+            }
+            current = next;
+        }
+    }
+    return linkers.sort((left, right) => left.localeCompare(right));
+}
+/** `a` / `a and b` / `a, b, and c`, repository-relative. */
+function describeLinkers(repoRoot, linkers) {
+    const paths = linkers.map((path) => toPosixPath(relative(repoRoot, path)));
+    if (paths.length <= 2) {
+        return paths.join(' and ');
+    }
+    return `${paths.slice(0, -1).join(', ')}, and ${paths.at(-1)}`;
+}
+/**
+ * Re-verify, immediately before deletion, that a CLAUDE.md planned for removal
+ * is still the exact managed shim the scan recorded: same `lstat` identity
+ * (device and inode, so a replaced file is caught even with identical bytes),
+ * same shape, same symlink target, and still an exact managed shape now.
+ *
+ * Returns null when removal may proceed, or the reason it must not.
+ */
+export async function verifyManagedShimUnchanged(claudePath, agentsPath, planned, dependencies) {
+    const current = await inspectManagedShim(claudePath, agentsPath, dependencies);
+    if (current.kind === 'absent') {
+        return 'CLAUDE.md no longer exists';
+    }
+    if (current.kind !== 'managed') {
+        return current.detail.replace(/; kept$/, '');
+    }
+    if (current.record.dev !== planned.dev ||
+        current.record.ino !== planned.ino) {
+        return 'CLAUDE.md was replaced by a different file';
+    }
+    if (current.record.shape !== planned.shape) {
+        return `CLAUDE.md changed from a ${planned.shape} shim to a ${current.record.shape} shim`;
+    }
+    if (current.record.linkTarget !== planned.linkTarget) {
+        return 'CLAUDE.md symlink target changed';
+    }
+    return null;
+}
+function describeManagedShim(record) {
+    switch (record.shape) {
+        case 'symlink':
+            return 'OAT-managed CLAUDE.md symlink';
+        case 'copy':
+            return 'OAT-managed CLAUDE.md hard copy';
+        default:
+            return 'OAT-managed CLAUDE.md pointer file';
+    }
+}
+/**
+ * Classify one scanned directory under strategy `none`, where no CLAUDE.md is
+ * wanted: an absent CLAUDE.md is correct, an exact managed shim is drift that
+ * sync removes, and anything else is kept and reported, never deleted.
+ */
+async function classifyWithoutShims(directoryPath, directoryEntry, dependencies) {
+    const agentsPath = directoryEntry.agentsPath ?? null;
+    const claudePath = directoryEntry.claudePath ?? join(directoryPath, 'CLAUDE.md');
+    const hasClaude = directoryEntry.claudePath !== undefined ||
+        directoryEntry.brokenClaudePath !== undefined;
+    const entry = (status, detail) => ({ agentsPath, claudePath, status, detail });
+    // `.claude/CLAUDE.md` is Claude Code's alternate project instruction file,
+    // not a shim for an AGENTS.md in `.claude`, so it is never adopted or removed.
+    if (basename(directoryPath) === '.claude' && hasClaude) {
+        return entry('unmanaged', '.claude/CLAUDE.md is not managed by instruction sync; kept');
+    }
+    if (directoryEntry.brokenClaudePath) {
+        const errorCode = directoryEntry.brokenClaudeErrorCode ?? 'unknown error';
+        return entry('unmanaged', errorCode === 'ENOENT'
+            ? 'broken CLAUDE.md symlink; kept'
+            : `unreadable CLAUDE.md symlink target (${errorCode}); kept`);
+    }
+    if (!agentsPath) {
+        try {
+            await dependencies.readFile(claudePath, 'utf8');
+        }
+        catch (error) {
+            return entry('content_mismatch', `unable to read CLAUDE.md (${getErrorCode(error) ?? 'unknown'})`);
+        }
+        return entry('stray', 'CLAUDE.md found without AGENTS.md');
+    }
+    if (!hasClaude) {
+        return entry('ok', 'no CLAUDE.md');
+    }
+    const inspection = await inspectManagedShim(claudePath, agentsPath, dependencies);
+    switch (inspection.kind) {
+        case 'absent':
+            return entry('ok', 'no CLAUDE.md');
+        case 'unreadable':
+            return entry('content_mismatch', inspection.detail);
+        case 'unmanaged':
+            return entry('unmanaged', inspection.detail);
+        case 'managed':
+            return {
+                ...entry('managed_shim', `${describeManagedShim(inspection.record)}; sync removes it under strategy none`),
+                managedShim: inspection.record,
+            };
+    }
+}
+/**
+ * The effective strategy for one run: the `--strategy` flag, then the
+ * repository's `instructions.claude.shims`, then the built-in
+ * default. The flag only ever overrides a single run; it never rewrites config.
+ */
+export function resolveInstructionSyncStrategy(flagStrategy, configuredStrategy) {
+    return (flagStrategy ?? configuredStrategy ?? DEFAULT_INSTRUCTION_SYNC_STRATEGY);
+}
+/**
+ * Read `instructions.claude.shims` from the shared config. A
+ * malformed value fails closed in the config normalizer rather than reading as
+ * unset, so a typo can never silently select the built-in default.
+ */
+export async function readConfiguredInstructionSyncStrategy(repoRoot) {
+    const config = await readOatConfig(repoRoot);
+    return config.instructions?.claude?.shims;
 }
 function getValidInstructionDetail(strategy) {
     switch (strategy) {
+        case 'none':
+            return 'no CLAUDE.md';
         case 'symlink':
             return 'symlink valid';
         case 'copy':
@@ -45,6 +371,8 @@ function getValidInstructionDetail(strategy) {
 }
 function getInvalidInstructionDetail(strategy) {
     switch (strategy) {
+        case 'none':
+            return 'expected no CLAUDE.md';
         case 'symlink':
             return 'expected symlink to AGENTS.md';
         case 'copy':
@@ -193,7 +521,7 @@ async function probeExclusionDirectory(dependencies, repoRoot, relativePath) {
 /**
  * The directories `oat instructions sync` and `oat instructions validate` skip:
  * the derived documentation content root first, then the explicit
- * `documentation.instructionPointerExcludes` opt-outs.
+ * `instructions.claude.excludes` opt-outs.
  *
  * Both commands resolve exclusions through this one function. That is the
  * property that matters: if they computed exclusions separately, validate
@@ -221,6 +549,7 @@ export async function resolveInstructionPointerExcludes(repoRoot, overrides = {}
         realpath,
         readdir,
         readFile,
+        readFileBytes: readFileBytesDefault,
         readlink,
         stat,
         ...overrides,
@@ -242,9 +571,9 @@ export async function resolveInstructionPointerExcludes(repoRoot, overrides = {}
         ...(contentRoot === null
             ? []
             : [{ raw: contentRoot, source: 'documentation.root' }]),
-        ...(config.documentation?.instructionPointerExcludes ?? []).map((raw) => ({
+        ...(config.instructions?.claude?.excludes ?? []).map((raw) => ({
             raw,
-            source: 'documentation.instructionPointerExcludes',
+            source: 'instructions.claude.excludes',
         })),
     ];
     const configured = [];
@@ -285,6 +614,16 @@ export async function resolveInstructionPointerExcludes(repoRoot, overrides = {}
     }
     return { configured, effective, warnings };
 }
+/**
+ * A directory below the repository root that holds its own `.git` (a
+ * directory, or the gitdir file of a submodule or linked worktree such as
+ * `.claude/worktrees/<name>`) is a separate checkout. Its own
+ * `oat instructions` run owns it: the parent never scans, rewrites, removes,
+ * or warns about anything inside it.
+ */
+function isNestedCheckout(repoRoot, directoryPath, entries) {
+    return (directoryPath !== repoRoot && entries.some((entry) => entry.name === '.git'));
+}
 async function scanInstructionDirectories(repoRoot, dependencies, debug, excludedPaths = new Set()) {
     const queue = [repoRoot];
     const directoryEntries = new Map();
@@ -304,6 +643,10 @@ async function scanInstructionDirectories(repoRoot, dependencies, debug, exclude
             debug?.(`Skipping directory scan for ${toPosixPath(currentDirectory)} (${errorCode ?? 'unknown error'})`);
             continue;
         }
+        if (isNestedCheckout(repoRoot, currentDirectory, entries)) {
+            debug?.(`Skipping nested git checkout ${toPosixPath(relative(repoRoot, currentDirectory))}`);
+            continue;
+        }
         for (const entry of entries) {
             const entryPath = join(currentDirectory, entry.name);
             const isRootLevel = currentDirectory === repoRoot;
@@ -388,6 +731,7 @@ export async function scanInstructionFiles(repoRoot, options = {}, overrides = {
         realpath,
         readdir,
         readFile,
+        readFileBytes: readFileBytesDefault,
         readlink,
         stat,
         ...overrides,
@@ -398,6 +742,10 @@ export async function scanInstructionFiles(repoRoot, options = {}, overrides = {
         const agentsPath = directoryEntry.agentsPath ?? null;
         const brokenAgentsPath = directoryEntry.brokenAgentsPath ?? null;
         const brokenAgentsErrorCode = directoryEntry.brokenAgentsErrorCode ?? 'unknown error';
+        if (strategy === 'none' && (agentsPath || !brokenAgentsPath)) {
+            entries.push(await classifyWithoutShims(directoryPath, directoryEntry, dependencies));
+            continue;
+        }
         const brokenClaudePath = directoryEntry.brokenClaudePath ?? null;
         const brokenClaudeErrorCode = directoryEntry.brokenClaudeErrorCode ?? 'unknown error';
         const claudePath = directoryEntry.claudePath ?? join(directoryPath, 'CLAUDE.md');
@@ -586,8 +934,287 @@ export async function scanInstructionFiles(repoRoot, options = {}, overrides = {
             });
         }
     }
+    if (strategy === 'none') {
+        return normalizeEntries(await keepLinkedClaudeFiles(repoRoot, entries, instructionDirectories, dependencies));
+    }
     return normalizeEntries(entries);
 }
+/**
+ * Under `none`, a CLAUDE.md that any scanned instruction file links to --
+ * `pkg/AGENTS.md -> ../CLAUDE.md`, say -- is never removed or adopted, even
+ * when it has an exact managed shape: deleting it would leave that link
+ * dangling. It is reported as `unmanaged`, naming the links.
+ */
+async function keepLinkedClaudeFiles(repoRoot, entries, instructionDirectories, dependencies) {
+    const candidates = [...instructionDirectories.values()].flatMap((directoryEntry) => [
+        directoryEntry.agentsPath,
+        directoryEntry.brokenAgentsPath,
+        directoryEntry.claudePath,
+        directoryEntry.brokenClaudePath,
+    ].filter((path) => path !== undefined));
+    const kept = [];
+    for (const entry of entries) {
+        if (entry.status !== 'managed_shim' && entry.status !== 'stray') {
+            kept.push(entry);
+            continue;
+        }
+        const linkers = await findLinksThrough(entry.claudePath, candidates, dependencies);
+        if (linkers.length === 0) {
+            kept.push(entry);
+            continue;
+        }
+        kept.push({
+            agentsPath: entry.agentsPath,
+            claudePath: entry.claudePath,
+            status: 'unmanaged',
+            detail: `${describeLinkers(repoRoot, linkers)} ${linkers.length === 1 ? 'links' : 'link'} to this CLAUDE.md, so removing it would break ${linkers.length === 1 ? 'that link' : 'those links'} (replace ${linkers.length === 1 ? 'the link' : 'each link'} with its content first); kept`,
+        });
+    }
+    return kept;
+}
+// Exact-case names only. A case-insensitive match would flag ordinary
+// documents such as a provider page named `claude.md` (this repository has
+// two) with advice to delete them, on the unverified premise that Claude
+// Code's plugin would treat them as CLAUDE.md; case variants are therefore
+// neither reported nor ever removed.
+const LEFTOVER_CLAUDE_FILE_NAMES = new Set(['CLAUDE.md', 'CLAUDE.local.md']);
+/**
+ * Every `CLAUDE.md` (including `.claude/CLAUDE.md`) and `CLAUDE.local.md` in
+ * the repository (exact case), sorted, as absolute paths, each with the
+ * `AGENTS.md` files that link to it.
+ *
+ * A separate, read-only walk on purpose. The instruction scan skips the
+ * documentation content root and `instructions.claude.excludes`,
+ * but those only limit what OAT may change: Claude Code's `agents-md` plugin
+ * stands down whichever directory the file is in. Only `.git`, `node_modules`,
+ * the root `.worktrees`, and nested git checkouts (separate repositories) are
+ * skipped, and symlinked directories are not followed. A symlink named like
+ * an instruction file counts, broken or not. Each directory entry is read
+ * once, so one file is never reported twice, even on a case-insensitive
+ * filesystem.
+ */
+export async function findLeftoverClaudeFiles(repoRoot, overrides = {}) {
+    const readDirectory = overrides.readdir ?? readdir;
+    const linkDependencies = {
+        lstat: overrides.lstat ?? lstat,
+        readlink: overrides.readlink ?? readlink,
+        realpath: overrides.realpath ?? realpath,
+    };
+    const inspectionDependencies = {
+        ...linkDependencies,
+        readFileBytes: overrides.readFileBytes ?? readFileBytesDefault,
+    };
+    const queue = [repoRoot];
+    const found = [];
+    const agentsFiles = [];
+    while (queue.length > 0) {
+        const currentDirectory = queue.shift();
+        if (!currentDirectory) {
+            continue;
+        }
+        let entries;
+        try {
+            entries = await readDirectory(currentDirectory, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        if (isNestedCheckout(repoRoot, currentDirectory, entries)) {
+            continue;
+        }
+        for (const entry of entries) {
+            const entryPath = join(currentDirectory, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === '.git' ||
+                    GLOBAL_EXCLUDED_DIRECTORIES.has(entry.name) ||
+                    (currentDirectory === repoRoot && entry.name === '.worktrees')) {
+                    continue;
+                }
+                queue.push(entryPath);
+                continue;
+            }
+            if (entry.name === 'AGENTS.md') {
+                agentsFiles.push(entryPath);
+            }
+            if (LEFTOVER_CLAUDE_FILE_NAMES.has(entry.name)) {
+                found.push(entryPath);
+            }
+        }
+    }
+    const leftovers = [];
+    for (const path of found.sort((left, right) => left.localeCompare(right))) {
+        // `inspectManagedShim` already refuses `CLAUDE.local.md` and anything in
+        // `.claude`, so it alone decides. A file that vanished since the walk
+        // (`absent`) holds nothing and cannot block anything.
+        const inspection = await inspectManagedShim(path, join(dirname(path), 'AGENTS.md'), inspectionDependencies);
+        leftovers.push({
+            path,
+            linkedBy: await findLinksThrough(path, agentsFiles, linkDependencies),
+            exactShim: inspection.kind === 'managed' || inspection.kind === 'absent',
+        });
+    }
+    return leftovers;
+}
+/**
+ * Where the docs explain why any CLAUDE.md makes Claude Code ignore AGENTS.md.
+ * Absolute, because the message is read in terminals and JSON consumers that
+ * cannot resolve a repository-relative docs path.
+ */
+export const CLAUDE_CODE_AGENTS_MD_DOCS_URL = 'https://github.com/voxmedia/open-agent-toolkit/blob/main/apps/oat-docs/docs/provider-sync/instruction-sync.md#claude-code-and-agentsmd';
+/**
+ * Under strategy `none`, removal is all or nothing: the leftover files with
+ * content of their own (anything but an exact OAT shim) that hold back every
+ * CLAUDE.md removal while they exist.
+ *
+ * A stray the scan will adopt (a lone `CLAUDE.md` with no sibling AGENTS.md)
+ * never blocks: its content moves into a new AGENTS.md, so it is not left
+ * behind. Every other file counts wherever it is, including excluded and
+ * documentation trees, because Claude Code's walk does not honor OAT's
+ * exclusions. An unreadable file counts too: blocking is the safe direction.
+ */
+export function findShimRemovalBlockers(entries, leftovers) {
+    const adoptedStrays = new Set(entries
+        .filter((entry) => entry.status === 'stray')
+        .map((entry) => entry.claudePath));
+    return leftovers
+        .filter((leftover) => !leftover.exactShim && !adoptedStrays.has(leftover.path))
+        .map(({ path, linkedBy }) => ({ path, linkedBy }));
+}
+/**
+ * Under a blocked removal, the leftover warnings minus the files the block
+ * holds back: the block finding already names them, and advice to remove
+ * one by hand would recreate the mix the block exists to prevent.
+ */
+export function omitHeldBackLeftovers(leftovers, heldBack) {
+    const kept = new Set(heldBack);
+    return leftovers.filter((leftover) => !kept.has(leftover.path));
+}
+/** The CLAUDE.md files strategy `none` removes: managed shims and adopted strays. */
+export function listShimRemovals(entries) {
+    return entries
+        .filter((entry) => entry.status === 'managed_shim' || entry.status === 'stray')
+        .map((entry) => entry.claudePath)
+        .sort((left, right) => left.localeCompare(right));
+}
+/** `a` / `a and b` / `a, b, and c`. */
+function joinList(items) {
+    if (items.length <= 2) {
+        return items.join(' and ');
+    }
+    return `${items.slice(0, -1).join(', ')}, and ${items.at(-1)}`;
+}
+/** The skip reason sync records for each removal the block holds back. */
+export function describeShimRemovalBlock(repoRoot, blockers) {
+    const paths = blockers.map(({ path }) => toPosixPath(relative(repoRoot, path)));
+    return (`kept: strategy none removes no CLAUDE.md while ${joinList(paths)} ` +
+        `${paths.length === 1 ? 'has' : 'have'} content (see warnings)`);
+}
+/**
+ * The single finding for a blocked removal: which shims the configuration
+ * would remove, that none were removed and which files are why, why any
+ * CLAUDE.md matters, and what to do next.
+ */
+export function buildShimRemovalBlockWarning(repoRoot, blockers, wouldRemove, mode) {
+    const relativeTo = (path) => toPosixPath(relative(repoRoot, path));
+    const paths = blockers.map(({ path }) => relativeTo(path));
+    const removals = wouldRemove.map(relativeTo);
+    const one = paths.length === 1;
+    // A blocker an AGENTS.md links to holds the only copy of those
+    // instructions: removing it would break the links, so its fix is to
+    // replace them with its content first, never plain removal.
+    const unlinked = blockers
+        .filter(({ linkedBy }) => linkedBy.length === 0)
+        .map(({ path }) => relativeTo(path));
+    const fixes = [
+        ...(unlinked.length === 0
+            ? []
+            : [
+                `remove ${joinList(unlinked)} or move ${unlinked.length === 1 ? 'its' : 'their'} content into an AGENTS.md`,
+            ]),
+        ...blockers
+            .filter(({ linkedBy }) => linkedBy.length > 0)
+            .map(({ path, linkedBy }) => {
+            const file = relativeTo(path);
+            return `replace ${describeLinkers(repoRoot, linkedBy)} with the content of ${file}, then remove ${file}`;
+        }),
+    ];
+    return {
+        code: 'claude_md_blocks_shim_removal',
+        paths,
+        wouldRemove: removals,
+        linkedBy: Object.fromEntries(blockers.map(({ path, linkedBy }) => [
+            relativeTo(path),
+            linkedBy.map(relativeTo),
+        ])),
+        message: `Strategy none would remove ${removals.length} CLAUDE.md ` +
+            `${removals.length === 1 ? 'file' : 'files'} (${removals.join(', ')}), ` +
+            `but ${mode === 'apply' ? 'none were removed' : 'none will be removed'} ` +
+            `because ${joinList(paths)} ${one ? 'has' : 'have'} content that is not an OAT shim. ` +
+            'Any CLAUDE.md makes Claude Code ignore AGENTS.md ' +
+            `(${CLAUDE_CODE_AGENTS_MD_DOCS_URL}), so OAT removes none of them until no ` +
+            'CLAUDE.md with content remains rather than leave a mix. ' +
+            `To finish, ${fixes.join('; ')} and rerun \`oat instructions sync\`, or set instructions.claude.shims to a shim strategy ` +
+            '(pointer, symlink, or copy) to keep CLAUDE.md files.',
+    };
+}
+/**
+ * Restate each managed shim's detail while the block holds: sync will not
+ * remove it, so "sync removes it" would be false.
+ */
+export function markBlockedShimEntries(entries) {
+    return entries.map((entry) => entry.status === 'managed_shim' && entry.managedShim
+        ? {
+            ...entry,
+            detail: `${describeManagedShim(entry.managedShim)}; not removed while another CLAUDE.md has content`,
+        }
+        : entry);
+}
+/**
+ * The directory whose sessions a leftover file affects: its own directory,
+ * except that `.claude/CLAUDE.md` belongs to the directory holding `.claude`.
+ * `.` for the project root.
+ */
+function leftoverScopeDirectory(relativePath) {
+    const directory = posix.dirname(relativePath);
+    return posix.basename(directory) === '.claude'
+        ? posix.dirname(directory)
+        : directory;
+}
+/**
+ * One warning per leftover file, naming exactly two ways out: remove the
+ * file, or opt back into shims and let sync add them everywhere.
+ *
+ * When an `AGENTS.md` links to the file, removing it would break that link
+ * and lose the only copy of the instructions, so the first option becomes
+ * "replace the link with the file's content, then remove the file", and
+ * `linkedBy` names the links.
+ *
+ * Claude Code's plugin stands down when such a file sits in the session's
+ * working directory or any directory above it up to the project root, so a
+ * root file affects every session and a nested one only sessions started in
+ * its directory or below.
+ */
+export function buildLeftoverClaudeWarnings(repoRoot, leftovers) {
+    return leftovers.map(({ path, linkedBy }) => {
+        const relativePath = toPosixPath(relative(repoRoot, path));
+        const scopeDirectory = leftoverScopeDirectory(relativePath);
+        const scope = scopeDirectory === '.'
+            ? ', whatever directory a session starts in'
+            : ` for Claude Code sessions started in ${scopeDirectory}/ or below`;
+        const firstOption = linkedBy.length === 0
+            ? `Either remove ${relativePath}`
+            : `Either replace ${describeLinkers(repoRoot, linkedBy)} (${linkedBy.length === 1 ? 'a link' : 'links'} to ${relativePath}) with the content of ${relativePath} and then remove ${relativePath}`;
+        return {
+            code: 'claude_md_hides_agents_md',
+            path: relativePath,
+            linkedBy: linkedBy.map((linker) => toPosixPath(relative(repoRoot, linker))),
+            message: `${relativePath} makes Claude Code ignore every AGENTS.md in this project${scope}: ` +
+                "its default agents-md mode stands down while any CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md exists in the session's working directory or any directory above it, up to the project root. " +
+                `${firstOption}, or set instructions.claude.shims in .oat/config.json ` +
+                'to a shim strategy (pointer, symlink, or copy) and rerun `oat instructions sync` to add shims back.',
+        };
+    });
+}
 export function buildInstructionsSummary(entries, actions) {
     const normalizedEntries = normalizeEntries(entries);
     const normalizedActions = normalizeActions(actions);
@@ -598,22 +1225,29 @@ export function buildInstructionsSummary(entries, actions) {
             .length,
         contentMismatch: normalizedEntries.filter((entry) => entry.status === 'content_mismatch').length,
         stray: normalizedEntries.filter((entry) => entry.status === 'stray').length,
+        managedShim: normalizedEntries.filter((entry) => entry.status === 'managed_shim').length,
+        unmanaged: normalizedEntries.filter((entry) => entry.status === 'unmanaged')
+            .length,
         created: normalizedActions.filter((action) => action.type === 'create')
             .length,
         updated: normalizedActions.filter((action) => action.type === 'update')
             .length,
+        removed: normalizedActions.filter((action) => action.type === 'remove')
+            .length,
         skipped: normalizedActions.filter((action) => action.result === 'skipped')
             .length,
     };
 }
 function deriveInstructionsStatus(entries, actions) {
-    if (entries.some((entry) => entry.status !== 'ok') ||
+    // An `unmanaged` CLAUDE.md is reported but is not drift: sync never removes
+    // it, so counting it would leave the repository no clean state to reach.
+    if (entries.some((entry) => entry.status !== 'ok' && entry.status !== 'unmanaged') ||
         actions.some((action) => action.result === 'skipped')) {
         return 'drift';
     }
     return 'ok';
 }
-export function buildInstructionsPayload({ mode, entries, actions, excludedPaths, effectiveExcludedPaths, exclusionWarnings, }) {
+export function buildInstructionsPayload({ mode, strategy, warnings, entries, actions, excludedPaths, effectiveExcludedPaths, exclusionWarnings, }) {
     const normalizedEntries = normalizeEntries(entries);
     const normalizedActions = normalizeActions(actions);
     const normalizedExcludedPaths = normalizeExcludedPaths(excludedPaths);
@@ -621,8 +1255,10 @@ export function buildInstructionsPayload({ mode, entries, actions, excludedPaths
     return {
         mode,
         status: deriveInstructionsStatus(normalizedEntries, normalizedActions),
+        strategy,
         summary: buildInstructionsSummary(normalizedEntries, normalizedActions),
-        entries: normalizedEntries,
+        // The planning identity is an apply-time safety input, not output.
+        entries: normalizedEntries.map(({ managedShim: _managedShim, ...entry }) => entry),
         actions: normalizedActions,
         // Both omitted when nothing is configured, so a repository with no
         // documentation root keeps its existing payload shape exactly. Once
@@ -641,13 +1277,15 @@ export function buildInstructionsPayload({ mode, entries, actions, excludedPaths
         ...(exclusionWarnings !== undefined && exclusionWarnings.length > 0
             ? { exclusionWarnings }
             : {}),
+        ...(warnings !== undefined && warnings.length > 0 ? { warnings } : {}),
     };
 }
 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}, stray=${payload.summary.stray}, created=${payload.summary.created}, updated=${payload.summary.updated}, skipped=${payload.summary.skipped}`,
+        `strategy: ${payload.strategy}`,
+        `summary: scanned=${payload.summary.scanned}, ok=${payload.summary.ok}, missing=${payload.summary.missing}, content_mismatch=${payload.summary.contentMismatch}, stray=${payload.summary.stray}, managed_shim=${payload.summary.managedShim}, unmanaged=${payload.summary.unmanaged}, created=${payload.summary.created}, updated=${payload.summary.updated}, removed=${payload.summary.removed}, skipped=${payload.summary.skipped}`,
     ];
     if (payload.entries.length === 0) {
         lines.push('entries: none');