@intellectronica/ruler 0.3.42 → 0.3.44

package/dist/constants.d.ts

@@ -15,7 +15,7 @@ export declare function logVerboseInfo(message: string, isVerbose: boolean, dryR
 export declare const SKILLS_DIR = "skills";
 export declare const RULER_SKILLS_PATH = ".ruler/skills";
 export declare const CLAUDE_SKILLS_PATH = ".claude/skills";
-export declare const CODEX_SKILLS_PATH = ".codex/skills";
+export declare const CODEX_SKILLS_PATH = ".agents/skills";
 export declare const OPENCODE_SKILLS_PATH = ".opencode/skills";
 export declare const PI_SKILLS_PATH = ".pi/skills";
 export declare const GOOSE_SKILLS_PATH = ".agents/skills";

package/dist/constants.js

@@ -53,7 +53,7 @@ function logVerboseInfo(message, isVerbose, dryRun = false) {
 exports.SKILLS_DIR = 'skills';
 exports.RULER_SKILLS_PATH = '.ruler/skills';
 exports.CLAUDE_SKILLS_PATH = '.claude/skills';
-exports.CODEX_SKILLS_PATH = '.codex/skills';
+exports.CODEX_SKILLS_PATH = '.agents/skills';
 exports.OPENCODE_SKILLS_PATH = '.opencode/skills';
 exports.PI_SKILLS_PATH = '.pi/skills';
 exports.GOOSE_SKILLS_PATH = '.agents/skills';

package/dist/core/ConfigLoader.d.ts

@@ -11,6 +11,8 @@ export interface IAgentConfig {
     outputPathConfig?: string;
     /** MCP propagation config for this agent. */
     mcp?: McpConfig;
+    /** Agent-scoped MCP server definitions. */
+    mcpServers?: Record<string, Record<string, unknown>>;
 }
 /**
  * Parsed ruler configuration values.

package/dist/core/ConfigLoader.js

@@ -40,6 +40,7 @@ const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const toml_1 = require("@iarna/toml");
 const zod_1 = require("zod");
+const path_utils_1 = require("./path-utils");
 const constants_1 = require("../constants");
 // One-shot guard so the deprecation message fires once per process even when
 // `loadConfig` is called multiple times (e.g. nested mode walks every
@@ -61,6 +62,7 @@ const mcpConfigSchema = zod_1.z
     enabled: zod_1.z.boolean().optional(),
     merge_strategy: zod_1.z.enum(['merge', 'overwrite']).optional(),
 })
+    .strict()
     .optional();
 const agentConfigSchema = zod_1.z
     .object({
@@ -69,7 +71,11 @@ const agentConfigSchema = zod_1.z
     output_path_instructions: zod_1.z.string().optional(),
     output_path_config: zod_1.z.string().optional(),
     mcp: mcpConfigSchema,
+    mcp_servers: zod_1.z
+        .record(zod_1.z.string(), zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()))
+        .optional(),
 })
+    .strict()
     .optional();
 // `[agents]` is a heterogeneous table that holds two unrelated kinds of keys:
 //   - reserved subagent-control booleans (`enabled`, `include_in_rules`)
@@ -81,7 +87,8 @@ const SUBAGENT_RESERVED_KEYS = new Set([
     'include_in_rules',
     'cleanup_orphaned',
 ]);
-const rulerConfigSchema = zod_1.z.object({
+const rulerConfigSchema = zod_1.z
+    .object({
     default_agents: zod_1.z.array(zod_1.z.string()).optional(),
     agents: zod_1.z
         .object({
@@ -96,22 +103,29 @@ const rulerConfigSchema = zod_1.z.object({
         enabled: zod_1.z.boolean().optional(),
         merge_strategy: zod_1.z.enum(['merge', 'overwrite']).optional(),
     })
+        .strict()
+        .optional(),
+    mcp_servers: zod_1.z
+        .record(zod_1.z.string(), zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()))
         .optional(),
     gitignore: zod_1.z
         .object({
         enabled: zod_1.z.boolean().optional(),
         local: zod_1.z.boolean().optional(),
     })
+        .strict()
         .optional(),
     backup: zod_1.z
         .object({
         enabled: zod_1.z.boolean().optional(),
     })
+        .strict()
         .optional(),
     skills: zod_1.z
         .object({
         enabled: zod_1.z.boolean().optional(),
     })
+        .strict()
         .optional(),
     // Deprecated: kept in the schema only so that legacy `[subagents]` blocks
     // are preserved through validation. The parser reads from here as a
@@ -123,9 +137,11 @@ const rulerConfigSchema = zod_1.z.object({
         include_in_rules: zod_1.z.boolean().optional(),
         cleanup_orphaned: zod_1.z.boolean().optional(),
     })
+        .strict()
         .optional(),
     nested: zod_1.z.boolean().optional(),
-});
+})
+    .strict();
 /**
  * Recursively creates a new object with only enumerable string keys,
  * effectively excluding Symbol properties.
@@ -147,6 +163,46 @@ function stripSymbols(obj) {
     }
     return result;
 }
+function parseAgentMcpServers(sectionObj) {
+    if (!sectionObj.mcp_servers ||
+        typeof sectionObj.mcp_servers !== 'object' ||
+        Array.isArray(sectionObj.mcp_servers)) {
+        return undefined;
+    }
+    const servers = {};
+    for (const [name, def] of Object.entries(sectionObj.mcp_servers)) {
+        if (def && typeof def === 'object' && !Array.isArray(def)) {
+            const server = normalizeAgentMcpServer(def);
+            if (server.command || server.url) {
+                servers[name] = server;
+            }
+        }
+    }
+    return Object.keys(servers).length > 0 ? servers : undefined;
+}
+function normalizeAgentMcpServer(def) {
+    const server = { ...def };
+    const hasCommand = typeof server.command === 'string';
+    const hasUrl = typeof server.url === 'string';
+    if (!hasCommand) {
+        delete server.command;
+        delete server.args;
+        delete server.env;
+    }
+    if (!hasUrl) {
+        delete server.url;
+        delete server.headers;
+        delete server.auth;
+        delete server.oauth;
+    }
+    if (hasCommand && hasUrl) {
+        delete server.command;
+        delete server.args;
+        delete server.env;
+        server.type = 'remote';
+    }
+    return server;
+}
 /**
  * Loads and parses the ruler TOML configuration file, applying defaults.
  * Missing implicit configs return defaults. Explicit configs and existing
@@ -179,13 +235,13 @@ async function loadConfig(options) {
                 cfg.enabled = sectionObj.enabled;
             }
             if (typeof sectionObj.output_path === 'string') {
-                cfg.outputPath = path.resolve(projectRoot, sectionObj.output_path);
+                cfg.outputPath = resolveProjectOutputPath(projectRoot, sectionObj.output_path, configFile, `[agents.${name}].output_path`);
             }
             if (typeof sectionObj.output_path_instructions === 'string') {
-                cfg.outputPathInstructions = path.resolve(projectRoot, sectionObj.output_path_instructions);
+                cfg.outputPathInstructions = resolveProjectOutputPath(projectRoot, sectionObj.output_path_instructions, configFile, `[agents.${name}].output_path_instructions`);
             }
             if (typeof sectionObj.output_path_config === 'string') {
-                cfg.outputPathConfig = path.resolve(projectRoot, sectionObj.output_path_config);
+                cfg.outputPathConfig = resolveProjectOutputPath(projectRoot, sectionObj.output_path_config, configFile, `[agents.${name}].output_path_config`);
             }
             if (sectionObj.mcp && typeof sectionObj.mcp === 'object') {
                 const m = sectionObj.mcp;
@@ -201,6 +257,7 @@ async function loadConfig(options) {
                 }
                 cfg.mcp = mcpCfg;
             }
+            cfg.mcpServers = parseAgentMcpServers(sectionObj);
             agentConfigs[name] = cfg;
         }
     }
@@ -301,6 +358,20 @@ async function loadConfig(options) {
         nestedDefined,
     };
 }
+function resolveProjectOutputPath(projectRoot, configuredPath, configFile, fieldName) {
+    const resolvedPath = path.resolve(projectRoot, configuredPath);
+    if (!(0, path_utils_1.isPathInsideOrEqual)(projectRoot, resolvedPath)) {
+        throw (0, constants_1.createRulerError)('Configured output path is outside the project root', [
+            configFile ? `File: ${configFile}` : undefined,
+            `Field: ${fieldName}`,
+            `Path: ${configuredPath}`,
+            `Project root: ${projectRoot}`,
+        ]
+            .filter(Boolean)
+            .join(', '));
+    }
+    return resolvedPath;
+}
 async function resolveImplicitConfigFile(projectRoot, checkGlobal) {
     const localRulerDir = await findNearestLocalRulerDir(projectRoot);
     const localConfigFile = localRulerDir
@@ -381,8 +452,18 @@ function parseConfigText(text, configFile) {
 function validateConfig(raw, configFile) {
     const validationResult = rulerConfigSchema.safeParse(raw);
     if (!validationResult.success) {
-        throw (0, constants_1.createRulerError)('Invalid configuration file format', `File: ${configFile}, Errors: ${validationResult.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join(', ')}`);
+        throw (0, constants_1.createRulerError)('Invalid configuration file format', `File: ${configFile}, Errors: ${validationResult.error.issues.map(formatZodIssue).join(', ')}`);
+    }
+}
+function formatZodIssue(issue) {
+    const basePath = issue.path.join('.');
+    if (issue.code === 'unrecognized_keys') {
+        const keys = issue.keys;
+        return keys
+            .map((key) => (basePath ? `${basePath}.${key}` : key))
+            .join(', ');
     }
+    return `${basePath}: ${issue.message}`;
 }
 function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);

package/dist/core/FileSystemUtils.d.ts

@@ -1,9 +1,12 @@
+export declare function assertNotSymbolicLink(filePath: string, action: string): Promise<void>;
+export declare function assertManagedPathInsideRoot(managedPath: string, rootPath: string, action: string): Promise<void>;
 /**
  * Searches upwards from startPath to find a directory named .ruler.
  * If not found locally and checkGlobal is true, checks for global config at XDG_CONFIG_HOME/ruler.
  * Returns the path to the .ruler directory, or null if not found.
  */
 export declare function findRulerDir(startPath: string, checkGlobal?: boolean): Promise<string | null>;
+export declare function resolveProjectRootForRulerDir(requestedProjectRoot: string, rulerDir: string): string;
 /**
  * Options for {@link readMarkdownFiles}.
  */
@@ -29,12 +32,12 @@ export declare function readMarkdownFiles(rulerDir: string, options?: ReadMarkdo
 /**
  * Writes content to filePath, creating parent directories if necessary.
  */
-export declare function writeGeneratedFile(filePath: string, content: string): Promise<void>;
+export declare function writeGeneratedFile(filePath: string, content: string, containmentRoot?: string): Promise<void>;
 /**
  * Creates a backup of the given filePath by copying it to filePath.bak if it exists.
  * Keeps an existing backup intact so repeated applies preserve the original file.
  */
-export declare function backupFile(filePath: string): Promise<void>;
+export declare function backupFile(filePath: string, containmentRoot?: string): Promise<void>;
 /**
  * Ensures that the given directory exists by creating it recursively.
  */

package/dist/core/FileSystemUtils.js

@@ -33,7 +33,10 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertNotSymbolicLink = assertNotSymbolicLink;
+exports.assertManagedPathInsideRoot = assertManagedPathInsideRoot;
 exports.findRulerDir = findRulerDir;
+exports.resolveProjectRootForRulerDir = resolveProjectRootForRulerDir;
 exports.readMarkdownFiles = readMarkdownFiles;
 exports.writeGeneratedFile = writeGeneratedFile;
 exports.backupFile = backupFile;
@@ -44,7 +47,9 @@ const fs_1 = require("fs");
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const constants_1 = require("../constants");
+const path_utils_1 = require("./path-utils");
 const SUBAGENTS_DIR_NAME = path.basename(constants_1.RULER_SUBAGENTS_PATH);
+const RULER_GENERATED_MARKER = '<!-- Generated by Ruler -->';
 const DEFAULT_NESTED_DISCOVERY_IGNORES = new Set([
     '__fixtures__',
     '__generated__',
@@ -66,6 +71,66 @@ function getXdgConfigDir() {
 function shouldSkipNestedDiscoveryDir(dirName) {
     return (dirName.startsWith('.') || DEFAULT_NESTED_DISCOVERY_IGNORES.has(dirName));
 }
+async function isSymbolicLink(filePath) {
+    try {
+        return (await fs_1.promises.lstat(filePath)).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+async function assertNotSymbolicLink(filePath, action) {
+    if (await isSymbolicLink(filePath)) {
+        throw new Error(`${action}: ${filePath}`);
+    }
+}
+async function assertContainingDirectoryInsideRoot(filePath, rootPath, action) {
+    const realRoot = await fs_1.promises.realpath(rootPath);
+    let current = path.dirname(path.resolve(filePath));
+    while (true) {
+        try {
+            const realCurrent = await fs_1.promises.realpath(current);
+            if (!(0, path_utils_1.isPathInsideOrEqual)(realRoot, realCurrent)) {
+                throw new Error(`${action}: ${filePath}`);
+            }
+            return;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return;
+        }
+        current = parent;
+    }
+}
+async function assertManagedPathInsideRoot(managedPath, rootPath, action) {
+    const realRoot = await fs_1.promises.realpath(rootPath);
+    await assertContainingDirectoryInsideRoot(managedPath, rootPath, action);
+    try {
+        const realManagedPath = await fs_1.promises.realpath(managedPath);
+        if (!(0, path_utils_1.isPathInsideOrEqual)(realRoot, realManagedPath)) {
+            throw new Error(`${action}: ${managedPath}`);
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+}
+async function isRulerGeneratedFile(filePath) {
+    try {
+        const content = await fs_1.promises.readFile(filePath, 'utf8');
+        return content.startsWith(RULER_GENERATED_MARKER);
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Searches upwards from startPath to find a directory named .ruler.
  * If not found locally and checkGlobal is true, checks for global config at XDG_CONFIG_HOME/ruler.
@@ -101,11 +166,19 @@ async function findRulerDir(startPath, checkGlobal = true) {
             }
         }
         catch (err) {
+            if (err.code === 'ENOENT') {
+                return null;
+            }
             console.error(`[ruler] Error checking global config directory ${globalConfigDir}:`, err);
         }
     }
     return null;
 }
+function resolveProjectRootForRulerDir(requestedProjectRoot, rulerDir) {
+    return path.basename(rulerDir) === '.ruler'
+        ? path.dirname(rulerDir)
+        : requestedProjectRoot;
+}
 /**
  * Recursively reads all Markdown (.md) files in rulerDir, returning their paths and contents.
  * Files are sorted alphabetically by path.
@@ -116,6 +189,8 @@ async function findRulerDir(startPath, checkGlobal = true) {
 async function readMarkdownFiles(rulerDir, options = {}) {
     const mdFiles = [];
     const includeAgents = options.includeAgents === true;
+    const realRulerDir = await fs_1.promises.realpath(rulerDir);
+    const visitedDirectories = new Set();
     // Tracks whether we skipped a `.ruler/agents` subtree so the root-AGENTS.md
     // fallback below still recognises ruler content as present and does not
     // resurrect a previously generated root AGENTS.md (which may itself contain
@@ -123,6 +198,17 @@ async function readMarkdownFiles(rulerDir, options = {}) {
     let sawExcludedAgents = false;
     // Gather all markdown files (recursive) first
     async function walk(dir) {
+        let realDir;
+        try {
+            realDir = await fs_1.promises.realpath(dir);
+        }
+        catch {
+            return;
+        }
+        if (visitedDirectories.has(realDir)) {
+            return;
+        }
+        visitedDirectories.add(realDir);
         const entries = await fs_1.promises.readdir(dir, { withFileTypes: true });
         for (const entry of entries) {
             const fullPath = path.join(dir, entry.name);
@@ -131,6 +217,10 @@ async function readMarkdownFiles(rulerDir, options = {}) {
             let isFile = entry.isFile();
             if (entry.isSymbolicLink()) {
                 try {
+                    const realTarget = await fs_1.promises.realpath(fullPath);
+                    if (!(0, path_utils_1.isPathInsideOrEqual)(realRulerDir, realTarget)) {
+                        continue;
+                    }
                     const stat = await fs_1.promises.stat(fullPath);
                     isDir = stat.isDirectory();
                     isFile = stat.isFile();
@@ -201,7 +291,19 @@ async function readMarkdownFiles(rulerDir, options = {}) {
         const repoRoot = path.dirname(rulerDir); // .ruler parent
         const rootAgentsPath = path.join(repoRoot, 'AGENTS.md');
         if (path.resolve(rootAgentsPath) !== path.resolve(topLevelAgents)) {
-            const stat = await fs_1.promises.stat(rootAgentsPath);
+            const rootAgentsStat = await fs_1.promises.lstat(rootAgentsPath);
+            if (rootAgentsStat.isSymbolicLink()) {
+                const [realRepoRoot, realRootAgentsPath] = await Promise.all([
+                    fs_1.promises.realpath(repoRoot),
+                    fs_1.promises.realpath(rootAgentsPath),
+                ]);
+                if (!(0, path_utils_1.isPathInsideOrEqual)(realRepoRoot, realRootAgentsPath)) {
+                    return ordered;
+                }
+            }
+            const stat = rootAgentsStat.isSymbolicLink()
+                ? await fs_1.promises.stat(rootAgentsPath)
+                : rootAgentsStat;
             if (stat.isFile()) {
                 const content = await fs_1.promises.readFile(rootAgentsPath, 'utf8');
                 // Check if this is a generated file and we have other .ruler files.
@@ -231,16 +333,29 @@ async function readMarkdownFiles(rulerDir, options = {}) {
 /**
  * Writes content to filePath, creating parent directories if necessary.
  */
-async function writeGeneratedFile(filePath, content) {
+async function writeGeneratedFile(filePath, content, containmentRoot) {
+    if (containmentRoot) {
+        await assertContainingDirectoryInsideRoot(filePath, containmentRoot, 'Refusing to write generated file through symlinked directory');
+    }
     await fs_1.promises.mkdir(path.dirname(filePath), { recursive: true });
+    await assertNotSymbolicLink(filePath, 'Refusing to write generated file through symlink');
+    if (containmentRoot) {
+        await assertContainingDirectoryInsideRoot(filePath, containmentRoot, 'Refusing to write generated file through symlinked directory');
+    }
     await fs_1.promises.writeFile(filePath, content, 'utf8');
 }
 /**
  * Creates a backup of the given filePath by copying it to filePath.bak if it exists.
  * Keeps an existing backup intact so repeated applies preserve the original file.
  */
-async function backupFile(filePath) {
+async function backupFile(filePath, containmentRoot) {
     const backupPath = `${filePath}.bak`;
+    if (containmentRoot) {
+        await assertManagedPathInsideRoot(filePath, containmentRoot, 'Refusing to back up generated file through symlinked directory');
+        await assertManagedPathInsideRoot(backupPath, containmentRoot, 'Refusing to create backup file through symlinked directory');
+    }
+    await assertNotSymbolicLink(filePath, 'Refusing to back up symlinked file');
+    await assertNotSymbolicLink(backupPath, 'Refusing to use symlinked backup file');
     try {
         await fs_1.promises.access(backupPath);
         return;
@@ -248,6 +363,9 @@ async function backupFile(filePath) {
     catch {
         // continue if no backup exists yet
     }
+    if (await isRulerGeneratedFile(filePath)) {
+        return;
+    }
     try {
         await fs_1.promises.copyFile(filePath, backupPath);
     }

package/dist/core/GitignoreUtils.d.ts

@@ -1,3 +1,11 @@
+export interface RulerBlockRange {
+    start: number;
+    end: number;
+}
+export interface RemoveRulerBlocksResult {
+    content: string;
+    removed: boolean;
+}
 /**
  * Updates an ignore file in the project root with paths in a managed Ruler block.
  * Creates the file if it doesn't exist, and creates or updates the Ruler-managed block.
@@ -13,3 +21,5 @@ export declare function updateGitignore(projectRoot: string, paths: string[], ig
  * through that pointer.
  */
 export declare function resolveIgnoreFilePath(projectRoot: string, ignoreFile: string): Promise<string>;
+export declare function findCompleteRulerBlocks(lines: string[]): RulerBlockRange[];
+export declare function removeCompleteRulerBlocks(content: string): RemoveRulerBlocksResult;

package/dist/core/GitignoreUtils.js

@@ -35,8 +35,11 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.updateGitignore = updateGitignore;
 exports.resolveIgnoreFilePath = resolveIgnoreFilePath;
+exports.findCompleteRulerBlocks = findCompleteRulerBlocks;
+exports.removeCompleteRulerBlocks = removeCompleteRulerBlocks;
 const fs_1 = require("fs");
 const path = __importStar(require("path"));
+const FileSystemUtils_1 = require("./FileSystemUtils");
 const RULER_START_MARKER = '# START Ruler Generated Files';
 const RULER_END_MARKER = '# END Ruler Generated Files';
 /**
@@ -99,8 +102,7 @@ async function updateGitignore(projectRoot, paths, ignoreFile = '.gitignore') {
     // Create new content
     const newContent = updateGitignoreContent(existingContent, allRulerPaths);
     // Write the updated content
-    await fs_1.promises.mkdir(path.dirname(gitignorePath), { recursive: true });
-    await fs_1.promises.writeFile(gitignorePath, newContent);
+    await (0, FileSystemUtils_1.writeGeneratedFile)(gitignorePath, newContent);
 }
 /**
  * Resolves ignore files Ruler manages. Linked worktrees store `.git` as a
@@ -137,56 +139,85 @@ async function resolveIgnoreFilePath(projectRoot, ignoreFile) {
  */
 function getExistingPathsExcludingRulerBlock(content) {
     const lines = content.split('\n');
+    const rulerBlocks = findCompleteRulerBlocks(lines);
     const paths = [];
-    let inRulerBlock = false;
-    for (const line of lines) {
-        const trimmed = line.trim();
-        if (trimmed === RULER_START_MARKER) {
-            inRulerBlock = true;
-            continue;
-        }
-        if (trimmed === RULER_END_MARKER) {
-            inRulerBlock = false;
+    for (const [index, line] of lines.entries()) {
+        if (rulerBlocks.some((block) => index >= block.start && index <= block.end)) {
             continue;
         }
-        if (!inRulerBlock && trimmed && !trimmed.startsWith('#')) {
+        const trimmed = line.trim();
+        if (trimmed && !trimmed.startsWith('#')) {
             paths.push(trimmed);
         }
     }
     return paths;
 }
+function findCompleteRulerBlocks(lines) {
+    const ranges = [];
+    for (let index = 0; index < lines.length; index++) {
+        if (lines[index].trim() !== RULER_START_MARKER) {
+            continue;
+        }
+        for (let endIndex = index + 1; endIndex < lines.length; endIndex++) {
+            const trimmed = lines[endIndex].trim();
+            if (trimmed === RULER_START_MARKER) {
+                break;
+            }
+            if (trimmed === RULER_END_MARKER) {
+                ranges.push({ start: index, end: endIndex });
+                index = endIndex;
+                break;
+            }
+        }
+    }
+    return ranges;
+}
+function removeCompleteRulerBlocks(content) {
+    const lines = content.split('\n');
+    const rulerBlocks = findCompleteRulerBlocks(lines);
+    if (rulerBlocks.length === 0) {
+        return { content, removed: false };
+    }
+    const retainedLines = [];
+    for (let index = 0; index < lines.length; index++) {
+        const block = rulerBlocks.find((range) => range.start === index);
+        if (block) {
+            index = block.end;
+            continue;
+        }
+        retainedLines.push(lines[index]);
+    }
+    return {
+        content: retainedLines.join('\n').replace(/\n{3,}/g, '\n\n'),
+        removed: true,
+    };
+}
 /**
  * Updates the .gitignore content by replacing or adding the Ruler block.
  */
 function updateGitignoreContent(existingContent, rulerPaths) {
     const lines = existingContent.split('\n');
+    const rulerBlocks = findCompleteRulerBlocks(lines);
     const newLines = [];
-    let inFirstRulerBlock = false;
-    let hasRulerBlock = false;
-    let processedFirstBlock = false;
-    for (const line of lines) {
-        const trimmed = line.trim();
-        if (trimmed === RULER_START_MARKER && !processedFirstBlock) {
-            inFirstRulerBlock = true;
-            hasRulerBlock = true;
-            newLines.push(line);
-            // Add the new Ruler paths
+    let replacedFirstBlock = false;
+    for (let index = 0; index < lines.length; index++) {
+        const block = rulerBlocks.find((range) => range.start === index);
+        if (block && !replacedFirstBlock) {
+            newLines.push(lines[block.start]);
             rulerPaths.forEach((p) => newLines.push(p));
+            newLines.push(lines[block.end]);
+            replacedFirstBlock = true;
+            index = block.end;
             continue;
         }
-        if (trimmed === RULER_END_MARKER && inFirstRulerBlock) {
-            inFirstRulerBlock = false;
-            processedFirstBlock = true;
-            newLines.push(line);
+        if (block) {
+            index = block.end;
             continue;
         }
-        if (!inFirstRulerBlock) {
-            newLines.push(line);
-        }
-        // Skip lines that are in the first Ruler block (they get replaced)
+        newLines.push(lines[index]);
     }
     // If no Ruler block exists, add one at the end
-    if (!hasRulerBlock) {
+    if (rulerBlocks.length === 0) {
         // Add blank line if content exists and doesn't end with blank line
         if (existingContent.trim() && !existingContent.endsWith('\n\n')) {
             newLines.push('');

package/dist/core/SkillsProcessor.d.ts

@@ -15,7 +15,7 @@ export declare function discoverSkills(projectRoot: string): Promise<{
  */
 export declare function getSkillsGitignorePaths(projectRoot: string, agents: IAgent[]): Promise<string[]>;
 type ReplaceSkillsFsOps = Pick<typeof fs, 'rename' | 'cp' | 'rm'>;
-export declare function replaceSkillsDirectory(tempDir: string, targetDir: string, fsOps?: ReplaceSkillsFsOps): Promise<void>;
+export declare function replaceSkillsDirectory(tempDir: string, targetDir: string, fsOps?: ReplaceSkillsFsOps, containmentRoot?: string): Promise<void>;
 /**
  * Propagates skills for agents that need them.
  */
@@ -29,7 +29,7 @@ export declare function propagateSkillsForClaude(projectRoot: string, options: {
     dryRun: boolean;
 }): Promise<string[]>;
 /**
- * Propagates skills for OpenAI Codex CLI by copying .ruler/skills to .codex/skills.
+ * Propagates skills for OpenAI Codex CLI by copying .ruler/skills to .agents/skills.
  * Uses atomic replace to ensure safe overwriting of existing skills.
  * Returns dry-run steps if dryRun is true, otherwise returns empty array.
  */