@open-agent-toolkit/cli 0.3.8 → 0.3.10

package/dist/commands/init/tools/project-guidance.js

@@ -1,4 +1,5 @@
 import { join } from 'node:path';
+import { buildAgentsMdManagedBlock, formatAgentsMdGuidanceResult, } from '../../shared/agents-md.js';
 import { CliError } from '../../../errors/index.js';
 export function reportableProjectGuidance(plan) {
     return {
@@ -8,6 +9,30 @@ export function reportableProjectGuidance(plan) {
         ...(plan.manualPatch ? { manualPatch: plan.manualPatch } : {}),
     };
 }
+export function isProjectGuidanceIncomplete(plan) {
+    return plan.action === 'blocked' || plan.action === 'manual-required';
+}
+/** Prints one guidance plan in the human form every guidance surface uses. */
+export function reportProjectGuidancePlan(logger, plan) {
+    const message = `Project guidance: ${plan.action} — ${plan.reason}`;
+    if (plan.action === 'skipped') {
+        logger.warn(message);
+        return;
+    }
+    if (!isProjectGuidanceIncomplete(plan)) {
+        logger.info(message);
+        return;
+    }
+    logger.warn(message);
+    if (plan.manualPatch) {
+        for (const line of formatAgentsMdGuidanceResult({
+            action: 'manual-required',
+            manualPatch: plan.manualPatch,
+        })) {
+            logger.info(line);
+        }
+    }
+}
 const PACK_DESCRIPTIONS = {
     core: 'Diagnostics and documentation (oat-doctor, oat-docs)',
     docs: 'Documentation and instruction governance workflows',
@@ -18,20 +43,34 @@ const PACK_DESCRIPTIONS = {
     research: 'Research, analysis, verification, and synthesis',
     brainstorm: 'Always-on brainstorming entry point with visual companion',
 };
-export function buildToolPacksSectionBody(packs) {
+export function buildToolPacksSectionBody(packs, options = {}) {
+    // Directories are named by pack membership, never by directory existence:
+    // `oat init --scope project` creates an empty `.agents/skills/`, and
+    // unrelated repository skills may live there.
+    const projectPacks = packs.filter((pack) => pack.scope === 'project' || pack.scope === 'both');
     const userPacks = packs.filter((pack) => pack.scope === 'user' || pack.scope === 'both');
+    const hasOtherProjectSkills = (options.otherProjectSkills?.length ?? 0) > 0;
     const hasWorkflows = packs.some((pack) => pack.pack === 'workflows');
-    const lines = [
-        '## Tool Packs',
-        '',
-        '- **Skills directory:** `.agents/skills/`',
-        '- **Discover available skills:** scan `.agents/skills/*/SKILL.md`',
-        '- **Refresh provider views:** `oat sync --scope all`',
-        '- **Update skills to latest versions:** `oat tools update`',
-    ];
+    const lines = ['## Tool Packs', ''];
+    if (projectPacks.length > 0) {
+        lines.push(`- **Project skills directory:** \`.agents/skills/\` (${projectPacks.map(({ pack }) => pack).join(', ')} packs installed at project scope)`);
+    }
     if (userPacks.length > 0) {
-        lines.push(`- **User-scoped skills:** \`~/.agents/skills/\` (${userPacks.map(({ pack }) => pack).join(', ')} packs installed at user scope)`);
+        lines.push(`- **User skills directory:** \`~/.agents/skills/\` (${userPacks.map(({ pack }) => pack).join(', ')} packs installed at user scope)`);
+    }
+    if (hasOtherProjectSkills) {
+        lines.push('- **Other project skills:** `.agents/skills/` also holds repository skills that belong to no OAT pack; they are not OAT pack skills.');
     }
+    const scanTargets = [
+        ...(projectPacks.length > 0 || hasOtherProjectSkills
+            ? ['`.agents/skills/*/SKILL.md`']
+            : []),
+        ...(userPacks.length > 0 ? ['`~/.agents/skills/*/SKILL.md`'] : []),
+    ];
+    if (scanTargets.length > 0) {
+        lines.push(`- **Discover available skills:** scan ${scanTargets.join(' and ')}`);
+    }
+    lines.push('- **Refresh provider views:** `oat sync --scope all`', '- **Update skills to latest versions:** `oat tools update`');
     lines.push('', '### Installed Packs', '');
     for (const { pack, scope } of packs) {
         const suffix = scope === 'user'
@@ -46,6 +85,10 @@ export function buildToolPacksSectionBody(packs) {
     }
     return lines.join('\n');
 }
+/** The complete managed `OAT tools` block, markers included. */
+export function renderToolPacksManagedBlock(packs, options = {}) {
+    return buildAgentsMdManagedBlock('tools', buildToolPacksSectionBody(packs, options));
+}
 export function parseProjectGuidanceFlags(args) {
     const accepted = args.includes('--project-guidance');
     const declined = args.includes('--no-project-guidance');
@@ -67,7 +110,7 @@ export function commandProjectGuidanceChoice(command) {
 }
 export function withProjectGuidanceOptions(command) {
     if (!command.options.some(({ long }) => long === '--project-guidance')) {
-        command.option('--project-guidance', 'Create missing or print manual repository AGENTS.md tool guidance');
+        command.option('--project-guidance', 'Create or append repository AGENTS.md tool guidance, or print a manual patch');
     }
     if (!command.options.some(({ long }) => long === '--no-project-guidance')) {
         command.option('--no-project-guidance', 'Decline repository AGENTS.md tool guidance');
@@ -89,12 +132,12 @@ export async function planProjectGuidance(input) {
         };
     }
     else {
-        const accepted = await input.confirmAction('Create missing or propose manual repository AGENTS.md tool guidance?', { interactive: input.interactive });
+        const accepted = await input.confirmAction('Create or append repository AGENTS.md tool guidance (a different existing block prints a manual patch)?', { interactive: input.interactive });
         choice = accepted
             ? { choice: 'accepted', source: 'prompt' }
             : { choice: 'declined', source: 'prompt' };
     }
-    const body = buildToolPacksSectionBody(input.packs);
+    const body = buildToolPacksSectionBody(input.packs, input);
     if (choice.choice === 'declined') {
         return {
             repoRoot: input.repoRoot,
@@ -115,7 +158,7 @@ export async function planProjectGuidance(input) {
             sectionKey: 'tools',
             body,
             legacySectionAction: 'preserve',
-            reason: 'Project guidance was not requested. Re-run with --project-guidance to create an absent AGENTS.md or print a manual patch for an existing one.',
+            reason: 'Project guidance was not requested. Re-run with --project-guidance to create an absent AGENTS.md, append an absent guidance block to an existing one, or print a manual patch for a different existing block.',
             choice,
         };
     }
@@ -138,7 +181,7 @@ export async function planProjectGuidance(input) {
         sectionKey: 'tools',
         body,
         legacySectionAction: 'remove',
-        reason: 'Project guidance was accepted. An absent AGENTS.md may be created; an existing file requires a manual patch.',
+        reason: 'Project guidance was accepted. An absent AGENTS.md may be created and an absent guidance block appended; a different existing block requires a manual patch.',
         choice,
     };
 }

package/dist/commands/init/tools/workflows/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/commands/init/tools/workflows/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EAIzB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,iCAAiC,CAAC;AAQzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,KAAK,EAAY,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAGvE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAGL,mBAAmB,EAIpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC3B,MAAM,qBAAqB,CAAC;AAM7B,UAAU,8BAA8B;IACtC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,gBAAgB,EAAE,CAChB,KAAK,EAAE,qBAAqB,EAC5B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,KACT,MAAM,CAAC;IACZ,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,gBAAgB,EAAE,CAChB,OAAO,EAAE,uBAAuB,KAC7B,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACrC,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzE,SAAS,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC9D,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,qBAAqB,EAAE,CACrB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,uBAAuB,KAC9B,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACnC;AA+SD,wBAAgB,+BAA+B,CAC7C,SAAS,GAAE,OAAO,CAAC,8BAA8B,CAAM,GACtD,OAAO,CAuBT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/commands/init/tools/workflows/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EAIzB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,iCAAiC,CAAC;AAQzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,KAAK,EAAY,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAGvE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAGL,mBAAmB,EAIpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC3B,MAAM,qBAAqB,CAAC;AAM7B,UAAU,8BAA8B;IACtC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,gBAAgB,EAAE,CAChB,KAAK,EAAE,qBAAqB,EAC5B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,KACT,MAAM,CAAC;IACZ,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,gBAAgB,EAAE,CAChB,OAAO,EAAE,uBAAuB,KAC7B,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACrC,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzE,SAAS,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC9D,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,qBAAqB,EAAE,CACrB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,uBAAuB,KAC9B,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACnC;AAoTD,wBAAgB,+BAA+B,CAC7C,SAAS,GAAE,OAAO,CAAC,8BAA8B,CAAM,GACtD,OAAO,CAuBT"}

package/dist/commands/init/tools/workflows/index.js

@@ -70,7 +70,11 @@ async function applyProjectGuidance(plan, dependencies) {
         }
         return {
             ...plan,
-            action: result.action === 'created' ? 'create' : 'no-change',
+            action: result.action === 'created'
+                ? 'create'
+                : result.action === 'appended'
+                    ? 'appended'
+                    : 'no-change',
             reason: `Accepted project guidance ${result.action}. Capability placement and PJM adoption were unchanged.`,
         };
     }

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

@@ -1,16 +1,40 @@
 import type { Dirent, Stats } from 'node:fs';
 import type { CommandContext, GlobalOptions } from '../../app/command-context.js';
-export declare const INSTRUCTION_SYNC_STRATEGIES: readonly ['pointer', 'symlink', 'copy'];
-export type InstructionSyncStrategy = (typeof INSTRUCTION_SYNC_STRATEGIES)[number];
-export type InstructionStatus = 'ok' | 'missing' | 'content_mismatch' | 'stray';
+import type { InstructionSyncStrategy } from '../../config/oat-config.js';
+export { INSTRUCTION_SYNC_STRATEGIES, type InstructionSyncStrategy, } from '../../config/oat-config.js';
+/**
+ * - `managed_shim`: under strategy `none`, a CLAUDE.md in the exact shape OAT
+ *   writes (the `@AGENTS.md` pointer, a symlink to the sibling AGENTS.md, or a
+ *   byte-identical copy). Drift: sync removes it.
+ * - `unmanaged`: under strategy `none`, a CLAUDE.md that is not an exact
+ *   managed shape (hand-written, modified, a symlink elsewhere). Never
+ *   removed, and not drift.
+ */
+export type InstructionStatus = 'ok' | 'missing' | 'content_mismatch' | 'stray' | 'managed_shim' | 'unmanaged';
+export type ManagedShimShape = 'pointer' | 'symlink' | 'copy';
+/**
+ * What the scan observed about a managed shim, so removal can fail closed if
+ * the file changed between planning and deletion. Internal to the sync apply
+ * path; never serialized into the JSON payload.
+ */
+export interface ManagedShimRecord {
+    shape: ManagedShimShape;
+    /** `lstat` identity of the CLAUDE.md itself (the link for a symlink). */
+    dev: number;
+    ino: number;
+    /** The raw `readlink` value, for the symlink shape only. */
+    linkTarget?: string;
+}
 export type InstructionsStatus = 'ok' | 'drift';
 export interface InstructionEntry {
     agentsPath: string | null;
     claudePath: string;
     status: InstructionStatus;
     detail: string;
+    /** Present only for `managed_shim` entries. */
+    managedShim?: ManagedShimRecord;
 }
-export type InstructionActionType = 'create' | 'update' | 'skip';
+export type InstructionActionType = 'create' | 'update' | 'remove' | 'skip';
 export type InstructionActionResult = 'planned' | 'applied' | 'skipped';
 export interface InstructionActionRecord {
     type: InstructionActionType;
@@ -19,19 +43,69 @@ export interface InstructionActionRecord {
     result: InstructionActionResult;
 }
 export type InstructionsMode = 'validate' | 'dry-run' | 'apply';
+/**
+ * A finding that never changes the exit code by itself.
+ *
+ * `claude_md_hides_agents_md`: under strategy `none`, a `CLAUDE.md`,
+ * `.claude/CLAUDE.md`, or `CLAUDE.local.md` that makes Claude Code's default
+ * `agents-md` mode ignore every AGENTS.md in the project while it exists.
+ */
+export interface ClaudeMdHidesAgentsMdWarning {
+    code: 'claude_md_hides_agents_md';
+    /** Repository-relative POSIX path. */
+    path: string;
+    /**
+     * Repository-relative `AGENTS.md` paths whose symlink chain reaches `path`.
+     * When non-empty, removing `path` would break them: replace each link with
+     * the file's content first. Always present, possibly empty.
+     */
+    linkedBy: string[];
+    message: string;
+}
+/**
+ * `claude_md_blocks_shim_removal`: under strategy `none`, removal is all or
+ * nothing. While any `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md`
+ * is not an exact OAT shim, sync removes no CLAUDE.md at all; this finding
+ * names those files and the removals held back. Sync reports each held-back
+ * removal as a skipped action, which is what sets its exit code.
+ */
+export interface ClaudeMdBlocksShimRemovalWarning {
+    code: 'claude_md_blocks_shim_removal';
+    /** Repository-relative POSIX paths of the files with their own content. */
+    paths: string[];
+    /** Repository-relative POSIX paths of the CLAUDE.md files kept because of them. */
+    wouldRemove: string[];
+    /**
+     * For each path in `paths`, the repository-relative `AGENTS.md` paths whose
+     * symlink chain reaches it. A non-empty list means that file holds the only
+     * copy of those instructions: replace each link with its content before
+     * removing it, never remove it plainly. Every path in `paths` has a key.
+     */
+    linkedBy: Record<string, string[]>;
+    message: string;
+}
+export type InstructionsWarning = ClaudeMdHidesAgentsMdWarning | ClaudeMdBlocksShimRemovalWarning;
 export interface InstructionsSummary {
     scanned: number;
     ok: number;
     missing: number;
     contentMismatch: number;
     stray: number;
+    managedShim: number;
+    unmanaged: number;
     created: number;
     updated: number;
+    removed: number;
     skipped: number;
 }
 export interface InstructionsJsonPayload {
     mode: InstructionsMode;
     status: InstructionsStatus;
+    /**
+     * The strategy this run applied or checked: `--strategy` when given, else
+     * `instructions.claude.shims`, else the built-in default.
+     */
+    strategy: InstructionSyncStrategy;
     summary: InstructionsSummary;
     entries: InstructionEntry[];
     actions: InstructionActionRecord[];
@@ -71,6 +145,11 @@ export interface InstructionsJsonPayload {
      * exclusion that silently does nothing. Omitted when empty.
      */
     exclusionWarnings?: string[];
+    /**
+     * Structured warnings, the same text written to stderr in human mode.
+     * Omitted when empty, so a clean repository's payload shape is unchanged.
+     */
+    warnings?: InstructionsWarning[];
 }
 /**
  * The resolved exclusion set, split so that intent and effect cannot be
@@ -104,12 +183,30 @@ export interface InstructionsScanDependencies {
     lstat: (path: string) => Promise<Stats>;
     realpath: (path: string) => Promise<string>;
     readFile: (path: string, encoding: 'utf8') => Promise<string>;
+    /** Raw bytes, for the byte-exact managed-shim comparisons. */
+    readFileBytes: (path: string) => Promise<Buffer>;
     readlink: (path: string) => Promise<string>;
     stat: (path: string) => Promise<Stats>;
 }
 export interface InstructionsValidateCommandDependencies {
     buildCommandContext: (options: GlobalOptions) => CommandContext;
     resolveProjectRoot: (cwd: string) => Promise<string>;
+    /**
+     * The repository's configured `instructions.claude.shims`, or
+     * undefined when the key is absent. Sync inherits it from this interface so
+     * both commands resolve the strategy through the same config read.
+     */
+    readConfiguredInstructionSyncStrategy: (repoRoot: string) => Promise<InstructionSyncStrategy | undefined>;
+    /**
+     * Every `CLAUDE.md` and `CLAUDE.local.md` in the repository (absolute
+     * paths), from a read-only walk that ignores the mutation exclusions, each
+     * classified as an exact OAT shim or not.
+     */
+    findLeftoverClaudeFiles: (repoRoot: string) => Promise<Array<{
+        path: string;
+        linkedBy: string[];
+        exactShim: boolean;
+    }>>;
     /**
      * The single exclusion path both commands resolve through. Sync inherits it
      * from this interface rather than resolving its own, so validate can never
@@ -121,6 +218,10 @@ export interface InstructionsValidateCommandDependencies {
 export interface InstructionsSyncCommandDependencies extends InstructionsValidateCommandDependencies {
     lstat: (path: string) => Promise<Stats>;
     readFile: (path: string, encoding: 'utf8') => Promise<string>;
+    /** Raw bytes, for the apply-time managed-shim re-verification. */
+    readFileBytes: (path: string) => Promise<Buffer>;
+    readlink: (path: string) => Promise<string>;
+    realpath: (path: string) => Promise<string>;
     removeFile: (path: string) => Promise<void>;
     symlinkFile: (target: string, path: string) => Promise<void>;
     writeFile: (path: string, content: string, encoding: 'utf8') => Promise<void>;

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

@@ -1 +1 @@
-{"version":3,"file":"instructions.types.d.ts","sourceRoot":"","sources":["../../../src/commands/instructions/instructions.types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"instructions.types.d.ts","sourceRoot":"","sources":["../../../src/commands/instructions/instructions.types.ts"],"names":[],"mappings":"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"}

package/dist/commands/instructions/instructions.types.js

@@ -1,5 +1,4 @@
-export const INSTRUCTION_SYNC_STRATEGIES = [
-    'pointer',
-    'symlink',
-    'copy',
-];
+// One list shared with the `instructions.claude.shims` config
+// normalizer and `oat config set`, so the commands can never accept a value
+// the config rejects or the reverse.
+export { INSTRUCTION_SYNC_STRATEGIES, } from '../../config/oat-config.js';

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

@@ -1,15 +1,83 @@
-import type { InstructionSyncStrategy, InstructionActionRecord, InstructionEntry, InstructionsJsonPayload, InstructionsMode, InstructionPointerExclusions, InstructionsScanOptions, InstructionsScanDependencies, InstructionsSummary } from './instructions.types.js';
+import { DEFAULT_INSTRUCTION_SYNC_STRATEGY } from '../../config/oat-config.js';
+import type { ClaudeMdBlocksShimRemovalWarning, ClaudeMdHidesAgentsMdWarning, InstructionSyncStrategy, InstructionActionRecord, InstructionEntry, InstructionsJsonPayload, InstructionsMode, InstructionPointerExclusions, InstructionsScanOptions, InstructionsScanDependencies, InstructionsSummary, InstructionsWarning, ManagedShimRecord } from './instructions.types.js';
 export declare const EXPECTED_CLAUDE_CONTENT = "@AGENTS.md\n";
-export declare const DEFAULT_INSTRUCTION_SYNC_STRATEGY: InstructionSyncStrategy;
+export { DEFAULT_INSTRUCTION_SYNC_STRATEGY };
 interface BuildInstructionsPayloadArgs {
     mode: InstructionsMode;
+    strategy: InstructionSyncStrategy;
+    warnings?: InstructionsWarning[];
     entries: InstructionEntry[];
     actions: InstructionActionRecord[];
     excludedPaths?: string[];
     effectiveExcludedPaths?: string[];
     exclusionWarnings?: string[];
 }
-export declare function resolveInstructionSyncStrategy(strategy?: InstructionSyncStrategy): InstructionSyncStrategy;
+/** The filesystem reads managed-shim classification needs. */
+export interface ManagedShimInspectionDependencies {
+    lstat: InstructionsScanDependencies['lstat'];
+    readlink: InstructionsScanDependencies['readlink'];
+    readFileBytes: InstructionsScanDependencies['readFileBytes'];
+    realpath: InstructionsScanDependencies['realpath'];
+}
+export type ManagedShimInspection = {
+    kind: 'managed';
+    record: ManagedShimRecord;
+} | {
+    kind: 'absent';
+} | {
+    kind: 'unmanaged';
+    detail: string;
+} | {
+    kind: 'unreadable';
+    detail: string;
+};
+/**
+ * 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 declare function inspectManagedShim(claudePath: string, agentsPath: string, dependencies: ManagedShimInspectionDependencies): Promise<ManagedShimInspection>;
+/** The filesystem reads link-chain resolution needs. */
+export interface LinkResolutionDependencies {
+    lstat: InstructionsScanDependencies['lstat'];
+    readlink: InstructionsScanDependencies['readlink'];
+    realpath: InstructionsScanDependencies['realpath'];
+}
+/**
+ * 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 declare function findLinksThrough(targetPath: string, candidates: readonly string[], dependencies: LinkResolutionDependencies): Promise<string[]>;
+/**
+ * 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 declare function verifyManagedShimUnchanged(claudePath: string, agentsPath: string, planned: ManagedShimRecord, dependencies: ManagedShimInspectionDependencies): Promise<string | null>;
+/**
+ * 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 declare function resolveInstructionSyncStrategy(flagStrategy?: InstructionSyncStrategy, configuredStrategy?: InstructionSyncStrategy): InstructionSyncStrategy;
+/**
+ * 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 declare function readConfiguredInstructionSyncStrategy(repoRoot: string): Promise<InstructionSyncStrategy | undefined>;
 /**
  * Canonicalize repo-relative exclusion entries into the exact form the scan
  * compares against: POSIX separators, collapsed `.` and `..` segments and
@@ -33,7 +101,7 @@ export declare function normalizeExcludedPaths(excludedPaths?: readonly string[]
 /**
  * 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
@@ -57,8 +125,95 @@ export declare function normalizeExcludedPaths(excludedPaths?: readonly string[]
  */
 export declare function resolveInstructionPointerExcludes(repoRoot: string, overrides?: Partial<InstructionsScanDependencies>): Promise<InstructionPointerExclusions>;
 export declare function scanInstructionFiles(repoRoot: string, options?: InstructionsScanOptions, overrides?: Partial<InstructionsScanDependencies>): Promise<InstructionEntry[]>;
+/** A leftover file and the `AGENTS.md` links that pass through it. */
+export interface LeftoverClaudeFile {
+    path: string;
+    /** Absolute paths of every `AGENTS.md` whose symlink chain reaches `path`. */
+    linkedBy: string[];
+    /**
+     * Whether the file is an exact OAT shim of its sibling AGENTS.md (pointer,
+     * sibling symlink, or identical copy), judged by `inspectManagedShim`. Any
+     * other file -- `CLAUDE.local.md`, `.claude/CLAUDE.md`, a hand-written or
+     * modified `CLAUDE.md`, one without a sibling AGENTS.md, or one that cannot
+     * be read -- has content of its own.
+     */
+    exactShim: boolean;
+}
+/**
+ * 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 declare function findLeftoverClaudeFiles(repoRoot: string, overrides?: Partial<Pick<InstructionsScanDependencies, 'readdir' | 'lstat' | 'readlink' | 'realpath' | 'readFileBytes'>>): Promise<LeftoverClaudeFile[]>;
+/**
+ * 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 declare 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 declare function findShimRemovalBlockers(entries: readonly InstructionEntry[], leftovers: readonly LeftoverClaudeFile[]): ShimRemovalBlocker[];
+/** A file that blocks removal, and the `AGENTS.md` links that reach it. */
+export type ShimRemovalBlocker = Pick<LeftoverClaudeFile, '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 declare function omitHeldBackLeftovers<T extends {
+    path: string;
+}>(leftovers: readonly T[], heldBack: readonly string[]): T[];
+/** The CLAUDE.md files strategy `none` removes: managed shims and adopted strays. */
+export declare function listShimRemovals(entries: readonly InstructionEntry[]): string[];
+/** The skip reason sync records for each removal the block holds back. */
+export declare function describeShimRemovalBlock(repoRoot: string, blockers: readonly ShimRemovalBlocker[]): string;
+/**
+ * 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 declare function buildShimRemovalBlockWarning(repoRoot: string, blockers: readonly ShimRemovalBlocker[], wouldRemove: readonly string[], mode: InstructionsMode): ClaudeMdBlocksShimRemovalWarning;
+/**
+ * Restate each managed shim's detail while the block holds: sync will not
+ * remove it, so "sync removes it" would be false.
+ */
+export declare function markBlockedShimEntries(entries: readonly InstructionEntry[]): InstructionEntry[];
+/**
+ * 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 declare function buildLeftoverClaudeWarnings(repoRoot: string, leftovers: readonly Pick<LeftoverClaudeFile, 'path' | 'linkedBy'>[]): ClaudeMdHidesAgentsMdWarning[];
 export declare function buildInstructionsSummary(entries: InstructionEntry[], actions: InstructionActionRecord[]): InstructionsSummary;
-export declare function buildInstructionsPayload({ mode, entries, actions, excludedPaths, effectiveExcludedPaths, exclusionWarnings, }: BuildInstructionsPayloadArgs): InstructionsJsonPayload;
+export declare function buildInstructionsPayload({ mode, strategy, warnings, entries, actions, excludedPaths, effectiveExcludedPaths, exclusionWarnings, }: BuildInstructionsPayloadArgs): InstructionsJsonPayload;
 export declare function formatInstructionsReport(payload: InstructionsJsonPayload, repoRoot?: string): string;
-export {};
 //# sourceMappingURL=instructions.utils.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"instructions.utils.d.ts","sourceRoot":"","sources":["../../../src/commands/instructions/instructions.utils.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EACV,uBAAuB,EACvB,uBAAuB,EACvB,gBAAgB,EAChB,uBAAuB,EACvB,gBAAgB,EAChB,4BAA4B,EAC5B,uBAAuB,EACvB,4BAA4B,EAE5B,mBAAmB,EACpB,MAAM,sBAAsB,CAAC;AAE9B,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AACtD,eAAO,MAAM,iCAAiC,EAAE,uBACrC,CAAC;AAcZ,UAAU,4BAA4B;IACpC,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,OAAO,EAAE,uBAAuB,EAAE,CAAC;IACnC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;IAClC,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B;AAiCD,wBAAgB,8BAA8B,CAC5C,QAAQ,CAAC,EAAE,uBAAuB,GACjC,uBAAuB,CAEzB;AA2ED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CACpC,aAAa,GAAE,SAAS,MAAM,EAAO,GACpC,MAAM,EAAE,CAyBV;AA0FD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,iCAAiC,CACrD,QAAQ,EAAE,MAAM,EAChB,SAAS,GAAE,OAAO,CAAC,4BAA4B,CAAM,GACpD,OAAO,CAAC,4BAA4B,CAAC,CAgGvC;AAgID,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,uBAA4B,EACrC,SAAS,GAAE,OAAO,CAAC,4BAA4B,CAAM,GACpD,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAkO7B;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,gBAAgB,EAAE,EAC3B,OAAO,EAAE,uBAAuB,EAAE,GACjC,mBAAmB,CAoBrB;AAgBD,wBAAgB,wBAAwB,CAAC,EACvC,IAAI,EACJ,OAAO,EACP,OAAO,EACP,aAAa,EACb,sBAAsB,EACtB,iBAAiB,GAClB,EAAE,4BAA4B,GAAG,uBAAuB,CAgCxD;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,uBAAuB,EAChC,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CAmCR"}
+{"version":3,"file":"instructions.utils.d.ts","sourceRoot":"","sources":["../../../src/commands/instructions/instructions.utils.ts"],"names":[],"mappings":"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"}