@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/routines-project.js

@@ -1,17 +1,3 @@
-/**
- * Project routine discovery, source tracking, and user-layer sync.
- *
- * Project YAML under `<project>/.agents/routines/*.yml` never fires on its own
- * (a cloned repo must not auto-run agent prompts). A routine has exactly one
- * state — enabled or disabled — owned by this device's `meta.deviceRoutines`
- * list, never by the project YAML's own `enabled:` field. `agents routines
- * enable <name>` materialises the routine into `~/.agents/routines/` with
- * `source:` provenance (so the daemon, which loads only user + system layers,
- * can see it) and flips the device flag on — one action. `discoverProjectRoutines`
- * surfaces not-yet-materialised routines from the user's registered projects so
- * `list` shows them as disabled. `syncProjectRoutines` refreshes materialised
- * copies from their source YAML (also invoked on daemon SIGHUP).
- */
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -22,7 +8,6 @@ import { readJob, writeJob, deleteJob, listJobs, validateJob, } from './scheduli
 import { parseOwnerRepoFromRemote } from './registry.js';
 import { listProjectDefs, projectDirsAbs } from './projects.js';
 import { isSafeSegmentName } from './paths.js';
-/** Expand `~/…` and resolve to an absolute path. */
 export function expandProjectPath(p) {
     const trimmed = p.trim();
     if (trimmed.startsWith('~/') || trimmed === '~') {
@@ -30,7 +15,6 @@ export function expandProjectPath(p) {
     }
     return path.resolve(trimmed);
 }
-/** Store paths home-relative when under $HOME so they travel across machines. */
 export function displayProjectPath(abs) {
     const home = os.homedir();
     const resolved = path.resolve(abs);
@@ -41,14 +25,12 @@ export function displayProjectPath(abs) {
     }
     return resolved;
 }
-/** Resolve the project root (parent of `.agents/`) from a cwd, or null. */
 export function resolveProjectRoot(cwd = process.cwd()) {
     const agentsDir = getProjectAgentsDir(cwd);
     if (!agentsDir)
         return null;
     return path.dirname(agentsDir);
 }
-/** Git provenance for a project root (best-effort; never throws). */
 function readProjectGitSource(projectRoot) {
     const abs = expandProjectPath(projectRoot);
     const out = {};
@@ -62,7 +44,7 @@ function readProjectGitSource(projectRoot) {
         if (repo)
             out.repo = repo;
     }
-    catch { /* no origin */ }
+    catch { }
     try {
         out.branch = execFileSync('git', ['-C', abs, 'rev-parse', '--abbrev-ref', 'HEAD'], {
             encoding: 'utf-8',
@@ -70,9 +52,9 @@ function readProjectGitSource(projectRoot) {
             timeout: 5_000,
         }).trim();
         if (out.branch === 'HEAD')
-            delete out.branch; // detached
+            delete out.branch;
     }
-    catch { /* not a git repo */ }
+    catch { }
     try {
         out.commit = execFileSync('git', ['-C', abs, 'rev-parse', '--short', 'HEAD'], {
             encoding: 'utf-8',
@@ -80,10 +62,9 @@ function readProjectGitSource(projectRoot) {
             timeout: 5_000,
         }).trim();
     }
-    catch { /* ignore */ }
+    catch { }
     return out;
 }
-/** List project routine YAML files (name + absolute path). */
 export function listProjectRoutineFiles(projectRoot) {
     const routinesDir = getProjectRoutinesDir(expandProjectPath(projectRoot));
     if (!routinesDir || !fs.existsSync(routinesDir))
@@ -117,17 +98,6 @@ function readProjectJobFile(filePath) {
         return null;
     }
 }
-/**
- * Refresh one project's already-materialised routines from its source YAML.
- * - Overwrites user copies that already carry matching `source.projectPath`
- * - Never clobbers a hand-authored user routine (no source / different source)
- * - Removes user copies from this project whose YAML disappeared
- *
- * Sync NEVER touches the device enable flag: a routine's enabled/disabled state
- * is owned solely by `meta.deviceRoutines` (via `agents routines enable/disable`),
- * never by the project YAML's own `enabled:` field. That is what keeps a cloned
- * repo from auto-firing — refreshing a definition can never turn it on.
- */
 export function syncProjectRoutines(projectRoot) {
     ensureAgentsDir();
     const abs = expandProjectPath(projectRoot);
@@ -150,10 +120,6 @@ export function syncProjectRoutines(projectRoot) {
     const seenNames = new Set();
     for (const file of files) {
         seenNames.add(file.name);
-        // Refresh only routines the user already materialised from THIS project.
-        // A project file with no existing user-layer copy is "available, not
-        // enabled" — it surfaces via `discoverProjectRoutines` and is materialised
-        // by `agents routines enable <name>`, never auto-pulled by a refresh.
         const existing = readJob(file.name);
         if (!existing)
             continue;
@@ -174,18 +140,11 @@ export function syncProjectRoutines(projectRoot) {
             result.errors.push({ name: file.name, error: 'unreadable or invalid YAML' });
             continue;
         }
-        // Preserve user-layer devices pin when project YAML omits it (same overlay
-        // semantics as listJobs project discovery).
         if (job.devices === undefined && existing.devices && existing.devices.length > 0) {
             job.devices = existing.devices;
         }
-        // Carry the original creation stamp across. A sync rebuilds the config
-        // from the PROJECT yaml, which never carries `createdAt`, so without this
-        // every `agents routines sync` would re-stamp it to now — walking the
-        // overdue floor forward and hiding real missed fires for project routines.
         if (existing.createdAt)
             job.createdAt = existing.createdAt;
-        // Surface repo for list/display when project has a GitHub origin.
         if (git.repo && !job.repo)
             job.repo = git.repo;
         job.source = source;
@@ -196,8 +155,6 @@ export function syncProjectRoutines(projectRoot) {
             continue;
         }
         try {
-            // Refresh the definition only. Enablement lives in meta.deviceRoutines and
-            // is never derived from the project YAML here.
             writeJob(job);
             result.synced.push(file.name);
         }
@@ -205,7 +162,6 @@ export function syncProjectRoutines(projectRoot) {
             result.errors.push({ name: file.name, error: err.message });
         }
     }
-    // Drop user-layer copies from this project that no longer exist in project YAML.
     for (const job of listJobs()) {
         if (job.source?.kind !== 'project')
             continue;
@@ -218,7 +174,6 @@ export function syncProjectRoutines(projectRoot) {
     }
     return result;
 }
-/** Distinct project roots that already have at least one materialised routine. */
 export function materialisedProjectRoots() {
     const roots = new Set();
     for (const job of listJobs()) {
@@ -227,12 +182,6 @@ export function materialisedProjectRoots() {
     }
     return [...roots];
 }
-/**
- * Refresh every materialised project routine from its source YAML. The set of
- * roots is derived from what the user has already enabled/materialised (their
- * `source.projectPath`), not from any allowlist — enabling a routine is the only
- * thing that brings its project into the refresh set. Also runs on daemon SIGHUP.
- */
 export function syncAllProjectRoutines(opts = {}) {
     const roots = new Set(materialisedProjectRoots());
     for (const r of opts.extraRoots ?? [])
@@ -248,11 +197,6 @@ export function syncAllProjectRoutines(opts = {}) {
     }
     return { projects, missing };
 }
-/**
- * Absolute local checkout roots for every registered project, deduped. This is
- * the discovery universe for project routines: bounded to projects the user
- * registered (`agents projects`), never an arbitrary filesystem scan.
- */
 function registeredProjectRoots() {
     const roots = new Set();
     for (const def of listProjectDefs()) {
@@ -263,13 +207,6 @@ function registeredProjectRoots() {
     }
     return [...roots];
 }
-/**
- * Project routines from registered projects that are NOT already materialised
- * in the user layer. These surface in `agents routines list` as disabled rows so
- * the single enabled/disabled model is visible, and `enable <name>` resolves a
- * name against them. A routine whose name already exists as a user/system
- * routine is omitted (that materialised copy is the live one).
- */
 export function discoverProjectRoutines() {
     const materialisedNames = new Set(listJobs().map((j) => j.name));
     const out = [];
@@ -278,7 +215,7 @@ export function discoverProjectRoutines() {
         const files = listProjectRoutineFiles(root).filter((f) => !materialisedNames.has(f.name) && !seen.has(f.name));
         if (files.length === 0)
             continue;
-        const git = readProjectGitSource(root); // once per root, not per routine
+        const git = readProjectGitSource(root);
         for (const file of files) {
             const job = readProjectJobFile(file.path);
             if (!job)
@@ -294,17 +231,12 @@ export function discoverProjectRoutines() {
             };
             if (git.repo && !job.repo)
                 job.repo = git.repo;
-            job.enabled = false; // available, not enabled — never inferred from the repo YAML
+            job.enabled = false;
             out.push({ name: file.name, projectRoot: expandProjectPath(root), file: file.path, config: job });
         }
     }
     return out;
 }
-/**
- * Resolve a routine name to a project source for `enable <name>`: first the cwd
- * project, then registered projects. Returns null when the name matches no
- * project routine, or throws-by-return when it is ambiguous across projects.
- */
 export function findProjectRoutine(name, cwd = process.cwd()) {
     const cwdRoot = resolveProjectRoot(cwd);
     if (cwdRoot) {
@@ -329,12 +261,6 @@ export function findProjectRoutine(name, cwd = process.cwd()) {
         return { ambiguous: hits.map((h) => displayProjectPath(h.projectRoot)) };
     return hits[0];
 }
-/**
- * Materialise one project routine into the user layer WITHOUT enabling it. The
- * caller (`agents routines enable`) flips the device flag separately, so a
- * materialise can never by itself make a routine fire. Returns the written
- * config, or an error string.
- */
 export function materialiseProjectRoutine(projectRoot, name) {
     ensureAgentsDir();
     const abs = expandProjectPath(projectRoot);

package/dist/lib/rules/compile.d.ts

@@ -1,88 +1,22 @@
-/**
- * Rules file compilation -- resolving @-imports into a single flat file.
- *
- * Agents that do not natively resolve `@path/to/file` imports (Codex, Cursor)
- * need a pre-compiled rules file with all imports inlined. This module
- * handles that expansion for both user-scope (writes into version home) and
- * project-scope (writes into the workspace).
- */
 import type { AgentId } from '../types.js';
 import { type RulesLayer } from './compose.js';
-/**
- * Header the non-@-import compile path (`agents refresh-rules` → compileRulesForAgent)
- * prepends to a compiled instruction file. Exported so `doctor-diff` can strip it
- * before content-comparing a home rules file against the raw preset composition —
- * a header-compiled home must still reconcile (the header is not source content).
- */
 export declare const COMPILED_HEADER: string;
 export declare const COMPILED_HEADER_PROJECT: string;
-/** Result of resolving @-imports in a rules file. */
 interface ResolveResult {
-    /** Fully-inlined content. */
     content: string;
-    /** Absolute paths of every file read during resolution (including the root). */
     sources: string[];
 }
-/**
- * Expand all `@path/to/file` imports in `content`, recursively up to
- * MAX_DEPTH. Imports inside fenced code blocks and inline code spans are
- * left alone, matching Claude Code's parser. Missing files are left as-is
- * (silent skip), matching the documented behavior.
- *
- * Relative paths resolve against `baseDir`; absolute and tilde-prefixed
- * paths resolve against the filesystem root / home directory.
- */
 export declare function resolveImports(content: string, baseDir: string): ResolveResult;
-/** True if the agent's native runtime resolves `@path` imports in its rules file. */
 export declare function supportsRulesImports(agentId: AgentId): boolean;
-/**
- * Fast staleness check. Returns true when:
- *  - the compiled file or its manifest is missing
- *  - any recorded source file is missing
- *  - any recorded source's sha256 no longer matches
- *
- * For agents that support @-imports natively, always returns false — there's
- * nothing to compile.
- */
 export declare function isRulesStale(agentId: AgentId, version: string): boolean;
-/**
- * Recompile rules if stale. Safe to call on every agent invocation — the
- * staleness check is fast (sha256 of 8-10 small files, ~10-20ms). Returns
- * true if a recompile happened, false otherwise.
- */
 export declare function ensureRulesFresh(agentId: AgentId, version: string): boolean;
 interface ProjectCompileResult {
-    /** True when cwd/AGENTS.md was newly written or rewritten. */
     compiled: boolean;
-    /** Absolute path to cwd/AGENTS.md. Empty when no project rules dir was present. */
     agentsPath: string;
-    /** Per-agent instruction filenames symlinked (or copied) to AGENTS.md. */
     symlinks: string[];
-    /** Number of source files inlined (root + recursive @-imports). */
     sources: number;
-    /** Per-agent files we left alone because the user wrote/owns them. */
     skippedClobber: string[];
 }
-/**
- * Compile project-scope rules into a workspace's root memory files so each
- * agent's native loader picks them up.
- *
- * Composes rules from all available layers (project > user > extras > system)
- * with project highest priority — so a project's `subrules/` and `rules.yaml`
- * shadow user/system fragments and presets. Writes `cwd/AGENTS.md` with
- * COMPILED_HEADER_PROJECT and creates symlinks (CLAUDE.md, GEMINI.md,
- * .cursorrules, etc.) → AGENTS.md so every agent finds its expected file at
- * cwd. The agent's own loader merges this project-level file with its
- * user-level rules (in version home) at runtime.
- *
- * Don't-clobber guard: if `cwd/AGENTS.md` exists without our header, the user
- * authored it — leave it alone and report via `skippedClobber`. Same for any
- * pre-existing per-agent file or symlink that doesn't already point at
- * AGENTS.md.
- *
- * No-op when `cwd/.agents/rules/` does not exist. Idempotent on repeated
- * calls — content equality short-circuits the write.
- */
 export declare function compileRulesForProject(cwd: string, opts?: {
     preset?: string;
     layers?: RulesLayer[];

package/dist/lib/rules/compile.js

@@ -1,11 +1,3 @@
-/**
- * Rules file compilation -- resolving @-imports into a single flat file.
- *
- * Agents that do not natively resolve `@path/to/file` imports (Codex, Cursor)
- * need a pre-compiled rules file with all imports inlined. This module
- * handles that expansion for both user-scope (writes into version home) and
- * project-scope (writes into the workspace).
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
@@ -13,17 +5,8 @@ import * as crypto from 'crypto';
 import { AGENTS, agentConfigDirName } from '../agents.js';
 import { getVersionsDir, isReservedAgentsDir } from '../state.js';
 import { composeRules, composeRulesFromState } from './compose.js';
-// Match `@path` preceded by start-of-string or whitespace. This avoids
-// matching emails ("foo@bar.com") and the middle of words. The leading
-// whitespace (if any) is captured so we can preserve it in the output.
 const IMPORT_RE = /(^|\s)@(\S+)/g;
 const MAX_DEPTH = 5;
-/**
- * Header the non-@-import compile path (`agents refresh-rules` → compileRulesForAgent)
- * prepends to a compiled instruction file. Exported so `doctor-diff` can strip it
- * before content-comparing a home rules file against the raw preset composition —
- * a header-compiled home must still reconcile (the header is not source content).
- */
 export const COMPILED_HEADER = '<!-- Auto-compiled by agents-cli from ~/.agents/rules/AGENTS.md + imports.\n' +
     '     Edit the source files under ~/.agents/rules/ — edits to this file will be overwritten on next sync. -->\n\n';
 export const COMPILED_HEADER_PROJECT = '<!-- Auto-compiled by agents-cli from .agents/rules/AGENTS.md + imports.\n' +
@@ -38,11 +21,6 @@ function expandTilde(p) {
 function sha256(content) {
     return crypto.createHash('sha256').update(content).digest('hex');
 }
-/**
- * Replace fenced code blocks (```...```) and inline code spans (`...`) with
- * placeholders. Claude Code's @-import parser ignores these regions, so we
- * must too.
- */
 function protectCodeRegions(content) {
     const fences = [];
     let withFences = content.replace(/```[\s\S]*?```/g, (match) => {
@@ -61,15 +39,6 @@ function restoreCodeRegions(content, fences, inlines) {
     restored = restored.replace(/\x00FENCE_(\d+)\x00/g, (_, i) => fences[Number(i)]);
     return restored;
 }
-/**
- * Expand all `@path/to/file` imports in `content`, recursively up to
- * MAX_DEPTH. Imports inside fenced code blocks and inline code spans are
- * left alone, matching Claude Code's parser. Missing files are left as-is
- * (silent skip), matching the documented behavior.
- *
- * Relative paths resolve against `baseDir`; absolute and tilde-prefixed
- * paths resolve against the filesystem root / home directory.
- */
 export function resolveImports(content, baseDir) {
     const sources = [];
     const seen = new Set();
@@ -83,9 +52,9 @@ export function resolveImports(content, baseDir) {
                 ? tildeExpanded
                 : path.resolve(currentDir, tildeExpanded);
             if (seen.has(resolved))
-                return lead; // cycle break — keep leading whitespace
+                return lead;
             if (!fs.existsSync(resolved))
-                return match; // preserve literal including lead
+                return match;
             seen.add(resolved);
             sources.push(resolved);
             const body = fs.readFileSync(resolved, 'utf8');
@@ -96,7 +65,6 @@ export function resolveImports(content, baseDir) {
     const result = expand(content, baseDir, 0);
     return { content: result, sources };
 }
-/** True if the agent's native runtime resolves `@path` imports in its rules file. */
 export function supportsRulesImports(agentId) {
     return !!AGENTS[agentId].capabilities.rulesImports;
 }
@@ -108,15 +76,6 @@ function getCompiledRulesPath(agentId, version) {
 function getManifestPath(compiledPath) {
     return compiledPath + '.manifest.json';
 }
-/**
- * Fast staleness check. Returns true when:
- *  - the compiled file or its manifest is missing
- *  - any recorded source file is missing
- *  - any recorded source's sha256 no longer matches
- *
- * For agents that support @-imports natively, always returns false — there's
- * nothing to compile.
- */
 export function isRulesStale(agentId, version) {
     if (supportsRulesImports(agentId))
         return false;
@@ -129,13 +88,11 @@ export function isRulesStale(agentId, version) {
         for (const src of manifest.sources) {
             if (!fs.existsSync(src.path))
                 return true;
-            // Tier 1: mtime+size fast path (no file read needed)
             if (src.mtime !== undefined && src.size !== undefined) {
                 const stat = fs.statSync(src.path);
                 if (stat.mtimeMs === src.mtime && stat.size === src.size)
                     continue;
             }
-            // Tier 2: content hash
             if (sha256(fs.readFileSync(src.path, 'utf8')) !== src.sha256)
                 return true;
         }
@@ -145,33 +102,15 @@ export function isRulesStale(agentId, version) {
         return true;
     }
 }
-/**
- * Resolve the source `rules/AGENTS.md` (with all @-imports expanded) and
- * write the result into the version home, alongside a sidecar manifest that
- * records source file hashes for staleness detection.
- *
- * Agents that natively resolve @-imports are skipped (no-op) — their sync
- * uses the standard copyFileSync path in `syncResourcesToVersion`.
- */
 function compileRulesForAgent(agentId, version) {
     if (supportsRulesImports(agentId)) {
         return { compiled: false, compiledPath: '', sources: 0 };
     }
-    // Route through the layered composer (project > user > extras > system).
-    // The previous implementation read only `<systemRules>/AGENTS.md` and
-    // inlined its @-imports — that dropped user/extras/project subrules
-    // entirely for @-import-incapable agents (Cursor, older Codex), so
-    // updates to ~/.agents/rules/subrules/ never reached the version home.
-    // composeRulesFromState already returns the concatenated content with
-    // every fragment resolved across layers; we just need to record the
-    // composed source list for staleness detection.
     let composed;
     try {
         composed = composeRulesFromState({ preset: undefined });
     }
     catch {
-        // No rules.yaml in any layer, or the default preset is missing — leave
-        // the version home untouched (matches the previous file-missing branch).
         return { compiled: false, compiledPath: '', sources: 0 };
     }
     const newContent = COMPILED_HEADER + composed.content;
@@ -182,8 +121,6 @@ function compileRulesForAgent(agentId, version) {
         return { compiled: false, compiledPath, sources: 0 };
     }
     fs.writeFileSync(compiledPath, newContent);
-    // Track every concrete subrule file the composer included as a source for
-    // staleness. composeRulesFromState exposes sourcePath on each ComposedSubrule.
     const allSources = composed.subrules.map(s => s.sourcePath);
     const manifest = {
         compiledAt: new Date().toISOString(),
@@ -196,11 +133,6 @@ function compileRulesForAgent(agentId, version) {
     fs.writeFileSync(getManifestPath(compiledPath), JSON.stringify(manifest, null, 2));
     return { compiled: true, compiledPath, sources: allSources.length };
 }
-/**
- * Recompile rules if stale. Safe to call on every agent invocation — the
- * staleness check is fast (sha256 of 8-10 small files, ~10-20ms). Returns
- * true if a recompile happened, false otherwise.
- */
 export function ensureRulesFresh(agentId, version) {
     if (supportsRulesImports(agentId))
         return false;
@@ -209,26 +141,6 @@ export function ensureRulesFresh(agentId, version) {
     const result = compileRulesForAgent(agentId, version);
     return result.compiled;
 }
-/**
- * Compile project-scope rules into a workspace's root memory files so each
- * agent's native loader picks them up.
- *
- * Composes rules from all available layers (project > user > extras > system)
- * with project highest priority — so a project's `subrules/` and `rules.yaml`
- * shadow user/system fragments and presets. Writes `cwd/AGENTS.md` with
- * COMPILED_HEADER_PROJECT and creates symlinks (CLAUDE.md, GEMINI.md,
- * .cursorrules, etc.) → AGENTS.md so every agent finds its expected file at
- * cwd. The agent's own loader merges this project-level file with its
- * user-level rules (in version home) at runtime.
- *
- * Don't-clobber guard: if `cwd/AGENTS.md` exists without our header, the user
- * authored it — leave it alone and report via `skippedClobber`. Same for any
- * pre-existing per-agent file or symlink that doesn't already point at
- * AGENTS.md.
- *
- * No-op when `cwd/.agents/rules/` does not exist. Idempotent on repeated
- * calls — content equality short-circuits the write.
- */
 export function compileRulesForProject(cwd, opts = {}) {
     const projectRulesDir = path.join(cwd, '.agents', 'rules');
     const empty = {
@@ -236,26 +148,16 @@ export function compileRulesForProject(cwd, opts = {}) {
     };
     if (!fs.existsSync(projectRulesDir))
         return empty;
-    // The user layer's own home satisfies the rules-dir test — ~/.agents/rules
-    // exists on every configured machine — which compiled $HOME as a "project",
-    // wrote ~/AGENTS.md (+ per-agent symlinks), and injected the whole ruleset
-    // into every session twice: once as global memory, once as "project" memory
-    // (RUSH-2725). Reserved roots (user layer, system layer, or a checkout of
-    // either canonical DotAgents repo) never compile as a project.
     if (isReservedAgentsDir(path.join(cwd, '.agents')))
         return empty;
     let composed;
     try {
-        // Tests inject `layers` to isolate from real ~/.agents-system / ~/.agents
-        // state. Production callers omit it and compose from discovered state.
         const result = opts.layers
             ? composeRules({ preset: opts.preset, layers: opts.layers })
             : composeRulesFromState({ cwd, preset: opts.preset });
         composed = { content: result.content, subrules: result.subrules };
     }
     catch {
-        // Composer threw (no preset, malformed yaml). Don't write a half-baked
-        // file — bail out cleanly, same as if the rules dir didn't exist.
         return empty;
     }
     const newContent = COMPILED_HEADER_PROJECT + composed.content;
@@ -267,7 +169,7 @@ export function compileRulesForProject(cwd, opts = {}) {
     try {
         agentsLstat = fs.lstatSync(agentsPath);
     }
-    catch { /* missing */ }
+    catch { }
     if (!agentsLstat) {
         fs.writeFileSync(agentsPath, newContent);
         compiled = true;
@@ -278,7 +180,7 @@ export function compileRulesForProject(cwd, opts = {}) {
         try {
             existing = fs.readFileSync(agentsPath, 'utf8');
         }
-        catch { /* unreadable */ }
+        catch { }
         if (existing.startsWith(COMPILED_HEADER_PROJECT)) {
             if (existing !== newContent) {
                 fs.writeFileSync(agentsPath, newContent);
@@ -291,11 +193,8 @@ export function compileRulesForProject(cwd, opts = {}) {
         }
     }
     else {
-        // Symlink or other non-regular file — treat as user-owned, do not clobber
         skippedClobber.push('AGENTS.md');
     }
-    // Per-agent symlinks. Only attempt when we own AGENTS.md — never create a
-    // dangling symlink to a file we couldn't write.
     const symlinks = [];
     if (weOwnAgentsMd) {
         const seen = new Set(['AGENTS.md']);
@@ -303,14 +202,8 @@ export function compileRulesForProject(cwd, opts = {}) {
             const fname = agent.instructionsFile;
             if (seen.has(fname))
                 continue;
-            // Hard-deprecated agents (e.g. Gemini, retired by Google) never get an
-            // instruction-file symlink — the harness is gone, so GEMINI.md would only
-            // litter the tree. Mirrors the deprecated?.hard skip used everywhere else
-            // (capabilities.ts, MANAGED_AGENT_IDS, modes.ts).
             if (agent.deprecated?.hard)
                 continue;
-            // Skip agents whose instructions live at a nested path (e.g. OpenClaw's
-            // workspace/AGENTS.md) — those are managed by their own setup paths.
             if (fname.includes('/') || fname.includes('\\'))
                 continue;
             seen.add(fname);
@@ -319,14 +212,14 @@ export function compileRulesForProject(cwd, opts = {}) {
             try {
                 lstat = fs.lstatSync(linkPath);
             }
-            catch { /* missing */ }
+            catch { }
             if (lstat) {
                 if (lstat.isSymbolicLink()) {
                     let target = '';
                     try {
                         target = fs.readlinkSync(linkPath);
                     }
-                    catch { /* unreadable */ }
+                    catch { }
                     if (target === 'AGENTS.md') {
                         symlinks.push(fname);
                         continue;
@@ -334,7 +227,6 @@ export function compileRulesForProject(cwd, opts = {}) {
                     skippedClobber.push(fname);
                     continue;
                 }
-                // Regular file — user authored
                 skippedClobber.push(fname);
                 continue;
             }
@@ -343,15 +235,11 @@ export function compileRulesForProject(cwd, opts = {}) {
                 symlinks.push(fname);
             }
             catch {
-                // Filesystems that disallow symlinks (some Windows configs) — fall
-                // back to a copy. The agent reads the same content either way.
                 try {
                     fs.copyFileSync(agentsPath, linkPath);
                     symlinks.push(fname);
                 }
                 catch {
-                    // Give up on this one quietly; the agent that needs this filename
-                    // will fall back to its own discovery rules.
                 }
             }
         }