@open-agent-toolkit/cli 0.3.7 → 0.3.9

package/dist/config/oat-config.js

@@ -8,6 +8,36 @@ import { normalizeDispatchMatrix, } from './dispatch-matrix.js';
 import { parseJsonConfig } from './json.js';
 import { resolveUserSyncConfig } from './user-sync-config.js';
 export { VALID_DISPATCH_MATRIX_TIERS, isCodexMaterializedRouteTarget, isWorkflowDispatchCandidateLadder, isWorkflowDispatchFallbackRoute, toWorkflowDispatchCandidateLadder, validateDispatchRouteTarget, } from './dispatch-matrix.js';
+/**
+ * The CLAUDE.md strategies `oat instructions sync` and
+ * `oat instructions validate` understand, and the values
+ * `instructions.claude.shims` accepts. `none` keeps no CLAUDE.md
+ * shims at all; the other three are the shim strategies.
+ *
+ * Declared here rather than in the instructions command so the config
+ * normalizer, the `oat config set` validator, and the commands share one list:
+ * a value the normalizer accepted but the commands did not understand would
+ * silently fall through to the built-in default.
+ */
+export const INSTRUCTION_SYNC_STRATEGIES = [
+    'none',
+    'pointer',
+    'symlink',
+    'copy',
+];
+/**
+ * The strategy used when neither `--strategy` nor
+ * `instructions.claude.shims` names one.
+ *
+ * `none` (DR-260927-claude-md-shims-are-opt): Claude Code reads AGENTS.md
+ * itself through its `agents-md` plugin, which stands down for the whole
+ * project while any CLAUDE.md exists, so shims are opt-in.
+ */
+export const DEFAULT_INSTRUCTION_SYNC_STRATEGY = 'none';
+export function isInstructionSyncStrategy(value) {
+    return (typeof value === 'string' &&
+        INSTRUCTION_SYNC_STRATEGIES.includes(value));
+}
 export const MIN_GATE_TIMEOUT_MS = 1_000;
 export const MAX_GATE_TIMEOUT_MS = 14_400_000;
 export function isValidGateTimeoutMs(value) {
@@ -635,13 +665,18 @@ function normalizePjmRemoteSharedConfig(value, configPath) {
 function assertClosedPjmRemoteSharedConfig(value, configPath) {
     const findings = [];
     collectUnknownPjmRemoteKeys(value, ['schemaVersion', 'storage', 'policy'], 'pjm.remote', findings);
+    if ('schemaVersion' in value && typeof value.schemaVersion !== 'number') {
+        findings.push(`pjm.remote.schemaVersion (expected number, received ${describePjmRemoteStructure(value.schemaVersion)})`);
+    }
     if ('storage' in value &&
         collectPjmRemoteExpectedObject(value.storage, 'pjm.remote.storage', findings)) {
         collectUnknownPjmRemoteKeys(value.storage, ['state'], 'pjm.remote.storage', findings);
+        collectPjmRemoteStringLeaf(value.storage, 'state', 'pjm.remote.storage', findings);
     }
     if ('policy' in value &&
         collectPjmRemoteExpectedObject(value.policy, 'pjm.remote.policy', findings)) {
         collectUnknownPjmRemoteKeys(value.policy, ['description', 'authority', 'providers'], 'pjm.remote.policy', findings);
+        collectPjmRemoteStringLeaf(value.policy, 'description', 'pjm.remote.policy', findings);
         if ('authority' in value.policy) {
             collectPjmRemoteAuthorityFindings(value.policy.authority, 'pjm.remote.policy.authority', findings);
         }
@@ -656,6 +691,7 @@ function assertClosedPjmRemoteSharedConfig(value, configPath) {
                     continue;
                 }
                 collectUnknownPjmRemoteKeys(providerPolicy, ['description', 'authority'], `pjm.remote.policy.providers.${provider}`, findings);
+                collectPjmRemoteStringLeaf(providerPolicy, 'description', `pjm.remote.policy.providers.${provider}`, findings);
                 if ('authority' in providerPolicy) {
                     collectPjmRemoteAuthorityFindings(providerPolicy.authority, `pjm.remote.policy.providers.${provider}.authority`, findings);
                 }
@@ -670,11 +706,27 @@ function collectPjmRemoteAuthorityFindings(value, path, findings) {
     if (!collectPjmRemoteExpectedObject(value, path, findings))
         return;
     collectUnknownPjmRemoteKeys(value, ['default', 'operations'], path, findings);
+    collectPjmRemoteStringLeaf(value, 'default', path, findings);
     if ('operations' in value &&
         collectPjmRemoteExpectedObject(value.operations, `${path}.operations`, findings)) {
         collectUnknownPjmRemoteKeys(value.operations, PJM_REMOTE_OPERATION_CLASSES, `${path}.operations`, findings);
+        for (const operation of PJM_REMOTE_OPERATION_CLASSES) {
+            collectPjmRemoteStringLeaf(value.operations, operation, `${path}.operations`, findings);
+        }
     }
 }
+/**
+ * Records a present leaf whose value is not a string.
+ *
+ * Only the *type* is checked: an unrecognized string keeps its documented
+ * coercion in the normalizer. The finding names the structure type, never the
+ * value, so a secret pasted into the wrong field cannot leak into the error.
+ */
+function collectPjmRemoteStringLeaf(value, key, path, findings) {
+    if (!(key in value) || typeof value[key] === 'string')
+        return;
+    findings.push(`${path}.${key} (expected string, received ${describePjmRemoteStructure(value[key])})`);
+}
 function collectPjmRemoteExpectedObject(value, path, findings) {
     if (isRecord(value) && !Array.isArray(value))
         return true;
@@ -812,7 +864,7 @@ function normalizeDocumentationExcludes(value, configPath) {
     return normalized;
 }
 /**
- * Parse `documentation.instructionPointerExcludes` into a trimmed,
+ * Parse `instructions.claude.excludes` into a trimmed,
  * de-duplicated, order-preserving list.
  *
  * Fails closed, exactly like its `documentation.excludes` sibling above and for
@@ -822,7 +874,7 @@ function normalizeDocumentationExcludes(value, configPath) {
  * an error.
  *
  * The repair instruction names `oat config set` first and the file second: the
- * command is catalogued (`oat config set documentation.instructionPointerExcludes`),
+ * command is catalogued (`oat config set instructions.claude.excludes`),
  * and an operator repairing a malformed value should reach for the validated
  * write path before hand-editing JSON.
  */
@@ -831,8 +883,8 @@ function normalizeInstructionPointerExcludes(value, configPath) {
         return [];
     }
     const invalid = () => {
-        throw new CliError(`Invalid documentation.instructionPointerExcludes in ${configPath}: expected an array of non-empty strings. ` +
-            'Repair it with `oat config set documentation.instructionPointerExcludes <path[,path...]>` (an empty value clears the key), or by editing that file.', 2);
+        throw new CliError(`Invalid instructions.claude.excludes in ${configPath}: expected an array of non-empty strings. ` +
+            'Repair it with `oat config set instructions.claude.excludes <path[,path...]>` (an empty value clears the key), or by editing that file.', 2);
     };
     if (!Array.isArray(value)) {
         invalid();
@@ -849,6 +901,27 @@ function normalizeInstructionPointerExcludes(value, configPath) {
     }
     return normalized;
 }
+/**
+ * Parse `instructions.claude.shims`.
+ *
+ * Fails closed like `projects.defaultScope`: a misspelled strategy must never
+ * read as unset, because unset means the built-in default, and the default
+ * decides whether `oat instructions sync` writes CLAUDE.md files. An absent key
+ * is "not configured"; any present value outside the accepted list is an error
+ * that names the `oat config set` repair.
+ */
+function normalizeInstructionSyncStrategy(value, configPath) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!isInstructionSyncStrategy(value)) {
+        const accepted = INSTRUCTION_SYNC_STRATEGIES.join('|');
+        throw new CliError(`Invalid instructions.claude.shims in ${configPath}: ${JSON.stringify(value)}. ` +
+            `Expected one of: ${INSTRUCTION_SYNC_STRATEGIES.join(', ')}. ` +
+            `Repair it with oat config set instructions.claude.shims <${accepted}>.`, 2);
+    }
+    return value;
+}
 /**
  * Report a stored value whose type the normalizer cannot use.
  *
@@ -999,14 +1072,24 @@ function normalizeOatConfig(parsed, configPath = '.oat/config.json', onWarning)
         if (excludes.length > 0) {
             doc.excludes = excludes;
         }
-        const instructionPointerExcludes = normalizeInstructionPointerExcludes(parsed.documentation.instructionPointerExcludes, configPath);
-        if (instructionPointerExcludes.length > 0) {
-            doc.instructionPointerExcludes = instructionPointerExcludes;
-        }
         if (Object.keys(doc).length > 0) {
             next.documentation = doc;
         }
     }
+    if (isRecord(parsed.instructions) && isRecord(parsed.instructions.claude)) {
+        const claude = {};
+        const shims = normalizeInstructionSyncStrategy(parsed.instructions.claude.shims, configPath);
+        if (shims !== undefined) {
+            claude.shims = shims;
+        }
+        const excludes = normalizeInstructionPointerExcludes(parsed.instructions.claude.excludes, configPath);
+        if (excludes.length > 0) {
+            claude.excludes = excludes;
+        }
+        if (Object.keys(claude).length > 0) {
+            next.instructions = { claude };
+        }
+    }
     if (Array.isArray(parsed.localPaths)) {
         const filtered = parsed.localPaths.filter((v) => typeof v === 'string' && v.trim() !== '');
         if (filtered.length > 0) {
@@ -1176,8 +1259,24 @@ export async function readOatConfigForDocumentationExcludesRepair(repoRoot) {
     }
 }
 /**
- * Read the shared config with a malformed
- * `documentation.instructionPointerExcludes` dropped.
+ * Return `parsed` with `instructions.claude.<key>` removed, leaving every other
+ * value untouched, so a repair read can load the file whose value it replaces.
+ */
+function withoutInstructionsClaudeKey(parsed, key) {
+    if (!isRecord(parsed) ||
+        !isRecord(parsed.instructions) ||
+        !isRecord(parsed.instructions.claude)) {
+        return parsed;
+    }
+    const claude = Object.fromEntries(Object.entries(parsed.instructions.claude).filter(([name]) => name !== key));
+    return {
+        ...parsed,
+        instructions: { ...parsed.instructions, claude },
+    };
+}
+/**
+ * Read the shared config with a malformed `instructions.claude.excludes`
+ * dropped.
  *
  * The sibling of `readOatConfigForDocumentationExcludesRepair`, and it exists
  * for the same reason: this key's own validation error now names
@@ -1189,11 +1288,27 @@ export async function readOatConfigForInstructionPointerExcludesRepair(repoRoot)
     try {
         const raw = await readFile(configPath, 'utf8');
         const parsed = parseJsonConfig(raw, configPath);
-        if (isRecord(parsed) && isRecord(parsed.documentation)) {
-            const { instructionPointerExcludes: _invalidInstructionPointerExcludes, ...documentation } = parsed.documentation;
-            return normalizeOatConfig({ ...parsed, documentation }, configPath);
+        return normalizeOatConfig(withoutInstructionsClaudeKey(parsed, 'excludes'), configPath);
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return { ...DEFAULT_OAT_CONFIG };
         }
-        return normalizeOatConfig(parsed, configPath);
+        throw error;
+    }
+}
+/**
+ * Read the shared config with a malformed `instructions.claude.shims`
+ * dropped, so the
+ * `oat config set`/`unset` repair its validation error names can load the file
+ * it is repairing.
+ */
+export async function readOatConfigForInstructionSyncStrategyRepair(repoRoot) {
+    const configPath = getConfigPath(repoRoot);
+    try {
+        const raw = await readFile(configPath, 'utf8');
+        const parsed = parseJsonConfig(raw, configPath);
+        return normalizeOatConfig(withoutInstructionsClaudeKey(parsed, 'shims'), configPath);
     }
     catch (error) {
         if (isMissingFileError(error)) {
@@ -1219,10 +1334,103 @@ export async function readOatLocalConfig(repoRoot) {
         throw error;
     }
 }
+/**
+ * Reads the existing config file as raw JSON for ordering and no-op checks.
+ *
+ * Parses through `parseJsonConfig`, the same tolerant parser every config
+ * reader uses (trailing commas accepted, `__proto__` kept as data), so a file
+ * the readers accept is never treated as unparsable here. Deliberately
+ * bypasses the normalizer, which throws on the malformed values repair flows
+ * exist to remove. A missing or unparsable file yields `undefined`, so the
+ * caller always writes it.
+ */
+async function readRawJsonForWrite(filePath) {
+    let raw;
+    try {
+        raw = await readFile(filePath, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        return parseJsonConfig(raw, filePath);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isPlainJsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Orders `value` like `template`, recursively: keys already present in the
+ * template keep their existing position, and new keys follow in the
+ * normalizer's order. Arrays keep their own element order.
+ */
+function orderLike(value, template) {
+    if (Array.isArray(value)) {
+        return value.map((element, index) => orderLike(element, Array.isArray(template) ? template[index] : undefined));
+    }
+    if (!isPlainJsonObject(value))
+        return value;
+    const templateObject = isPlainJsonObject(template) ? template : {};
+    const ordered = {};
+    // Define rather than assign: a config key named `__proto__` is data and must
+    // never replace the output object's prototype.
+    const place = (key, next) => {
+        Object.defineProperty(ordered, key, {
+            value: next,
+            enumerable: true,
+            writable: true,
+            configurable: true,
+        });
+    };
+    for (const key of Object.keys(templateObject)) {
+        if (Object.hasOwn(value, key) && value[key] !== undefined) {
+            place(key, orderLike(value[key], templateObject[key]));
+        }
+    }
+    for (const key of Object.keys(value)) {
+        if (!Object.hasOwn(ordered, key) && value[key] !== undefined) {
+            place(key, orderLike(value[key], undefined));
+        }
+    }
+    return ordered;
+}
+function jsonDeepEqual(left, right) {
+    if (Array.isArray(left) || Array.isArray(right)) {
+        return (Array.isArray(left) &&
+            Array.isArray(right) &&
+            left.length === right.length &&
+            left.every((element, index) => jsonDeepEqual(element, right[index])));
+    }
+    if (isPlainJsonObject(left) || isPlainJsonObject(right)) {
+        if (!isPlainJsonObject(left) || !isPlainJsonObject(right))
+            return false;
+        const leftKeys = Object.keys(left);
+        return (leftKeys.length === Object.keys(right).length &&
+            leftKeys.every((key) => Object.hasOwn(right, key) && jsonDeepEqual(left[key], right[key])));
+    }
+    return Object.is(left, right);
+}
+/**
+ * Writes the shared config, preserving the existing file's key order and
+ * skipping writes that would not change its JSON value (GitHub #329, #311).
+ *
+ * Formatting-only differences (indentation, trailing newline) therefore leave
+ * the file byte-identical, while repairs, raw-disk removals, and rewrites of a
+ * malformed or unparsable file always land.
+ */
 export async function writeOatConfig(repoRoot, config) {
     const configPath = getConfigPath(repoRoot);
     const normalized = normalizeOatConfig(config, configPath);
-    await atomicWriteJson(configPath, normalized);
+    const existing = await readRawJsonForWrite(configPath);
+    // Round-trip through JSON so the comparison sees exactly what would be
+    // serialized (undefined-valued keys dropped).
+    const output = JSON.parse(JSON.stringify(existing === undefined ? normalized : orderLike(normalized, existing)));
+    if (existing !== undefined && jsonDeepEqual(existing, output))
+        return;
+    await atomicWriteJson(configPath, output);
 }
 export async function writeOatLocalConfig(repoRoot, config) {
     const configPath = getLocalConfigPath(repoRoot);

package/dist/config/resolve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/config/resolve.ts"],"names":[],"mappings":"AACA,OAAO,EAML,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,UAAU,EAChB,MAAM,cAAc,CAAC;AAGtB,MAAM,MAAM,oBAAoB,GAC5B,QAAQ,GACR,OAAO,GACP,MAAM,GACN,KAAK,GACL,SAAS,CAAC;AAEd,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,oBAAoB,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,SAAS,CAAC;IAClB,KAAK,EAAE,cAAc,CAAC;IACtB,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,kCAAkC;IACjD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,cAAc,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CAChE;AAgHD,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,SAAS,GAAE,OAAO,CAAC,kCAAkC,CAAM,GAC1D,OAAO,CAAC,cAAc,CAAC,CAgFzB;AAED,wDAAwD;AACxD,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE3D,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IACxB;;;;OAIG;IACH,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACjC;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,cAAc,EACzB,SAAS,EAAE,MAAM,GAChB,sBAAsB,CAkBxB;AAED,wBAAgB,WAAW,CACzB,SAAS,EAAE,cAAc,EACzB,SAAS,EAAE,MAAM,GAChB,UAAU,GAAG,IAAI,CAEnB;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,cAAc,GACxB,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAY5B;AAED,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEvE,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,gBAAgB,CAAC;IACzB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,cAAc,GACxB,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CA0DxC;AAiMD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB,MAAM,GAAG,SAAS,CAQpB"}
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/config/resolve.ts"],"names":[],"mappings":"AACA,OAAO,EAOL,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,UAAU,EAChB,MAAM,cAAc,CAAC;AAGtB,MAAM,MAAM,oBAAoB,GAC5B,QAAQ,GACR,OAAO,GACP,MAAM,GACN,KAAK,GACL,SAAS,CAAC;AAEd,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,oBAAoB,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,SAAS,CAAC;IAClB,KAAK,EAAE,cAAc,CAAC;IACtB,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,kCAAkC;IACjD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,cAAc,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CAChE;AA0HD,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,SAAS,GAAE,OAAO,CAAC,kCAAkC,CAAM,GAC1D,OAAO,CAAC,cAAc,CAAC,CAgFzB;AAED,wDAAwD;AACxD,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE3D,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IACxB;;;;OAIG;IACH,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACjC;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,cAAc,EACzB,SAAS,EAAE,MAAM,GAChB,sBAAsB,CAkBxB;AAED,wBAAgB,WAAW,CACzB,SAAS,EAAE,cAAc,EACzB,SAAS,EAAE,MAAM,GAChB,UAAU,GAAG,IAAI,CAEnB;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,cAAc,GACxB,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAY5B;AAED,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEvE,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,gBAAgB,CAAC;IACzB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,cAAc,GACxB,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CA0DxC;AAiMD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB,MAAM,GAAG,SAAS,CAQpB"}

package/dist/config/resolve.js

@@ -1,5 +1,5 @@
 import { isWorkflowDispatchCandidateLadder } from './dispatch-matrix.js';
-import { BUILTIN_EXEC_TARGETS, isWorkflowPostImplementStructuredSequence, readOatConfig, readOatLocalConfig, readUserConfig, } from './oat-config.js';
+import { BUILTIN_EXEC_TARGETS, DEFAULT_INSTRUCTION_SYNC_STRATEGY, isWorkflowPostImplementStructuredSequence, readOatConfig, readOatLocalConfig, readUserConfig, } from './oat-config.js';
 import { getOwnKey, setOwnKey } from './own-keys.js';
 const DEFAULT_DEPENDENCIES = {
     readOatConfig,
@@ -35,9 +35,19 @@ const DEFAULT_SHARED_CONFIG = {
         // is absent here has no row at all while it is unset. `null` keeps meaning
         // "not set at this layer", so a configured array still wins.
         excludes: null,
-        instructionPointerExcludes: null,
         requireForProjectCompletion: false,
     },
+    instructions: {
+        claude: {
+            // The strategy `oat instructions sync` applies when neither
+            // `--strategy` nor this key names one, so `oat config get` reports what
+            // will happen.
+            shims: DEFAULT_INSTRUCTION_SYNC_STRATEGY,
+            // Listed for the same reason as `documentation.excludes`: `oat config
+            // dump` enumerates the resolved map, and `null` means "not set here".
+            excludes: null,
+        },
+    },
     tools: {
         brainstorm: false,
         core: false,

package/dist/engine/compute-plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compute-plan.d.ts","sourceRoot":"","sources":["../../src/engine/compute-plan.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGtD,OAAO,KAAK,EACV,QAAQ,EACR,aAAa,EAGd,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAEV,eAAe,EAChB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAGjD,OAAO,KAAK,EAEV,WAAW,EACX,oBAAoB,EACpB,QAAQ,EAET,MAAM,gBAAgB,CAAC;AAGxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,UAAU,mBAAmB;IAC3B,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,WAAW,CAAC;IACnB,MAAM,EAAE,UAAU,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,sCAAsC,CAAC,EAAE,QAAQ,CAC/C,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAClC,CAAC;IACF,+BAA+B,CAAC,EAAE,SAAS;QACzC,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,WAAW,CAAC;KAC1B,EAAE,CAAC;IACJ,gCAAgC,CAAC,EAAE,OAAO,CAAC;CAC5C;AAiOD,wBAAsB,iCAAiC,CACrD,aAAa,EAAE,aAAa,EAC5B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,oBAAoB,CAAC,CAqG/B;AAyJD,wBAAsB,eAAe,CAAC,EACpC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,KAAK,EACL,MAAM,EACN,SAAS,EAAE,iBAAiB,EAC5B,qBAAqB,EACrB,sCAAsC,EACtC,+BAAoC,EACpC,gCAAwC,GACzC,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC,CA4bzC"}
+{"version":3,"file":"compute-plan.d.ts","sourceRoot":"","sources":["../../src/engine/compute-plan.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAItD,OAAO,KAAK,EACV,QAAQ,EACR,aAAa,EAGd,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAEV,eAAe,EAChB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAGjD,OAAO,KAAK,EAEV,WAAW,EACX,oBAAoB,EACpB,QAAQ,EAET,MAAM,gBAAgB,CAAC;AAGxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,UAAU,mBAAmB;IAC3B,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,WAAW,CAAC;IACnB,MAAM,EAAE,UAAU,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,sCAAsC,CAAC,EAAE,QAAQ,CAC/C,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAClC,CAAC;IACF,+BAA+B,CAAC,EAAE,SAAS;QACzC,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,WAAW,CAAC;KAC1B,EAAE,CAAC;IACJ,gCAAgC,CAAC,EAAE,OAAO,CAAC;CAC5C;AAiOD,wBAAsB,iCAAiC,CACrD,aAAa,EAAE,aAAa,EAC5B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,oBAAoB,CAAC,CAqG/B;AAyJD,wBAAsB,eAAe,CAAC,EACpC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,KAAK,EACL,MAAM,EACN,SAAS,EAAE,iBAAiB,EAC5B,qBAAqB,EACrB,sCAAsC,EACtC,+BAAoC,EACpC,gCAAwC,GACzC,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC,CA6dzC"}

package/dist/engine/compute-plan.js

@@ -1,5 +1,6 @@
 import { access, lstat, readFile, readlink, stat } from 'node:fs/promises';
 import { basename, dirname, join, normalize, relative, resolve, } from 'node:path';
+import { CliError } from '../errors/index.js';
 import { computeContentHash, computeStringHash } from '../manifest/hash.js';
 import { findEntry } from '../manifest/manager.js';
 import { getSyncMappings } from '../providers/shared/adapter.utils.js';
@@ -315,6 +316,7 @@ export async function computeSyncPlan({ canonical, adapters, manifest, scope, co
     const collections = [];
     const scopeRoot = resolveScopeRoot(canonical, explicitScopeRoot);
     const seenCanonicalKeys = new Set();
+    const transformFailures = new Map();
     const activeProviderNames = new Set();
     const activeMappingsByProvider = new Map();
     const manifestV2 = manifest;
@@ -538,9 +540,27 @@ export async function computeSyncPlan({ canonical, adapters, manifest, scope, co
                 if (!entryInsideMapping(canonicalEntry, mapping.canonicalDir)) {
                     continue;
                 }
-                const renderedContent = mapping.transformCanonical && canonicalEntry.isFile
-                    ? mapping.transformCanonical(await readFile(canonicalEntry.canonicalPath, 'utf8'), relativeCanonicalPath.replaceAll('\\', '/'))
-                    : undefined;
+                let renderedContent;
+                if (mapping.transformCanonical && canonicalEntry.isFile) {
+                    const displayPath = relativeCanonicalPath.replaceAll('\\', '/');
+                    try {
+                        renderedContent = mapping.transformCanonical(await readFile(canonicalEntry.canonicalPath, 'utf8'), displayPath);
+                    }
+                    catch (error) {
+                        if (!(error instanceof CliError)) {
+                            throw error;
+                        }
+                        // Every provider transform parses the same canonical file, so key
+                        // the failure by path and report each invalid file exactly once.
+                        const failureKey = normalize(relativeCanonicalPath);
+                        if (!transformFailures.has(failureKey)) {
+                            transformFailures.set(failureKey, error.message.includes(displayPath)
+                                ? error.message
+                                : `${displayPath}: ${error.message}`);
+                        }
+                        continue;
+                    }
+                }
                 const entryScopeRoot = scopeRoot
                     ? scopeRoot
                     : resolveScopeRootFromCanonical(canonicalEntry, relativeCanonicalPath);
@@ -579,6 +599,14 @@ export async function computeSyncPlan({ canonical, adapters, manifest, scope, co
             }
         }
     }
+    if (transformFailures.size > 0) {
+        const count = transformFailures.size;
+        throw new CliError(`Sync stopped: ${count} invalid canonical ${count === 1 ? 'rule' : 'rules'}. Fix ${count === 1 ? 'it' : 'them'} and re-run oat sync:\n${[
+            ...transformFailures.values(),
+        ]
+            .map((message) => `  - ${message}`)
+            .join('\n')}`);
+    }
     if (!scopeRoot) {
         return { scope, entries, removals, collections };
     }

package/dist/providers/claude/dispatch-envelope.d.ts

@@ -1,4 +1,5 @@
 import { type GenericDispatchRecord } from '../identity/generic-dispatch-record.js';
+import { z } from 'zod';
 import { type ClaudeCapabilityEvidence } from './targets.js';
 export interface AcceptedClaudeLaunchEnvelope {
     schemaVersion: 1;
@@ -16,19 +17,71 @@ export interface AcceptedClaudeLaunchEnvelope {
         model?: string;
     };
 }
+type ResolverRole = AcceptedClaudeLaunchEnvelope['resolverRole'];
+/**
+ * One violation found while validating a managed Claude dispatch input.
+ * `stage` is the top-level input key it belongs to (`claudeLaunch`,
+ * `recordBase`, or `event`); `path` locates it inside that stage.
+ * Messages name fields and expected forms; they are still routed through the
+ * command's redaction boundary because a few echo caller-supplied selectors.
+ */
+export interface ManagedClaudeViolation {
+    stage: string;
+    path: string;
+    message: string;
+}
+/** Render a Zod issue path as `a.b[0].c`, or `<root>` when empty. */
+export declare function formatIssuePath(prefix: string | null, path: readonly (string | number)[]): string;
+export declare function zodIssueViolations(stage: string, prefix: string | null, error: z.ZodError): ManagedClaudeViolation[];
 /**
  * Validate the managed resolver result against the generated provider role and
  * the exact payload that will be launched. This is the production boundary
  * used by the project dispatch-record producer for managed Claude dispatches.
+ * It stops at the first failure; {@link collectClaudeLaunchViolations} reports
+ * every failure for a caller building its input.
  */
 export declare function acceptClaudeLaunchEnvelope(input: {
     resolution: unknown;
     definition: string;
     launch: unknown;
 }): AcceptedClaudeLaunchEnvelope;
+/**
+ * Report every `claudeLaunch` violation in one pass: each schema issue in the
+ * resolution and the payload, then every consistency check the parsed inputs
+ * allow. Consistency checks depend on a parsed resolution, and the two payload
+ * checks on a parsed payload; those are skipped and named in `skipped` rather
+ * than reported against a value that failed to parse.
+ */
+export declare function collectClaudeLaunchViolations(claudeLaunch: unknown): {
+    resolverRole: ResolverRole | null;
+    violations: ManagedClaudeViolation[];
+    skipped: string[];
+};
+/**
+ * Report every `recordBase` violation in one pass: each derived field that is
+ * present, the action/role check, every missing, mistyped, or unknown field,
+ * every absolute path in an identity or control field, and every sensitive key
+ * or value. The action/role check needs a parsed resolution and is skipped
+ * without one.
+ */
+export declare function collectClaudeRecordBaseViolations(candidate: unknown, resolverRole: ResolverRole | null): {
+    violations: ManagedClaudeViolation[];
+    skipped: string[];
+};
+/**
+ * One error for a whole validation run: a header, then one
+ * `stage path: message` line per violation, then the checks that were skipped
+ * because they depend on a stage that failed to parse.
+ */
+export declare class ManagedClaudeDispatchValidationError extends Error {
+    readonly violations: readonly ManagedClaudeViolation[];
+    readonly skipped: readonly string[];
+    constructor(violations: readonly ManagedClaudeViolation[], skipped?: readonly string[]);
+}
 /** Build configured invocation evidence only from an accepted launch envelope. */
 export declare function buildClaudeDispatchRecord(input: {
     envelope: AcceptedClaudeLaunchEnvelope;
     recordBase: unknown;
 }): GenericDispatchRecord;
+export {};
 //# sourceMappingURL=dispatch-envelope.d.ts.map

package/dist/providers/claude/dispatch-envelope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch-envelope.d.ts","sourceRoot":"","sources":["../../../src/providers/claude/dispatch-envelope.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,6CAA6C,CAAC;AAKrD,OAAO,EAEL,KAAK,wBAAwB,EAE9B,MAAM,WAAW,CAAC;AA4FnB,MAAM,WAAW,4BAA4B;IAC3C,aAAa,EAAE,CAAC,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC;IACnB,YAAY,EAAE,aAAa,GAAG,UAAU,CAAC;IACzC,QAAQ,EAAE,uBAAuB,GAAG,cAAc,CAAC;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB,EAAE,wBAAwB,CAAC;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE;QACP,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAsCD;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IAChD,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;CACjB,GAAG,4BAA4B,CA6F/B;AAmBD,kFAAkF;AAClF,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,QAAQ,EAAE,4BAA4B,CAAC;IACvC,UAAU,EAAE,OAAO,CAAC;CACrB,GAAG,qBAAqB,CAoDxB"}
+{"version":3,"file":"dispatch-envelope.d.ts","sourceRoot":"","sources":["../../../src/providers/claude/dispatch-envelope.ts"],"names":[],"mappings":"AACA,OAAO,EAOL,KAAK,qBAAqB,EAC3B,MAAM,6CAA6C,CAAC;AAErD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAEL,KAAK,wBAAwB,EAE9B,MAAM,WAAW,CAAC;AA4FnB,MAAM,WAAW,4BAA4B;IAC3C,aAAa,EAAE,CAAC,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC;IACnB,YAAY,EAAE,aAAa,GAAG,UAAU,CAAC;IACzC,QAAQ,EAAE,uBAAuB,GAAG,cAAc,CAAC;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB,EAAE,wBAAwB,CAAC;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE;QACP,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAgBD,KAAK,YAAY,GAAG,4BAA4B,CAAC,cAAc,CAAC,CAAC;AAEjE;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAOD,qEAAqE;AACrE,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GACjC,MAAM,CAWR;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,KAAK,EAAE,CAAC,CAAC,QAAQ,GAChB,sBAAsB,EAAE,CAM1B;AAsID;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IAChD,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;CACjB,GAAG,4BAA4B,CAgC/B;AASD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,YAAY,EAAE,OAAO,GAAG;IACpE,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;IAClC,UAAU,EAAE,sBAAsB,EAAE,CAAC;IACrC,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAqDA;AAuDD;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAC/C,SAAS,EAAE,OAAO,EAClB,YAAY,EAAE,YAAY,GAAG,IAAI,GAChC;IAAE,UAAU,EAAE,sBAAsB,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAkE7D;AAMD;;;;GAIG;AACH,qBAAa,oCAAqC,SAAQ,KAAK;IAC7D,QAAQ,CAAC,UAAU,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACvD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAEpC,YACE,UAAU,EAAE,SAAS,sBAAsB,EAAE,EAC7C,OAAO,GAAE,SAAS,MAAM,EAAO,EAyBhC;CACF;AAmBD,kFAAkF;AAClF,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,QAAQ,EAAE,4BAA4B,CAAC;IACvC,UAAU,EAAE,OAAO,CAAC;CACrB,GAAG,qBAAqB,CA2CxB"}