@open-agent-toolkit/cli 0.2.62 → 0.2.64

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

@@ -35,10 +35,67 @@ export interface InstructionsJsonPayload {
     summary: InstructionsSummary;
     entries: InstructionEntry[];
     actions: InstructionActionRecord[];
+    /**
+     * The normalized repo-relative exclusions this scan was *configured* with, in
+     * resolution order. An entry here is a statement of intent, not a guarantee:
+     * it may name a directory that does not exist, differ in case from the real
+     * path on a case-insensitive filesystem, or be shadowed by the `.oat/repo`
+     * carve-in.
+     *
+     * Read `effectiveExcludedPaths` to learn what was actually protected.
+     *
+     * Additive and omitted entirely when nothing was configured, so payloads from
+     * repositories without a documentation root are byte-identical to the
+     * pre-exclusion shape.
+     */
+    excludedPaths?: string[];
+    /**
+     * The subset of `excludedPaths` that names a real, case-exact directory the
+     * scan can actually prune. This is the field a consumer should trust when
+     * deciding whether a tree is protected; every configured entry missing from
+     * it was also reported as a warning on stderr.
+     *
+     * Present whenever `excludedPaths` is, including as an empty array when every
+     * configured entry turned out to be inert; omitted only when nothing was
+     * configured at all.
+     */
+    effectiveExcludedPaths?: string[];
+    /**
+     * One message per configured exclusion that will not protect anything, the
+     * same text written to stderr in human mode.
+     *
+     * This field is why the JSON surface is complete. `logger.warn` is suppressed
+     * under `--json`, and an entry rejected during normalization (an absolute
+     * path, or one escaping the repository) never reaches `excludedPaths` either
+     * — so without this a `--json` consumer would see no trace at all of an
+     * exclusion that silently does nothing. Omitted when empty.
+     */
+    exclusionWarnings?: string[];
+}
+/**
+ * The resolved exclusion set, split so that intent and effect cannot be
+ * confused. A configured entry that protects nothing is the failure mode this
+ * split exists to surface: silently reporting it as applied would let an
+ * operator believe a documentation tree is safe while pointers are written
+ * into it.
+ */
+export interface InstructionPointerExclusions {
+    /** Normalized entries exactly as configured, in resolution order. */
+    configured: string[];
+    /** The subset that names a real, case-exact, prunable directory. */
+    effective: string[];
+    /** One human-readable warning per configured entry that will do nothing. */
+    warnings: string[];
 }
 export interface InstructionsScanOptions {
     strategy?: InstructionSyncStrategy;
     debug?: (message: string) => void;
+    /**
+     * Repo-root-relative directories whose subtrees are left out of the scan.
+     * Applied after the excluded-root carve-in, so excluding a directory can
+     * never strand a subtree the carve-in re-entered (`.oat/repo/**`).
+     */
+    excludedPaths?: string[];
 }
 export interface InstructionsScanDependencies {
     readdir: (path: string, options: {
@@ -53,6 +110,12 @@ export interface InstructionsScanDependencies {
 export interface InstructionsValidateCommandDependencies {
     buildCommandContext: (options: GlobalOptions) => CommandContext;
     resolveProjectRoot: (cwd: string) => Promise<string>;
+    /**
+     * The single exclusion path both commands resolve through. Sync inherits it
+     * from this interface rather than resolving its own, so validate can never
+     * report drift that sync would refuse to fix.
+     */
+    resolveInstructionPointerExcludes: (repoRoot: string) => Promise<InstructionPointerExclusions>;
     scanInstructionFiles: (repoRoot: string, options?: InstructionsScanOptions, overrides?: Partial<InstructionsScanDependencies>) => Promise<InstructionEntry[]>;
 }
 export interface InstructionsSyncCommandDependencies extends InstructionsValidateCommandDependencies {

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.utils.d.ts

@@ -1,15 +1,64 @@
-import type { InstructionSyncStrategy, InstructionActionRecord, InstructionEntry, InstructionsJsonPayload, InstructionsMode, InstructionsScanOptions, InstructionsScanDependencies, InstructionsSummary } from './instructions.types.js';
+import type { InstructionSyncStrategy, InstructionActionRecord, InstructionEntry, InstructionsJsonPayload, InstructionsMode, InstructionPointerExclusions, InstructionsScanOptions, InstructionsScanDependencies, InstructionsSummary } from './instructions.types.js';
 export declare const EXPECTED_CLAUDE_CONTENT = "@AGENTS.md\n";
 export declare const DEFAULT_INSTRUCTION_SYNC_STRATEGY: InstructionSyncStrategy;
 interface BuildInstructionsPayloadArgs {
     mode: InstructionsMode;
     entries: InstructionEntry[];
     actions: InstructionActionRecord[];
+    excludedPaths?: string[];
+    effectiveExcludedPaths?: string[];
+    exclusionWarnings?: string[];
 }
 export declare function resolveInstructionSyncStrategy(strategy?: InstructionSyncStrategy): InstructionSyncStrategy;
+/**
+ * Canonicalize repo-relative exclusion entries into the exact form the scan
+ * compares against: POSIX separators, collapsed `.` and `..` segments and
+ * duplicate slashes, no trailing slash, de-duplicated, order-preserving.
+ *
+ * Full normalization is what makes the comparison trustworthy. The scan tests
+ * an exclusion against `relative(repoRoot, entryPath)`, which is always
+ * already-normalized, so an un-normalized entry like `apps/./docs` or
+ * `apps//docs` would silently never match and quietly fail open.
+ *
+ * Two classes of entry are dropped rather than normalized:
+ *
+ * - anything resolving to the repository root (`.`, `` , `./`), because
+ *   excluding the root would silence the entire scan — including the
+ *   `.oat/repo` carve-in — from one stray config value; and
+ * - absolute paths and entries escaping the repository (`..`, `../x`), which
+ *   can never name a directory inside the tree being scanned. Dropping them
+ *   keeps a malformed value from masquerading as a matchable exclusion.
+ */
+export declare function normalizeExcludedPaths(excludedPaths?: readonly string[]): string[];
+/**
+ * The directories `oat instructions sync` and `oat instructions validate` skip:
+ * the derived documentation content root first, then the explicit
+ * `documentation.instructionPointerExcludes` opt-outs.
+ *
+ * Both commands resolve exclusions through this one function. That is the
+ * property that matters: if they computed exclusions separately, validate
+ * could report drift in a directory sync refuses to touch, and the repository
+ * would have no clean state to reach.
+ *
+ * Every configured entry is classified rather than trusted. An entry that is
+ * dropped during normalization, names an unexcludable carve-in root, or does
+ * not resolve to a real case-exact directory is reported as a warning and kept
+ * out of `effective`, so no caller can mistake a typo for protection.
+ *
+ * `effective` answers "is this tree protected from pointer writes?", not "did
+ * the exclusion predicate fire for it". An entry that names an already-skipped
+ * built-in root (`.git`, `node_modules`) or sits beneath another exclusion is
+ * still effective, because the operator's intent holds; warning about those
+ * would be a false alarm about exclusions that do work.
+ *
+ * Nothing here deletes or rewrites an existing pointer. Excluding a directory
+ * only stops it being reported and written; a `CLAUDE.md` already inside an
+ * excluded tree is left exactly as it is.
+ */
+export declare function resolveInstructionPointerExcludes(repoRoot: string, overrides?: Partial<InstructionsScanDependencies>): Promise<InstructionPointerExclusions>;
 export declare function scanInstructionFiles(repoRoot: string, options?: InstructionsScanOptions, overrides?: Partial<InstructionsScanDependencies>): Promise<InstructionEntry[]>;
 export declare function buildInstructionsSummary(entries: InstructionEntry[], actions: InstructionActionRecord[]): InstructionsSummary;
-export declare function buildInstructionsPayload({ mode, entries, actions, }: BuildInstructionsPayloadArgs): InstructionsJsonPayload;
+export declare function buildInstructionsPayload({ mode, 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":"AAUA,OAAO,KAAK,EACV,uBAAuB,EACvB,uBAAuB,EACvB,gBAAgB,EAChB,uBAAuB,EACvB,gBAAgB,EAChB,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;CACpC;AAiCD,wBAAgB,8BAA8B,CAC5C,QAAQ,CAAC,EAAE,uBAAuB,GACjC,uBAAuB,CAEzB;AA2LD,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,uBAA4B,EACrC,SAAS,GAAE,OAAO,CAAC,4BAA4B,CAAM,GACpD,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAiO7B;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,GACR,EAAE,4BAA4B,GAAG,uBAAuB,CAWxD;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":"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;AAsDD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,iCAAiC,CACrD,QAAQ,EAAE,MAAM,EAChB,SAAS,GAAE,OAAO,CAAC,4BAA4B,CAAM,GACpD,OAAO,CAAC,4BAA4B,CAAC,CAuEvC;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"}

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

@@ -1,5 +1,6 @@
 import { lstat, readdir, readFile, readlink, realpath, stat, } from 'node:fs/promises';
-import { dirname, join, relative, resolve } from 'node:path';
+import { dirname, join, posix, relative, resolve } from 'node:path';
+import { readOatConfig, resolveDocumentationContentRoot, } from '../../config/oat-config.js';
 export const EXPECTED_CLAUDE_CONTENT = '@AGENTS.md\n';
 export const DEFAULT_INSTRUCTION_SYNC_STRATEGY = 'pointer';
 const ROOT_EXCLUDED_DIRECTORIES = new Set(['.git', '.oat', '.worktrees']);
@@ -87,7 +88,171 @@ function recordInstructionFile(directoryEntries, directoryPath, entryName, entry
     }
     directoryEntries.set(directoryPath, current);
 }
-async function scanInstructionDirectories(repoRoot, dependencies, debug) {
+/**
+ * Canonicalize repo-relative exclusion entries into the exact form the scan
+ * compares against: POSIX separators, collapsed `.` and `..` segments and
+ * duplicate slashes, no trailing slash, de-duplicated, order-preserving.
+ *
+ * Full normalization is what makes the comparison trustworthy. The scan tests
+ * an exclusion against `relative(repoRoot, entryPath)`, which is always
+ * already-normalized, so an un-normalized entry like `apps/./docs` or
+ * `apps//docs` would silently never match and quietly fail open.
+ *
+ * Two classes of entry are dropped rather than normalized:
+ *
+ * - anything resolving to the repository root (`.`, `` , `./`), because
+ *   excluding the root would silence the entire scan — including the
+ *   `.oat/repo` carve-in — from one stray config value; and
+ * - absolute paths and entries escaping the repository (`..`, `../x`), which
+ *   can never name a directory inside the tree being scanned. Dropping them
+ *   keeps a malformed value from masquerading as a matchable exclusion.
+ */
+export function normalizeExcludedPaths(excludedPaths = []) {
+    const normalized = [];
+    for (const candidate of excludedPaths) {
+        const trimmed = toPosixPath(candidate.trim());
+        if (!trimmed || posix.isAbsolute(trimmed)) {
+            continue;
+        }
+        const posixPath = posix.normalize(trimmed).replace(/\/+$/, '');
+        if (!posixPath ||
+            posixPath === '.' ||
+            posixPath === '..' ||
+            posixPath.startsWith('../')) {
+            continue;
+        }
+        if (!normalized.includes(posixPath)) {
+            normalized.push(posixPath);
+        }
+    }
+    return normalized;
+}
+/**
+ * Paths the carve-in queues directly, which therefore never reach the exclusion
+ * predicate and can never be excluded however the config asks. An opt-out
+ * naming one of these is inert and must be reported as such rather than
+ * silently listed as protection.
+ *
+ * Matched exactly, never by prefix: only the carve-in root itself bypasses the
+ * predicate. Its *descendants* are reached by ordinary traversal out of the
+ * queued directory, so `.oat/repo/pjm` is excludable even though `.oat/repo`
+ * is not, and treating it as inert would be a false warning about an exclusion
+ * that really does protect its tree.
+ */
+const UNEXCLUDABLE_PATHS = new Set([...ROOT_EXCLUDED_DIRECTORY_CARVE_INS].map(([directory, carveIn]) => `${directory}/${carveIn}`));
+/**
+ * Whether `relativePath` names a real directory whose on-disk spelling matches
+ * exactly.
+ *
+ * The case check is the point. On a case-insensitive filesystem (APFS, NTFS) a
+ * plain existence test accepts `Apps/Docsapp/docs` for a directory really named
+ * `apps/docsapp/docs`, but the scan compares against `relative(repoRoot, ...)`,
+ * which always yields the true on-disk case. The exclusion would then be
+ * reported as applied while matching nothing — issue #238 recurring silently on
+ * the default developer platform. Resolving through `realpath` and comparing
+ * the result to the requested spelling catches that, and returns false for a
+ * path that does not exist at all.
+ *
+ * `repoRoot` is realpath'd too, so a symlinked checkout (`/tmp` on macOS) does
+ * not make every entry look like a mismatch.
+ */
+async function isCaseExactDirectory(dependencies, repoRoot, relativePath) {
+    try {
+        const realRoot = await dependencies.realpath(repoRoot);
+        const candidate = join(realRoot, relativePath);
+        if (!(await directoryExists(dependencies, candidate))) {
+            return false;
+        }
+        const realCandidate = await dependencies.realpath(candidate);
+        return toPosixPath(relative(realRoot, realCandidate)) === relativePath;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The directories `oat instructions sync` and `oat instructions validate` skip:
+ * the derived documentation content root first, then the explicit
+ * `documentation.instructionPointerExcludes` opt-outs.
+ *
+ * Both commands resolve exclusions through this one function. That is the
+ * property that matters: if they computed exclusions separately, validate
+ * could report drift in a directory sync refuses to touch, and the repository
+ * would have no clean state to reach.
+ *
+ * Every configured entry is classified rather than trusted. An entry that is
+ * dropped during normalization, names an unexcludable carve-in root, or does
+ * not resolve to a real case-exact directory is reported as a warning and kept
+ * out of `effective`, so no caller can mistake a typo for protection.
+ *
+ * `effective` answers "is this tree protected from pointer writes?", not "did
+ * the exclusion predicate fire for it". An entry that names an already-skipped
+ * built-in root (`.git`, `node_modules`) or sits beneath another exclusion is
+ * still effective, because the operator's intent holds; warning about those
+ * would be a false alarm about exclusions that do work.
+ *
+ * Nothing here deletes or rewrites an existing pointer. Excluding a directory
+ * only stops it being reported and written; a `CLAUDE.md` already inside an
+ * excluded tree is left exactly as it is.
+ */
+export async function resolveInstructionPointerExcludes(repoRoot, overrides = {}) {
+    const dependencies = {
+        lstat,
+        realpath,
+        readdir,
+        readFile,
+        readlink,
+        stat,
+        ...overrides,
+    };
+    const config = await readOatConfig(repoRoot);
+    const contentRoot = await resolveDocumentationContentRoot(repoRoot, config, {
+        // Probe through the injected `stat` so a simulated filesystem (tests) and
+        // the real one agree on whether `<root>/docs` exists.
+        dirExists: async (path) => {
+            try {
+                return (await dependencies.stat(path)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        },
+    });
+    const requested = [
+        ...(contentRoot === null
+            ? []
+            : [{ raw: contentRoot, source: 'documentation.root' }]),
+        ...(config.documentation?.instructionPointerExcludes ?? []).map((raw) => ({
+            raw,
+            source: 'documentation.instructionPointerExcludes',
+        })),
+    ];
+    const configured = [];
+    const effective = [];
+    const warnings = [];
+    for (const { raw, source } of requested) {
+        const [normalizedPath] = normalizeExcludedPaths([raw]);
+        if (!normalizedPath) {
+            warnings.push(`Ignoring ${source} entry ${JSON.stringify(raw)}: exclusions must be repository-relative paths inside the repository.`);
+            continue;
+        }
+        if (configured.includes(normalizedPath)) {
+            continue;
+        }
+        configured.push(normalizedPath);
+        if (UNEXCLUDABLE_PATHS.has(normalizedPath)) {
+            warnings.push(`${source} entry ${JSON.stringify(normalizedPath)} has no effect: ${normalizedPath} is always scanned.`);
+            continue;
+        }
+        if (!(await isCaseExactDirectory(dependencies, repoRoot, normalizedPath))) {
+            warnings.push(`${source} entry ${JSON.stringify(normalizedPath)} matches no directory in this repository (matching is case-sensitive), so it excludes nothing.`);
+            continue;
+        }
+        effective.push(normalizedPath);
+    }
+    return { configured, effective, warnings };
+}
+async function scanInstructionDirectories(repoRoot, dependencies, debug, excludedPaths = new Set()) {
     const queue = [repoRoot];
     const directoryEntries = new Map();
     while (queue.length > 0) {
@@ -123,6 +288,19 @@ async function scanInstructionDirectories(repoRoot, dependencies, debug) {
                     }
                     continue;
                 }
+                // Deliberately after the carve-in above, never before it: the carve-in
+                // path is already queued by the time a configured exclusion is tested,
+                // so excluding `.oat` (or any documentation root that happens to
+                // contain one) still leaves `.oat/repo/**` scanned. Skipping the
+                // directory here also skips its whole subtree, because a directory
+                // that is never queued is never read.
+                if (excludedPaths.size > 0) {
+                    const relativePath = toPosixPath(relative(repoRoot, entryPath));
+                    if (excludedPaths.has(relativePath)) {
+                        debug?.(`Skipping excluded directory ${relativePath}`);
+                        continue;
+                    }
+                }
                 queue.push(entryPath);
                 continue;
             }
@@ -181,7 +359,7 @@ export async function scanInstructionFiles(repoRoot, options = {}, overrides = {
         stat,
         ...overrides,
     };
-    const instructionDirectories = await scanInstructionDirectories(repoRoot, dependencies, options.debug);
+    const instructionDirectories = await scanInstructionDirectories(repoRoot, dependencies, options.debug, new Set(normalizeExcludedPaths(options.excludedPaths)));
     const entries = [];
     for (const [directoryPath, directoryEntry] of instructionDirectories) {
         const agentsPath = directoryEntry.agentsPath ?? null;
@@ -402,15 +580,34 @@ function deriveInstructionsStatus(entries, actions) {
     }
     return 'ok';
 }
-export function buildInstructionsPayload({ mode, entries, actions, }) {
+export function buildInstructionsPayload({ mode, entries, actions, excludedPaths, effectiveExcludedPaths, exclusionWarnings, }) {
     const normalizedEntries = normalizeEntries(entries);
     const normalizedActions = normalizeActions(actions);
+    const normalizedExcludedPaths = normalizeExcludedPaths(excludedPaths);
+    const normalizedEffectivePaths = normalizeExcludedPaths(effectiveExcludedPaths);
     return {
         mode,
         status: deriveInstructionsStatus(normalizedEntries, normalizedActions),
         summary: buildInstructionsSummary(normalizedEntries, normalizedActions),
         entries: normalizedEntries,
         actions: normalizedActions,
+        // Both omitted when nothing is configured, so a repository with no
+        // documentation root keeps its existing payload shape exactly. Once
+        // `excludedPaths` is present its effective counterpart always is too, even
+        // when empty: "configured three, protected none" is precisely the state a
+        // consumer must be able to see, and omitting the field would hide it.
+        ...(normalizedExcludedPaths.length > 0
+            ? {
+                excludedPaths: normalizedExcludedPaths,
+                effectiveExcludedPaths: normalizedEffectivePaths,
+            }
+            : {}),
+        // Independent of the two fields above: an entry rejected during
+        // normalization produces a warning but no configured path, and that is
+        // exactly the case a JSON consumer must still be able to see.
+        ...(exclusionWarnings !== undefined && exclusionWarnings.length > 0
+            ? { exclusionWarnings }
+            : {}),
     };
 }
 export function formatInstructionsReport(payload, repoRoot) {

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

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

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

@@ -2,7 +2,7 @@ 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 { 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 { buildInstructionsPayload, DEFAULT_INSTRUCTION_SYNC_STRATEGY, EXPECTED_CLAUDE_CONTENT, formatInstructionsReport, resolveInstructionPointerExcludes, resolveInstructionSyncStrategy, scanInstructionFiles, } from '../../instructions/instructions.utils.js';
 import { readGlobalOptions } from '../../shared/shared.utils.js';
 import { CliError } from '../../../errors/cli-error.js';
 import { resolveProjectRoot } from '../../../fs/paths.js';
@@ -16,6 +16,7 @@ function defaultDependencies() {
         lstat,
         readFile,
         removeFile: removeInstructionFile,
+        resolveInstructionPointerExcludes,
         resolveProjectRoot,
         scanInstructionFiles,
         symlinkFile: async (target, path) => {
@@ -249,7 +250,14 @@ export function createInstructionsSyncCommand(overrides = {}) {
         try {
             const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
             const strategy = resolveInstructionSyncStrategy(options.strategy);
+            const exclusions = await dependencies.resolveInstructionPointerExcludes(repoRoot);
+            // Warned before any work: an operator whose opt-out silently matches
+            // nothing must hear about it even when the sync then succeeds.
+            for (const warning of exclusions.warnings) {
+                context.logger.warn(warning);
+            }
             const entries = await dependencies.scanInstructionFiles(repoRoot, {
+                excludedPaths: exclusions.configured,
                 strategy,
             });
             const plannedActions = planSyncActions({
@@ -267,6 +275,9 @@ export function createInstructionsSyncCommand(overrides = {}) {
                     ? entries
                     : getPostSyncEntries(entries, actions, strategy),
                 actions,
+                excludedPaths: exclusions.configured,
+                effectiveExcludedPaths: exclusions.effective,
+                exclusionWarnings: exclusions.warnings,
             });
             if (context.json) {
                 context.logger.json(payload);

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

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

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

@@ -1,6 +1,6 @@
 import { buildCommandContext } from '../../../app/command-context.js';
 import { INSTRUCTION_SYNC_STRATEGIES, } from '../../instructions/instructions.types.js';
-import { buildInstructionsPayload, DEFAULT_INSTRUCTION_SYNC_STRATEGY, formatInstructionsReport, resolveInstructionSyncStrategy, scanInstructionFiles, } from '../../instructions/instructions.utils.js';
+import { buildInstructionsPayload, DEFAULT_INSTRUCTION_SYNC_STRATEGY, formatInstructionsReport, resolveInstructionPointerExcludes, resolveInstructionSyncStrategy, scanInstructionFiles, } from '../../instructions/instructions.utils.js';
 import { readGlobalOptions } from '../../shared/shared.utils.js';
 import { CliError } from '../../../errors/cli-error.js';
 import { resolveProjectRoot } from '../../../fs/paths.js';
@@ -8,6 +8,7 @@ import { Command, Option } from 'commander';
 function defaultDependencies() {
     return {
         buildCommandContext,
+        resolveInstructionPointerExcludes,
         resolveProjectRoot,
         scanInstructionFiles,
     };
@@ -27,13 +28,23 @@ export function createInstructionsValidateCommand(overrides = {}) {
         const strategy = resolveInstructionSyncStrategy(options.strategy);
         try {
             const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
+            const exclusions = await dependencies.resolveInstructionPointerExcludes(repoRoot);
+            // Warned before any work: an operator whose opt-out silently matches
+            // nothing must hear about it even when validate then reports `ok`.
+            for (const warning of exclusions.warnings) {
+                context.logger.warn(warning);
+            }
             const entries = await dependencies.scanInstructionFiles(repoRoot, {
+                excludedPaths: exclusions.configured,
                 strategy,
             });
             const payload = buildInstructionsPayload({
                 mode: 'validate',
                 entries,
                 actions: [],
+                excludedPaths: exclusions.configured,
+                effectiveExcludedPaths: exclusions.effective,
+                exclusionWarnings: exclusions.warnings,
             });
             if (context.json) {
                 context.logger.json(payload);