@lousy-agents/mcp 5.22.28 → 5.23.1

package/dist/mcp-server.js

@@ -6559,7 +6559,7 @@ function escapeJsonPtr(str) {
 
 
 },
-3904(__unused_rspack_module, __unused_rspack___webpack_exports__, __webpack_require__) {
+8066(__unused_rspack_module, __unused_rspack___webpack_exports__, __webpack_require__) {
 // NAMESPACE OBJECT: ../../node_modules/micromark/lib/constructs.js
 var constructs_namespaceObject = {};
 __webpack_require__.r(constructs_namespaceObject);
@@ -28463,8 +28463,32 @@ const EMPTY_COMPLETION_RESULT = {
     }
 };
 //# sourceMappingURL=mcp.js.map
-// EXTERNAL MODULE: external "node:fs/promises"
-var promises_ = __webpack_require__(1455);
+// EXTERNAL MODULE: external "node:fs"
+var external_node_fs_ = __webpack_require__(3024);
+;// CONCATENATED MODULE: ./src/package-version.ts
+/**
+ * Reads the version of the installed @lousy-agents/mcp package.
+ *
+ * The release process writes the published version into package.json after
+ * the build, so the version is read at runtime instead of being bundled.
+ * Both src/ (tests) and dist/ (published bundle) sit one level below the
+ * package root.
+ */ 
+
+const PackageManifestSchema = schemas_object({
+    version: schemas_string().min(1)
+});
+const UNKNOWN_VERSION = "0.0.0-unknown";
+const OWN_MANIFEST_URL = new URL("../package.json", import.meta.url);
+function readPackageVersion(manifestUrl = OWN_MANIFEST_URL) {
+    try {
+        const manifest = JSON.parse((0,external_node_fs_.readFileSync)(manifestUrl, "utf-8"));
+        return PackageManifestSchema.parse(manifest).version;
+    } catch  {
+        return UNKNOWN_VERSION;
+    }
+}
+
 // EXTERNAL MODULE: external "node:path"
 var external_node_path_ = __webpack_require__(6760);
 ;// CONCATENATED MODULE: ../core/src/gateways/action-version-gateway.ts
@@ -28510,6 +28534,8 @@ var external_node_path_ = __webpack_require__(6760);
  * List of known action names for convenience
  */ const KNOWN_ACTIONS = Object.keys(DEFAULT_ACTION_VERSIONS);
 
+// EXTERNAL MODULE: external "node:fs/promises"
+var promises_ = __webpack_require__(1455);
 ;// CONCATENATED MODULE: ../../node_modules/@openclaw/fs-safe/dist/errors.js
 const OPERATIONAL_CODE_VALUES = [
     "helper-failed",
@@ -28545,8 +28571,6 @@ function isNoReplaceUnsupported(error) {
         error.details?.capability === "rename-noreplace";
 }
 
-// EXTERNAL MODULE: external "node:fs"
-var external_node_fs_ = __webpack_require__(3024);
 ;// CONCATENATED MODULE: ../../node_modules/@openclaw/fs-safe/dist/exact-identity.js
 
 
@@ -50180,7 +50204,9 @@ async function lstatIfExists(path) {
         return false;
     }
 }
-function isPathWithinRoot(rootPath, candidatePath) {
+/**
+ * Returns true when candidatePath is rootPath or a descendant of it.
+ */ function isPathWithinRoot(rootPath, candidatePath) {
     if (candidatePath === rootPath) {
         return true;
     }
@@ -53222,9 +53248,16 @@ async function readVersionFileContent(targetDir, relativePath) {
  * File system implementation of the environment gateway.
  */ class FileSystemEnvironmentGateway {
     cwd;
-    config = null;
-    constructor(cwd){
+    config;
+    /**
+     * @param cwd Directory the configuration is loaded from (defaults to
+     * process.cwd()), unless `config` is given
+     * @param config A configuration loaded by the caller. The gateway uses it
+     * as it is and does not read the configuration file itself, so a caller
+     * that also needs the configuration reads the file once for both.
+     */ constructor(cwd, config){
         this.cwd = cwd;
+        this.config = config ?? null;
     }
     async getConfig() {
         if (!this.config) {
@@ -53359,6 +53392,13 @@ async function readVersionFileContent(targetDir, relativePath) {
  */ function createEnvironmentGateway(cwd) {
     return new FileSystemEnvironmentGateway(cwd);
 }
+/**
+ * Creates an environment gateway that detects with a configuration the caller
+ * has already loaded, so the configuration file is read once and the gateway
+ * and the caller cannot see two different versions of it.
+ */ function createEnvironmentGatewayWithConfig(config) {
+    return new FileSystemEnvironmentGateway(undefined, config);
+}
 
 ;// CONCATENATED MODULE: ../core/src/gateways/github-ruleset-gateway.ts
 /**
@@ -53777,37 +53817,1055 @@ function createInitHooksConfigGateway() {
     return new InitHooksConfigGateway();
 }
 
+;// CONCATENATED MODULE: ../core/src/entities/file-limits.ts
+/**
+ * The most bytes of an instruction file that lint and doctor read. Import
+ * expansion, the instruction readers and doctor's file reads all use this one
+ * number, and the advisories that tell a user a file was too large describe it
+ * with {@link describeByteLimit}, so the cap and its text cannot drift.
+ */ const MAX_INSTRUCTION_FILE_BYTES = 1_048_576;
+const BYTES_PER_MIB = 1_048_576;
+/**
+ * A byte limit in words a reader can check a file against: a whole number of
+ * mebibytes ("1 MiB"), or the exact number of bytes, never a rounded figure.
+ */ function describeByteLimit(bytes) {
+    return bytes % BYTES_PER_MIB === 0 ? `${bytes / BYTES_PER_MIB} MiB` : `${bytes} bytes`;
+}
+
+;// CONCATENATED MODULE: ../core/src/entities/lint-rules.ts
+/**
+ * Lint rule registry entity.
+ * Defines all known lint rule IDs with their default severities, organized by target.
+ */ /** Valid severity values for rule configuration */ /** Reported when an instruction file could not be read or parsed. */ const INSTRUCTION_PARSE_ERROR_RULE_ID = "instruction/parse-error";
+/** Reported when instruction discovery stopped at one of its limits. */ const DISCOVERY_LIMIT_REACHED_RULE_ID = "instruction/discovery-limit-reached";
+/** Reported when instruction discovery skipped symbolic links that lead outside the repository. */ const DISCOVERY_SYMLINK_SKIPPED_RULE_ID = "instruction/discovery-symlink-skipped";
+/** Default severity levels for all known lint rules */ const DEFAULT_LINT_RULES = (/* unused pure expression or super */ null && ({
+    agents: {
+        "agent/missing-frontmatter": "error",
+        "agent/invalid-frontmatter": "error",
+        "agent/missing-name": "error",
+        "agent/invalid-name-format": "error",
+        "agent/name-mismatch": "error",
+        "agent/missing-description": "error",
+        "agent/invalid-description": "error",
+        "agent/invalid-field": "warn"
+    },
+    subagents: {
+        "subagent/missing-frontmatter": "error",
+        "subagent/invalid-frontmatter": "error",
+        "subagent/missing-name": "error",
+        // Claude Code's documented subagent contract requires only `name`
+        // and `description`; it neither specifies a name format beyond
+        // "unique identifier" nor ties `name` to the filename the way
+        // VS Code derives a Copilot custom agent's name from
+        // `<name>.agent.md`. Defaulting these to "warn" avoids failing
+        // lint for subagents that are valid per Claude Code's own docs.
+        "subagent/invalid-name-format": "warn",
+        "subagent/name-mismatch": "warn",
+        "subagent/missing-description": "error",
+        "subagent/invalid-description": "error",
+        "subagent/invalid-field": "warn"
+    },
+    mcpServers: {
+        "mcpserver/invalid-json": "error",
+        "mcpserver/invalid-config": "error"
+    },
+    hooks: {
+        "hook/invalid-json": "error",
+        "hook/invalid-config": "error",
+        "hook/missing-command": "error",
+        "hook/unknown-event": "error",
+        "hook/missing-matcher": "warn",
+        "hook/missing-timeout": "warn"
+    },
+    instructions: {
+        [INSTRUCTION_PARSE_ERROR_RULE_ID]: "warn",
+        "instruction/command-not-in-code-block": "warn",
+        "instruction/command-outside-section": "warn",
+        "instruction/missing-error-handling": "warn",
+        "instruction/missing-structural-heading": "warn",
+        "instruction/import-unresolved": "warn",
+        "instruction/import-escape": "warn",
+        "instruction/import-symlink": "warn",
+        "instruction/import-cycle": "warn",
+        "instruction/import-depth-exceeded": "warn",
+        "instruction/import-size-exceeded": "warn",
+        [DISCOVERY_LIMIT_REACHED_RULE_ID]: "warn",
+        [DISCOVERY_SYMLINK_SKIPPED_RULE_ID]: "warn"
+    },
+    skills: {
+        "skill/invalid-frontmatter": "error",
+        "skill/missing-frontmatter": "error",
+        "skill/missing-name": "error",
+        "skill/invalid-name-format": "error",
+        "skill/name-mismatch": "error",
+        "skill/missing-description": "error",
+        "skill/invalid-description": "error",
+        "skill/missing-allowed-tools": "warn",
+        "skill/missing-argument-hint": "warn"
+    }
+}));
+const RUN_LEVEL_RULE_IDS = new Set([
+    DISCOVERY_LIMIT_REACHED_RULE_ID,
+    DISCOVERY_SYMLINK_SKIPPED_RULE_ID
+]);
+/**
+ * Whether a rule's diagnostics describe the whole run rather than a place in
+ * one file, so a reporter that filters by changed file or line (reviewdog's
+ * diff filter) would drop them. Reporters surface these some other way. A
+ * predicate rather than the set itself, so a caller cannot change which rules
+ * count.
+ */ function isRunLevelRuleId(ruleId) {
+    return ruleId !== undefined && RUN_LEVEL_RULE_IDS.has(ruleId);
+}
+
+;// CONCATENATED MODULE: ../core/src/entities/discovery-limit-message.ts
+/**
+ * The one wording for a directory walk that stopped at a limit, shared by lint
+ * (instruction/discovery-limit-reached) and doctor (discovery-limit-reached)
+ * so the two cannot describe the same limits differently. Each caller says
+ * what it was looking for and what the user should take from the gap.
+ */ /** The limits a walk reached; a limit it did not reach is left out. */ /** One sentence for each limit that was reached: directories, depth, entries. */ function describeDiscoveryLimits(reached, { subject, missing, consequence }) {
+    const sentences = [];
+    if (reached.maxDirectories !== undefined) {
+        sentences.push(`${subject} stopped after listing ${reached.maxDirectories} directories, so ${missing} in the remaining directories ${consequence}.`);
+    }
+    if (reached.maxDepth !== undefined) {
+        sentences.push(`${subject} did not go more than ${reached.maxDepth} directories deep, so ${missing} in deeper directories ${consequence}.`);
+    }
+    if (reached.maxEntries !== undefined) {
+        sentences.push(`${subject} stopped after examining ${reached.maxEntries} directory entries, so ${missing} in the remaining entries ${consequence}.`);
+    }
+    return sentences;
+}
+/** How many paths a message names before it counts the rest. */ const NAMED_PATHS = 5;
+/**
+ * The first few paths joined with commas, and a count of the rest, so a
+ * message about a fan-out stays readable: "a, b, c, d, e, and 3 more".
+ */ function listPaths(paths) {
+    const listed = paths.slice(0, NAMED_PATHS).join(", ");
+    const unlisted = paths.length - NAMED_PATHS;
+    return unlisted > 0 ? `${listed}, and ${unlisted} more` : listed;
+}
+/**
+ * The message for instruction file discovery skipping symbolic links that
+ * point outside the repository, so their targets were not analyzed.
+ */ function describeSkippedSymlinks(paths) {
+    return `Instruction file discovery skipped ${paths.length} symbolic link(s) that point outside the repository, so their targets were not analyzed: ${listPaths(paths)}. Replace a link with a file inside the repository to have it analyzed.`;
+}
+
+;// CONCATENATED MODULE: ../core/src/entities/agentic-location-catalog.ts
+/**
+ * Canonical catalog of agentic construct locations shared by lint and doctor.
+ * Pure data only — no filesystem I/O.
+ */ const agentic_location_catalog_AGENTIC_LOCATION_CATALOG = [
+    // Skill lint roots
+    {
+        id: "skill-github",
+        path: ".github/skills",
+        matchKind: "directory-prefix",
+        primaryConstruct: "skill",
+        lintTarget: "skills",
+        harnessHints: [
+            "copilot"
+        ]
+    },
+    {
+        id: "skill-claude",
+        path: ".claude/skills",
+        matchKind: "directory-prefix",
+        primaryConstruct: "skill",
+        lintTarget: "skills",
+        harnessHints: [
+            "claude"
+        ]
+    },
+    {
+        id: "skill-agents",
+        path: ".agents/skills",
+        matchKind: "directory-prefix",
+        primaryConstruct: "skill",
+        lintTarget: "skills",
+        harnessHints: [
+            "shared"
+        ]
+    },
+    // Additional skill roots (SKILL.md convention, no alternate layout documented)
+    {
+        id: "skill-pi",
+        path: ".pi/skills",
+        matchKind: "directory-prefix",
+        primaryConstruct: "skill",
+        lintTarget: "skills",
+        harnessHints: [
+            "pi"
+        ]
+    },
+    {
+        id: "skill-pi-prompts",
+        path: ".pi/prompts",
+        matchKind: "directory-prefix",
+        primaryConstruct: "skill",
+        lintTarget: "skills",
+        harnessHints: [
+            "pi"
+        ]
+    },
+    // Agent lint root (dual-role: agent + instruction)
+    {
+        id: "agent-github",
+        path: ".github/agents",
+        matchKind: "directory-prefix",
+        primaryConstruct: "agent",
+        secondaryConstructs: [
+            "instruction"
+        ],
+        lintTarget: "agents",
+        harnessHints: [
+            "copilot"
+        ],
+        instructionFormat: "copilot-agent"
+    },
+    // Hook lint exact configs
+    {
+        id: "hook-copilot-agent-shell",
+        path: ".github/hooks/agent-shell/hooks.json",
+        matchKind: "exact",
+        primaryConstruct: "hook",
+        lintTarget: "hooks",
+        harnessHints: [
+            "copilot"
+        ],
+        hookPlatform: "copilot"
+    },
+    {
+        id: "hook-claude-settings",
+        path: ".claude/settings.json",
+        matchKind: "exact",
+        primaryConstruct: "hook",
+        lintTarget: "hooks",
+        harnessHints: [
+            "claude"
+        ],
+        hookPlatform: "claude"
+    },
+    {
+        id: "hook-claude-settings-local",
+        path: ".claude/settings.local.json",
+        matchKind: "exact",
+        primaryConstruct: "hook",
+        lintTarget: "hooks",
+        harnessHints: [
+            "claude"
+        ],
+        hookPlatform: "claude"
+    },
+    // Doctor-only hook directory prefixes
+    {
+        id: "hook-github-dir",
+        path: ".github/hooks",
+        matchKind: "directory-prefix",
+        primaryConstruct: "hook",
+        lintTarget: "none",
+        harnessHints: [
+            "copilot"
+        ]
+    },
+    {
+        id: "hook-claude-dir",
+        path: ".claude/hooks",
+        matchKind: "directory-prefix",
+        primaryConstruct: "hook",
+        lintTarget: "none",
+        harnessHints: [
+            "claude"
+        ]
+    },
+    // Instruction lint locations
+    {
+        id: "instruction-copilot-root",
+        path: ".github/copilot-instructions.md",
+        matchKind: "exact",
+        primaryConstruct: "instruction",
+        lintTarget: "instructions",
+        harnessHints: [
+            "copilot"
+        ],
+        instructionFormat: "copilot-instructions"
+    },
+    {
+        id: "instruction-copilot-scoped",
+        path: ".github/instructions",
+        matchKind: "directory-prefix",
+        primaryConstruct: "instruction",
+        lintTarget: "instructions",
+        harnessHints: [
+            "copilot"
+        ],
+        instructionFormat: "copilot-scoped",
+        includeSubdirectories: true,
+        fileSuffix: ".instructions.md"
+    },
+    {
+        id: "instruction-agents-md",
+        path: "AGENTS.md",
+        matchKind: "exact",
+        primaryConstruct: "instruction",
+        lintTarget: "instructions",
+        harnessHints: [
+            "shared"
+        ],
+        instructionFormat: "agents-md"
+    },
+    {
+        id: "instruction-agents-override-md",
+        path: "AGENTS.override.md",
+        matchKind: "exact",
+        primaryConstruct: "instruction",
+        lintTarget: "instructions",
+        harnessHints: [
+            "codex"
+        ],
+        instructionFormat: "agents-md"
+    },
+    {
+        id: "instruction-claude-md",
+        path: "CLAUDE.md",
+        matchKind: "exact",
+        primaryConstruct: "instruction",
+        lintTarget: "instructions",
+        harnessHints: [
+            "claude"
+        ],
+        instructionFormat: "claude-md"
+    },
+    {
+        id: "instruction-claude-dir-md",
+        path: ".claude/CLAUDE.md",
+        matchKind: "exact",
+        primaryConstruct: "instruction",
+        lintTarget: "instructions",
+        harnessHints: [
+            "claude"
+        ],
+        instructionFormat: "claude-md"
+    },
+    // Subagent lint root
+    {
+        id: "subagent-claude",
+        path: ".claude/agents",
+        matchKind: "directory-prefix",
+        primaryConstruct: "subagent",
+        lintTarget: "subagents",
+        harnessHints: [
+            "claude"
+        ]
+    },
+    {
+        id: "agent-claude-commands",
+        path: ".claude/commands",
+        matchKind: "directory-prefix",
+        primaryConstruct: "agent",
+        lintTarget: "none",
+        harnessHints: [
+            "claude"
+        ]
+    },
+    {
+        id: "plugin-codex",
+        path: ".codex-plugin",
+        matchKind: "directory-prefix",
+        primaryConstruct: "plugin",
+        lintTarget: "none",
+        harnessHints: [
+            "codex"
+        ]
+    }
+];
+
+;// CONCATENATED MODULE: ../core/src/lib/agentic-location-matchers.ts
+/**
+ * Pure path→construct matching helpers over the agentic location catalog.
+ * No filesystem I/O.
+ */ 
+/**
+ * Normalizes a repo-relative path for catalog matching.
+ * Collapses `.` / `..` segments. Returns "" when the path is absolute or
+ * escapes the repository root — callers treat "" as non-matching.
+ */ function isAbsoluteRepoPath(normalized) {
+    // POSIX absolute, UNC-style leading slash after backslash conversion,
+    // and Windows drive-letter absolute (C:/..., d:\...).
+    return normalized.startsWith("/") || /^[A-Za-z]:(\/|$)/.test(normalized);
+}
+function normalizeRepoRelativePath(path) {
+    const normalized = path.replaceAll("\\", "/");
+    if (isAbsoluteRepoPath(normalized)) {
+        return "";
+    }
+    const resolved = [];
+    for (const segment of normalized.split("/")){
+        if (segment === "" || segment === ".") {
+            continue;
+        }
+        if (segment === ".." && resolved.length === 0) {
+            return "";
+        }
+        if (segment === "..") {
+            resolved.pop();
+            continue;
+        }
+        resolved.push(segment);
+    }
+    return resolved.join("/");
+}
+function matchesLocationEntry(path, entry) {
+    const normalized = normalizeRepoRelativePath(path);
+    if (entry.matchKind === "exact") {
+        return normalized === entry.path;
+    }
+    return normalized === entry.path || normalized.startsWith(`${entry.path}/`) && (entry.fileSuffix === undefined || normalized.endsWith(entry.fileSuffix));
+}
+function entriesMatchingPath(path, catalog = AGENTIC_LOCATION_CATALOG) {
+    return catalog.filter((entry)=>matchesLocationEntry(path, entry));
+}
+/**
+ * True when the path sits under a catalog location that only accepts files
+ * with a given suffix, the path lacks that suffix, and no other entry claims
+ * it. The harness that owns that location does not load such a file (Copilot
+ * loads only `*.instructions.md` from `.github/instructions`), so a consumer
+ * that finds the file by directory prefix alone should leave it out.
+ */ function isExcludedBySuffix(path, catalog = AGENTIC_LOCATION_CATALOG) {
+    const normalized = normalizeRepoRelativePath(path);
+    return entriesMatchingPath(path, catalog).length === 0 && catalog.some((entry)=>entry.matchKind === "directory-prefix" && entry.fileSuffix !== undefined && normalized.startsWith(`${entry.path}/`));
+}
+function specificityScore(entry) {
+    // Exact matches outrank any prefix; longer prefixes outrank shorter ones.
+    const kindBonus = entry.matchKind === "exact" ? 1_000_000 : 0;
+    return kindBonus + entry.path.length;
+}
+function bestMatchingEntry(path, catalog = AGENTIC_LOCATION_CATALOG) {
+    const matches = entriesMatchingPath(path, catalog);
+    if (matches.length === 0) {
+        return null;
+    }
+    let best = matches[0];
+    let bestScore = specificityScore(best);
+    for(let i = 1; i < matches.length; i++){
+        const candidate = matches[i];
+        const score = specificityScore(candidate);
+        if (score > bestScore) {
+            best = candidate;
+            bestScore = score;
+        }
+    }
+    return best;
+}
+function primaryConstructTypeForPath(path, catalog = AGENTIC_LOCATION_CATALOG) {
+    return bestMatchingEntry(path, catalog)?.primaryConstruct ?? null;
+}
+function constructTypesForPath(path, catalog = AGENTIC_LOCATION_CATALOG) {
+    const best = bestMatchingEntry(path, catalog);
+    if (!best) {
+        return [];
+    }
+    const secondary = best.secondaryConstructs ?? [];
+    if (secondary.length === 0) {
+        return [
+            best.primaryConstruct
+        ];
+    }
+    return [
+        best.primaryConstruct,
+        ...secondary
+    ];
+}
+function lintTargetEntries(target, catalog = agentic_location_catalog_AGENTIC_LOCATION_CATALOG) {
+    return catalog.filter((entry)=>entry.lintTarget === target);
+}
+function skillDirectoryRoots(catalog = agentic_location_catalog_AGENTIC_LOCATION_CATALOG) {
+    return lintTargetEntries("skills", catalog).filter((entry)=>entry.matchKind === "directory-prefix").map((entry)=>entry.path);
+}
+function agentDirectoryRoots(catalog = AGENTIC_LOCATION_CATALOG) {
+    return lintTargetEntries("agents", catalog).filter((entry)=>entry.matchKind === "directory-prefix").map((entry)=>entry.path);
+}
+function subagentDirectoryRoots(catalog = AGENTIC_LOCATION_CATALOG) {
+    return lintTargetEntries("subagents", catalog).filter((entry)=>entry.matchKind === "directory-prefix").map((entry)=>entry.path);
+}
+function isHookConfigEntry(entry) {
+    return entry.matchKind === "exact" && entry.hookPlatform != null;
+}
+function hookConfigPaths(catalog = AGENTIC_LOCATION_CATALOG) {
+    return lintTargetEntries("hooks", catalog).filter(isHookConfigEntry).map((entry)=>({
+            relativePath: entry.path,
+            platform: entry.hookPlatform
+        }));
+}
+function instructionDiscoveryEntries(catalog = agentic_location_catalog_AGENTIC_LOCATION_CATALOG) {
+    return catalog.filter((entry)=>entry.instructionFormat != null);
+}
+
+;// CONCATENATED MODULE: ../core/src/gateways/real-path-within-root.ts
+/**
+ * Shared symlink policy for discovering agentic files (instruction files,
+ * doctor scan targets): follow a symlink only when its real target stays
+ * inside the repository.
+ */ 
+
+const nodeInspectionFs = {
+    realpath: promises_.realpath,
+    stat: promises_.stat
+};
+/**
+ * The error codes that mean no file is there. A path the system cannot
+ * represent cannot name a file, so it is as missing as one that was never
+ * created: a name too long for the file system to hold, one it rejects as
+ * invalid, or one holding a NUL byte, which Node rejects before it asks the
+ * system at all.
+ */ const MISSING_ERROR_CODES = [
+    "ENOENT",
+    "ENOTDIR",
+    "ENAMETOOLONG",
+    "EINVAL",
+    "ERR_INVALID_ARG_VALUE"
+];
+function isMissingError(error) {
+    return error instanceof Error && "code" in error && typeof error.code === "string" && MISSING_ERROR_CODES.includes(error.code);
+}
+const UNREADABLE_ERROR_CODES = [
+    "EMFILE",
+    "ENFILE",
+    "EACCES",
+    "EPERM",
+    "EIO"
+];
+function isUnreadableError(error) {
+    return error instanceof Error && "code" in error && typeof error.code === "string" && UNREADABLE_ERROR_CODES.includes(error.code);
+}
+function statusForInspectionError(error) {
+    if (isMissingError(error)) {
+        return "missing";
+    }
+    return isUnreadableError(error) ? "unreadable" : "unsupported";
+}
+async function kindOutsideRoot(real, fs) {
+    try {
+        const outside = await fs.stat(real);
+        if (outside.isDirectory()) {
+            return "directory";
+        }
+        return outside.isFile() ? "file" : "other";
+    } catch  {
+        return "other";
+    }
+}
+/**
+ * Follows a path (and any symlink along it) to its real location and reports
+ * why it cannot be used: missing, outside the real root, neither a regular
+ * file nor a directory, or unreadable (the system refused to look at it). Stats the already-resolved real path (rather than
+ * re-resolving the symlink) so the within-root check, the type check and the
+ * recorded identity observe the same target.
+ *
+ * @param rootReal Real (symlink-free) path of the root directory
+ * @param absolutePath Path to resolve, which may contain symlinks
+ * @param fs The file system calls to make; the real ones by default
+ */ async function inspectPathWithinRoot(rootReal, absolutePath, fs = nodeInspectionFs) {
+    try {
+        const real = await fs.realpath(absolutePath);
+        if (!isPathWithinRoot(rootReal, real)) {
+            return {
+                status: "outside-root",
+                kind: await kindOutsideRoot(real, fs)
+            };
+        }
+        const targetStat = await fs.stat(real);
+        const identity = {
+            dev: targetStat.dev,
+            ino: targetStat.ino
+        };
+        if (targetStat.isDirectory()) {
+            return {
+                status: "ok",
+                kind: "directory",
+                real,
+                identity
+            };
+        }
+        if (targetStat.isFile()) {
+            return {
+                status: "ok",
+                kind: "file",
+                real,
+                identity
+            };
+        }
+        return {
+            status: "unsupported"
+        };
+    } catch (error) {
+        return {
+            status: statusForInspectionError(error)
+        };
+    }
+}
+/**
+ * Shared symlink policy for discovering agentic files: a path (or any
+ * symlink along it) is followed only when its real target stays inside the
+ * real root and is a regular file or directory. Callers must still read the
+ * content through the real path with the no-follow readers, which reject a
+ * symlink swapped in after this check.
+ *
+ * @param rootReal Real (symlink-free) path of the root directory
+ * @param absolutePath Path to resolve, which may contain symlinks
+ * @returns The real path and its kind, or null when the target is missing,
+ * outside the root, or not a regular file or directory
+ */ async function resolveRealPathWithinRoot(rootReal, absolutePath) {
+    const inspection = await inspectPathWithinRoot(rootReal, absolutePath);
+    return inspection.status === "ok" ? {
+        kind: inspection.kind,
+        real: inspection.real
+    } : null;
+}
+
+;// CONCATENATED MODULE: ../core/src/entities/code-unit-order.ts
+/**
+ * Orders strings by UTF-16 code unit.
+ *
+ * Unlike `localeCompare`, the result does not depend on the machine's locale
+ * or ICU data, so anything sorted with it (directory entries, inventory
+ * paths) comes out in the same order on every machine and in CI.
+ */ function compareCodeUnits(a, b) {
+    if (a < b) {
+        return -1;
+    }
+    return a > b ? 1 : 0;
+}
+
+;// CONCATENATED MODULE: ../core/src/gateways/repository-walk.ts
+/**
+ * The shared, bounded walk over a repository tree, used by instruction
+ * discovery (lint, MCP) and by doctor so the two cannot disagree about how a
+ * tree is traversed.
+ *
+ * The walk follows symlinks only while their real target stays inside the
+ * repository (the shared policy in real-path-within-root), terminates on
+ * symlink cycles, lists entries in name order so the result does not depend
+ * on the file system, and is bounded in depth and in the number of
+ * directories it lists.
+ */ 
+
+
+
+
+/**
+ * The deepest level whose directories are listed (the start directory is 0).
+ * A directory at this depth is listed, and its own subdirectories are not
+ * entered.
+ */ const DEFAULT_MAX_WALK_DEPTH = 10;
+/** Directories listed before the walk stops descending. */ const DEFAULT_MAX_WALK_DIRECTORIES = 10_000;
+/**
+ * Directory entries examined before the walk stops. The directory cap counts
+ * listings, not the entries in them, and a fan-out of directory aliases lists
+ * a wide directory many times over, so this bounds the work itself.
+ */ const DEFAULT_MAX_WALK_ENTRIES = 200_000;
+const DEFAULT_SKIPPED_DIRECTORY_NAMES = [
+    "node_modules",
+    ".git"
+];
+const listWithinRoot = async (rootReal, relativePath)=>{
+    try {
+        return await file_system_utils_listDirectoryWithinRoot(rootReal, relativePath);
+    } catch  {
+        return [];
+    }
+};
+function resolveSettings(options) {
+    return {
+        startRelativePath: options.startRelativePath,
+        includeFile: options.includeFile,
+        includeSubdirectories: options.includeSubdirectories ?? true,
+        revisit: options.revisit ?? "once-per-real-directory",
+        maxDepth: options.maxDepth ?? DEFAULT_MAX_WALK_DEPTH,
+        maxDirectories: options.maxDirectories ?? DEFAULT_MAX_WALK_DIRECTORIES,
+        maxEntries: options.maxEntries ?? DEFAULT_MAX_WALK_ENTRIES,
+        skipDirectoryNames: new Set(options.skipDirectoryNames ?? DEFAULT_SKIPPED_DIRECTORY_NAMES),
+        listDirectory: options.listDirectory ?? listWithinRoot
+    };
+}
+/**
+ * Whether a directory entry name could escape its directory: a name that is
+ * the parent or current directory, or that holds a path separator. A name
+ * with two dots inside it, such as `review..strict.md`, is an ordinary name.
+ */ function isUnsafeEntryName(name) {
+    return name === "." || name === ".." || name.includes("/") || name.includes("\\");
+}
+/** Joins a repository-relative directory and an entry without a leading "/". */ function joinRelative(directory, name) {
+    return directory === "" ? name : `${directory}/${name}`;
+}
+function segmentsOf(relativePath) {
+    return relativePath.split("/").filter((segment)=>segment !== "");
+}
+/**
+ * Owns the bookkeeping of one walk. State lives on the instance, not in
+ * parameters, so a walk cannot leak into another.
+ */ class RepositoryWalk {
+    targetDir;
+    rootReal;
+    settings;
+    files = [];
+    visitedRealDirectories = new Set();
+    listedDirectories = 0;
+    limitReached = false;
+    depthLimitReached = false;
+    entriesExamined = 0;
+    entryLimitReached = false;
+    skippedOutsideRoot = [];
+    constructor(targetDir, rootReal, settings){
+        this.targetDir = targetDir;
+        this.rootReal = rootReal;
+        this.settings = settings;
+    }
+    async run() {
+        await this.walkDirectory(this.settings.startRelativePath, 0, []);
+        return {
+            files: this.files,
+            directoryLimitReached: this.limitReached,
+            depthLimitReached: this.depthLimitReached,
+            entryLimitReached: this.entryLimitReached,
+            skippedOutsideRoot: this.skippedOutsideRoot,
+            limits: {
+                maxDirectories: this.settings.maxDirectories,
+                maxDepth: this.settings.maxDepth,
+                maxEntries: this.settings.maxEntries
+            }
+        };
+    }
+    isRevisit(real, ancestors) {
+        return this.settings.revisit === "refuse-ancestors" ? ancestors.includes(real) : this.visitedRealDirectories.has(real);
+    }
+    async walkDirectory(directoryRelativePath, depth, ancestors) {
+        if (this.limitReached) {
+            return;
+        }
+        const directory = await inspectPathWithinRoot(this.rootReal, (0,external_node_path_.join)(this.targetDir, ...segmentsOf(directoryRelativePath)));
+        if (directory.status === "outside-root" && directory.kind === "directory") {
+            this.skippedOutsideRoot.push(directoryRelativePath);
+            return;
+        }
+        if (directory.status !== "ok" || directory.kind !== "directory") {
+            return;
+        }
+        if (this.isRevisit(directory.real, ancestors)) {
+            return;
+        }
+        if (this.listedDirectories >= this.settings.maxDirectories) {
+            this.limitReached = true;
+            return;
+        }
+        this.listedDirectories += 1;
+        this.visitedRealDirectories.add(directory.real);
+        const entries = await this.settings.listDirectory(this.rootReal, (0,external_node_path_.relative)(this.rootReal, directory.real));
+        const sorted = entries.filter((entry)=>!isUnsafeEntryName(entry.name)).sort((a, b)=>compareCodeUnits(a.name, b.name));
+        for (const entry of sorted){
+            if (this.entriesExamined >= this.settings.maxEntries) {
+                this.entryLimitReached = true;
+                return;
+            }
+            this.entriesExamined += 1;
+            await this.walkEntry(directory.real, joinRelative(directoryRelativePath, entry.name), entry.name, depth, [
+                ...ancestors,
+                directory.real
+            ]);
+        }
+    }
+    async walkEntry(directoryReal, entryRelativePath, name, depth, ancestors) {
+        const entry = await inspectPathWithinRoot(this.rootReal, (0,external_node_path_.join)(directoryReal, name));
+        if (entry.status === "outside-root") {
+            if (this.wouldHaveCollected(entry.kind, name, depth)) {
+                this.skippedOutsideRoot.push(entryRelativePath);
+            }
+            return;
+        }
+        if (entry.status !== "ok") {
+            return;
+        }
+        if (entry.kind === "file") {
+            this.collectFile(entryRelativePath, name, entry.real, entry.identity);
+            return;
+        }
+        if (this.shouldDescend(name, depth)) {
+            await this.walkDirectory(entryRelativePath, depth + 1, ancestors);
+        } else if (this.isTooDeep(name, depth) && !this.isRevisit(entry.real, ancestors)) {
+            this.depthLimitReached = true;
+        }
+    }
+    wouldHaveCollected(kind, name, depth) {
+        if (kind === "file") {
+            return this.settings.includeFile(name);
+        }
+        return kind === "directory" && this.shouldDescend(name, depth);
+    }
+    collectFile(relativePath, name, real, identity) {
+        if (this.settings.includeFile(name)) {
+            this.files.push({
+                relativePath,
+                real,
+                identity
+            });
+        }
+    }
+    shouldDescend(name, depth) {
+        return this.settings.includeSubdirectories && depth < this.settings.maxDepth && !this.settings.skipDirectoryNames.has(name);
+    }
+    isTooDeep(name, depth) {
+        return this.settings.includeSubdirectories && depth >= this.settings.maxDepth && !this.settings.skipDirectoryNames.has(name);
+    }
+}
+/**
+ * Walks a repository from options.startRelativePath and returns the files
+ * accepted by options.includeFile, in name order, with the logical path a
+ * harness loads each at and the real path to read it from.
+ *
+ * The cap counts every directory the walk lists (a logical visit), so a
+ * directory reached through several aliases is counted each time it is
+ * listed. When the cap is hit the walk stops listing, keeps what it found and
+ * reports directoryLimitReached; it never throws for it.
+ */ async function walkRepository(targetDir, options) {
+    const rootReal = await (0,promises_.realpath)((0,external_node_path_.resolve)(targetDir)).catch(()=>null);
+    const settings = resolveSettings(options);
+    if (rootReal === null) {
+        return {
+            files: [],
+            directoryLimitReached: false,
+            depthLimitReached: false,
+            entryLimitReached: false,
+            skippedOutsideRoot: [],
+            limits: {
+                maxDirectories: settings.maxDirectories,
+                maxDepth: settings.maxDepth,
+                maxEntries: settings.maxEntries
+            }
+        };
+    }
+    return new RepositoryWalk(targetDir, rootReal, settings).run();
+}
+
+;// CONCATENATED MODULE: ../core/src/gateways/instruction-file-discovery-gateway.ts
+/**
+ * Gateway for discovering instruction files across multiple formats.
+ * Supports GitHub Copilot, Claude Code, and community agent instruction formats.
+ */ 
+
+
+
+
+
+
+/**
+ * File system implementation of the instruction file discovery gateway.
+ *
+ * Symlinks follow the shared core policy (resolveRealPathWithinRoot): a
+ * symlinked instruction file or directory is discovered only when its real
+ * target stays inside the repository. The discovered filePath keeps the
+ * location the harness loads; contentPath points at the real file.
+ */ class FileSystemInstructionFileDiscoveryGateway {
+    maxDirectories;
+    maxEntries;
+    /**
+     * @param options.maxDirectories Directories one entry walk lists before it
+     * stops; defaults to the shared walk's production limit
+     * @param options.maxEntries Directory entries one entry walk examines
+     * before it stops; defaults to the shared walk's production limit
+     */ constructor(options = {}){
+        this.maxDirectories = options.maxDirectories ?? (/* inlined export .DEFAULT_MAX_WALK_DIRECTORIES */10000);
+        this.maxEntries = options.maxEntries;
+    }
+    async discoverInstructionFiles(targetDir, onDiagnostic) {
+        const rootReal = await (0,promises_.realpath)((0,external_node_path_.resolve)(targetDir)).catch(()=>null);
+        if (rootReal === null) {
+            return [];
+        }
+        const root = {
+            targetDir,
+            rootReal
+        };
+        const findings = new DiscoveryFindings();
+        for (const entry of instructionDiscoveryEntries()){
+            const format = entry.instructionFormat;
+            if (format == null) {
+                continue;
+            }
+            if (entry.matchKind === "exact") {
+                findings.addExact(await discoverExactFile(root, entry.path, format));
+                continue;
+            }
+            findings.addWalk(await walkRepository(targetDir, this.walkOptions(entry)), (file)=>toDiscoveredFile(root, file.relativePath, {
+                    kind: "file",
+                    real: file.real
+                }, format));
+        }
+        findings.report(onDiagnostic);
+        return findings.files;
+    }
+    walkOptions(entry) {
+        return {
+            startRelativePath: entry.path,
+            includeFile: (name)=>name.endsWith(entry.fileSuffix ?? ".md"),
+            includeSubdirectories: entry.includeSubdirectories === true,
+            revisit: "once-per-real-directory",
+            maxDirectories: this.maxDirectories,
+            ...this.maxEntries === undefined ? {} : {
+                maxEntries: this.maxEntries
+            }
+        };
+    }
+}
+/**
+ * What discovery found across the instruction locations it looked at, and
+ * what it left out, so it can say so once at the end.
+ */ class DiscoveryFindings {
+    files = [];
+    skippedOutsideRoot = [];
+    directoryLimitReached = false;
+    depthLimitReached = false;
+    entryLimitReached = false;
+    limits;
+    addExact(exact) {
+        this.files.push(...exact.files);
+        this.skippedOutsideRoot.push(...exact.skippedOutsideRoot);
+    }
+    addWalk(walked, toDiscovered) {
+        this.limits = walked.limits;
+        this.directoryLimitReached ||= walked.directoryLimitReached;
+        this.depthLimitReached ||= walked.depthLimitReached;
+        this.entryLimitReached ||= walked.entryLimitReached;
+        this.skippedOutsideRoot.push(...walked.skippedOutsideRoot);
+        this.files.push(...walked.files.map(toDiscovered));
+    }
+    report(onDiagnostic) {
+        const reasons = this.describeLimits();
+        if (reasons.length > 0) {
+            onDiagnostic?.({
+                ruleId: DISCOVERY_LIMIT_REACHED_RULE_ID,
+                message: reasons.join(" ")
+            });
+        }
+        if (this.skippedOutsideRoot.length > 0) {
+            onDiagnostic?.({
+                ruleId: DISCOVERY_SYMLINK_SKIPPED_RULE_ID,
+                message: describeSkippedSymlinks(this.skippedOutsideRoot)
+            });
+        }
+    }
+    describeLimits() {
+        if (this.limits === undefined) {
+            return [];
+        }
+        return describeDiscoveryLimits({
+            ...this.directoryLimitReached ? {
+                maxDirectories: this.limits.maxDirectories
+            } : {},
+            ...this.depthLimitReached ? {
+                maxDepth: this.limits.maxDepth
+            } : {},
+            ...this.entryLimitReached ? {
+                maxEntries: this.limits.maxEntries
+            } : {}
+        }, DISCOVERY_WORDING);
+    }
+}
+const DISCOVERY_WORDING = {
+    subject: "Instruction file discovery",
+    missing: "instruction files",
+    consequence: "were not analyzed"
+};
+/**
+ * Discovers one exact-path instruction file, or nothing when it is missing
+ * or resolves outside the root, in which case a link out of the repository is
+ * reported as skipped.
+ */ async function discoverExactFile(root, relativePosixPath, format) {
+    const inspected = await inspectPathWithinRoot(root.rootReal, (0,external_node_path_.join)(root.targetDir, ...relativePosixPath.split("/")));
+    if (inspected.status === "ok" && inspected.kind === "file") {
+        return {
+            files: [
+                toDiscoveredFile(root, relativePosixPath, inspected, format)
+            ],
+            skippedOutsideRoot: []
+        };
+    }
+    const leadsOutside = inspected.status === "outside-root" && inspected.kind === "file";
+    return {
+        files: [],
+        skippedOutsideRoot: leadsOutside ? [
+            relativePosixPath
+        ] : []
+    };
+}
+/**
+ * Builds the discovered file, adding contentPath when the logical path
+ * resolves through a symlink to another file.
+ */ function toDiscoveredFile(root, relativePosixPath, resolved, format) {
+    const segments = relativePosixPath.split("/");
+    const filePath = (0,external_node_path_.join)(root.targetDir, ...segments);
+    const lexicalReal = (0,external_node_path_.join)(root.rootReal, ...segments);
+    if (resolved.real === lexicalReal) {
+        return {
+            filePath,
+            format
+        };
+    }
+    return {
+        filePath,
+        format,
+        contentPath: (0,external_node_path_.join)(root.targetDir, (0,external_node_path_.relative)(root.rootReal, resolved.real))
+    };
+}
+/**
+ * Creates and returns the default instruction file discovery gateway.
+ */ function createInstructionFileDiscoveryGateway(options) {
+    return new FileSystemInstructionFileDiscoveryGateway(options);
+}
+
 ;// CONCATENATED MODULE: ../core/src/gateways/instruction-analysis-gateway.ts
 /**
  * Gateway for analyzing repository instructions for feedback loop coverage
  */ 
 
-const MAX_INSTRUCTION_FILE_BYTES = 1_048_576;
+
+
+
 /**
- * File system implementation of instruction analysis gateway
+ * File system implementation of instruction analysis gateway.
+ * Scans the same instruction files that instruction quality analysis
+ * discovers (the shared agentic location catalog).
  */ class FileSystemInstructionAnalysisGateway {
+    discoveryGateway;
+    constructor(discoveryGateway = createInstructionFileDiscoveryGateway()){
+        this.discoveryGateway = discoveryGateway;
+    }
     async analyzeCoverage(targetDir, scripts, tools) {
-        const instructionFiles = await this.findInstructionFiles(targetDir);
+        const { files: instructionFiles, diagnostics: discoveryDiagnostics } = await this.findInstructionFiles(targetDir);
+        const targetNames = [
+            ...scripts,
+            ...tools
+        ].map((item)=>item.name);
         const references = [];
-        const documentedTargets = new Set();
+        const unreadable = [];
         for (const file of instructionFiles){
-            const content = await file_system_utils_readTextWithinRoot(targetDir, file, MAX_INSTRUCTION_FILE_BYTES);
-            const lines = content.split("\n");
-            for (const script of scripts){
-                const scriptRefs = this.findReferencesInContent(script.name, content, lines, (0,external_node_path_.join)(targetDir, file), targetDir);
-                if (scriptRefs.length > 0) {
-                    references.push(...scriptRefs);
-                    documentedTargets.add(script.name);
-                }
-            }
-            for (const tool of tools){
-                const toolRefs = this.findReferencesInContent(tool.name, content, lines, (0,external_node_path_.join)(targetDir, file), targetDir);
-                if (toolRefs.length > 0) {
-                    references.push(...toolRefs);
-                    documentedTargets.add(tool.name);
-                }
+            const content = await this.readInstructionFile(targetDir, file);
+            if (content.ok) {
+                references.push(...this.findReferencesInFile(targetDir, file, content.text, targetNames));
+            } else {
+                unreadable.push({
+                    ruleId: INSTRUCTION_PARSE_ERROR_RULE_ID,
+                    message: `Could not read ${file.reportedPath} (${content.reason}), so it was not checked.`
+                });
             }
         }
+        const diagnostics = [
+            ...discoveryDiagnostics,
+            ...unreadable
+        ];
+        const documentedTargets = new Set(references.map((reference)=>reference.target));
         const mandatoryScripts = scripts.filter((s)=>s.isMandatory);
         const mandatoryTools = tools.filter((t)=>t.isMandatory);
         const allMandatory = [
@@ -53823,6 +54881,7 @@ const MAX_INSTRUCTION_FILE_BYTES = 1_048_576;
             missingInInstructions,
             documentedInInstructions,
             references,
+            diagnostics,
             summary: {
                 totalMandatory,
                 totalDocumented,
@@ -53830,31 +54889,42 @@ const MAX_INSTRUCTION_FILE_BYTES = 1_048_576;
             }
         };
     }
-    async safePathExists(targetDir, relativePath) {
+    async findInstructionFiles(targetDir) {
+        const diagnostics = [];
+        const discovered = await this.discoveryGateway.discoverInstructionFiles(targetDir, (diagnostic)=>diagnostics.push(diagnostic));
+        return {
+            files: discovered.map((file)=>({
+                    reportedPath: (0,external_node_path_.relative)(targetDir, file.filePath),
+                    contentPath: (0,external_node_path_.relative)(targetDir, file.contentPath ?? file.filePath)
+                })),
+            diagnostics
+        };
+    }
+    /**
+     * Reads one instruction file, or says why it could not be read (a hard
+     * link, a file over the size limit, a file that vanished), so one file
+     * that cannot be read leaves out only itself and not the whole analysis.
+     */ async readInstructionFile(targetDir, file) {
         try {
-            return await file_system_utils_pathExistsWithinRoot(targetDir, relativePath);
-        } catch  {
-            return false;
+            const text = await file_system_utils_readTextWithinRoot(targetDir, file.contentPath, MAX_INSTRUCTION_FILE_BYTES);
+            return {
+                ok: true,
+                text
+            };
+        } catch (error) {
+            return {
+                ok: false,
+                reason: error instanceof Error ? error.message : "unreadable"
+            };
         }
     }
-    async findInstructionFiles(targetDir) {
-        const files = [];
-        const copilotInstructions = (0,external_node_path_.join)(".github", "copilot-instructions.md");
-        if (await this.safePathExists(targetDir, copilotInstructions)) {
-            files.push(copilotInstructions);
-        }
-        const instructionsDir = (0,external_node_path_.join)(".github", "instructions");
-        if (await this.safePathExists(targetDir, instructionsDir)) {
-            try {
-                const instructionFiles = await file_system_utils_listDirectoryWithinRoot(targetDir, instructionsDir);
-                for (const file of instructionFiles){
-                    if (file.isFile() && file.name.endsWith(".md")) {
-                        files.push((0,external_node_path_.join)(instructionsDir, file.name));
-                    }
-                }
-            } catch  {}
-        }
-        return files;
+    /**
+     * Finds the references to every target in one instruction file, grouped by
+     * target in the order the targets are given.
+     */ findReferencesInFile(targetDir, file, content, targetNames) {
+        const lines = content.split("\n");
+        const reportedPath = (0,external_node_path_.join)(targetDir, file.reportedPath);
+        return targetNames.flatMap((target)=>this.findReferencesInContent(target, content, lines, reportedPath, targetDir));
     }
     findReferencesInContent(target, content, lines, file, targetDir) {
         const references = [];
@@ -55718,8 +56788,6 @@ const MAX_NPMRC_BYTES = (/* unused pure expression or super */ null && (64 * 102
  * Core domain entities for SDLC feedback loop discovery and validation.
  * These types represent scripts, tools, and their mapping to SDLC phases.
  */ /**
- * SDLC feedback loop phases that scripts and tools support
- */ /**
  * Maps common script names to SDLC phases
  */ const SCRIPT_PHASE_MAPPING = {
     test: "test",
@@ -55948,322 +57016,6 @@ const PackageJsonSchema = schemas_object({
     return new FileSystemSkillFileGateway();
 }
 
-;// CONCATENATED MODULE: ../core/src/entities/agentic-location-catalog.ts
-/**
- * Canonical catalog of agentic construct locations shared by lint and doctor.
- * Pure data only — no filesystem I/O.
- */ const agentic_location_catalog_AGENTIC_LOCATION_CATALOG = [
-    // Skill lint roots
-    {
-        id: "skill-github",
-        path: ".github/skills",
-        matchKind: "directory-prefix",
-        primaryConstruct: "skill",
-        lintTarget: "skills",
-        harnessHints: [
-            "copilot"
-        ]
-    },
-    {
-        id: "skill-claude",
-        path: ".claude/skills",
-        matchKind: "directory-prefix",
-        primaryConstruct: "skill",
-        lintTarget: "skills",
-        harnessHints: [
-            "claude"
-        ]
-    },
-    {
-        id: "skill-agents",
-        path: ".agents/skills",
-        matchKind: "directory-prefix",
-        primaryConstruct: "skill",
-        lintTarget: "skills",
-        harnessHints: [
-            "shared"
-        ]
-    },
-    // Additional skill roots (SKILL.md convention, no alternate layout documented)
-    {
-        id: "skill-pi",
-        path: ".pi/skills",
-        matchKind: "directory-prefix",
-        primaryConstruct: "skill",
-        lintTarget: "skills",
-        harnessHints: [
-            "pi"
-        ]
-    },
-    {
-        id: "skill-pi-prompts",
-        path: ".pi/prompts",
-        matchKind: "directory-prefix",
-        primaryConstruct: "skill",
-        lintTarget: "skills",
-        harnessHints: [
-            "pi"
-        ]
-    },
-    // Agent lint root (dual-role: agent + instruction)
-    {
-        id: "agent-github",
-        path: ".github/agents",
-        matchKind: "directory-prefix",
-        primaryConstruct: "agent",
-        secondaryConstructs: [
-            "instruction"
-        ],
-        lintTarget: "agents",
-        harnessHints: [
-            "copilot"
-        ],
-        instructionFormat: "copilot-agent"
-    },
-    // Hook lint exact configs
-    {
-        id: "hook-copilot-agent-shell",
-        path: ".github/hooks/agent-shell/hooks.json",
-        matchKind: "exact",
-        primaryConstruct: "hook",
-        lintTarget: "hooks",
-        harnessHints: [
-            "copilot"
-        ],
-        hookPlatform: "copilot"
-    },
-    {
-        id: "hook-claude-settings",
-        path: ".claude/settings.json",
-        matchKind: "exact",
-        primaryConstruct: "hook",
-        lintTarget: "hooks",
-        harnessHints: [
-            "claude"
-        ],
-        hookPlatform: "claude"
-    },
-    {
-        id: "hook-claude-settings-local",
-        path: ".claude/settings.local.json",
-        matchKind: "exact",
-        primaryConstruct: "hook",
-        lintTarget: "hooks",
-        harnessHints: [
-            "claude"
-        ],
-        hookPlatform: "claude"
-    },
-    // Doctor-only hook directory prefixes
-    {
-        id: "hook-github-dir",
-        path: ".github/hooks",
-        matchKind: "directory-prefix",
-        primaryConstruct: "hook",
-        lintTarget: "none",
-        harnessHints: [
-            "copilot"
-        ]
-    },
-    {
-        id: "hook-claude-dir",
-        path: ".claude/hooks",
-        matchKind: "directory-prefix",
-        primaryConstruct: "hook",
-        lintTarget: "none",
-        harnessHints: [
-            "claude"
-        ]
-    },
-    // Instruction lint locations
-    {
-        id: "instruction-copilot-root",
-        path: ".github/copilot-instructions.md",
-        matchKind: "exact",
-        primaryConstruct: "instruction",
-        lintTarget: "instructions",
-        harnessHints: [
-            "copilot"
-        ],
-        instructionFormat: "copilot-instructions"
-    },
-    {
-        id: "instruction-copilot-scoped",
-        path: ".github/instructions",
-        matchKind: "directory-prefix",
-        primaryConstruct: "instruction",
-        lintTarget: "instructions",
-        harnessHints: [
-            "copilot"
-        ],
-        instructionFormat: "copilot-scoped"
-    },
-    {
-        id: "instruction-agents-md",
-        path: "AGENTS.md",
-        matchKind: "exact",
-        primaryConstruct: "instruction",
-        lintTarget: "instructions",
-        harnessHints: [
-            "shared"
-        ],
-        instructionFormat: "agents-md"
-    },
-    {
-        id: "instruction-claude-md",
-        path: "CLAUDE.md",
-        matchKind: "exact",
-        primaryConstruct: "instruction",
-        lintTarget: "instructions",
-        harnessHints: [
-            "claude"
-        ],
-        instructionFormat: "claude-md"
-    },
-    // Subagent lint root
-    {
-        id: "subagent-claude",
-        path: ".claude/agents",
-        matchKind: "directory-prefix",
-        primaryConstruct: "subagent",
-        lintTarget: "subagents",
-        harnessHints: [
-            "claude"
-        ]
-    },
-    {
-        id: "agent-claude-commands",
-        path: ".claude/commands",
-        matchKind: "directory-prefix",
-        primaryConstruct: "agent",
-        lintTarget: "none",
-        harnessHints: [
-            "claude"
-        ]
-    },
-    {
-        id: "plugin-codex",
-        path: ".codex-plugin",
-        matchKind: "directory-prefix",
-        primaryConstruct: "plugin",
-        lintTarget: "none",
-        harnessHints: [
-            "codex"
-        ]
-    }
-];
-
-;// CONCATENATED MODULE: ../core/src/lib/agentic-location-matchers.ts
-/**
- * Pure path→construct matching helpers over the agentic location catalog.
- * No filesystem I/O.
- */ 
-/**
- * Normalizes a repo-relative path for catalog matching.
- * Collapses `.` / `..` segments. Returns "" when the path is absolute or
- * escapes the repository root — callers treat "" as non-matching.
- */ function isAbsoluteRepoPath(normalized) {
-    // POSIX absolute, UNC-style leading slash after backslash conversion,
-    // and Windows drive-letter absolute (C:/..., d:\...).
-    return normalized.startsWith("/") || /^[A-Za-z]:(\/|$)/.test(normalized);
-}
-function normalizeRepoRelativePath(path) {
-    const normalized = path.replaceAll("\\", "/");
-    if (isAbsoluteRepoPath(normalized)) {
-        return "";
-    }
-    const resolved = [];
-    for (const segment of normalized.split("/")){
-        if (segment === "" || segment === ".") {
-            continue;
-        }
-        if (segment === ".." && resolved.length === 0) {
-            return "";
-        }
-        if (segment === "..") {
-            resolved.pop();
-            continue;
-        }
-        resolved.push(segment);
-    }
-    return resolved.join("/");
-}
-function matchesLocationEntry(path, entry) {
-    const normalized = normalizeRepoRelativePath(path);
-    if (entry.matchKind === "exact") {
-        return normalized === entry.path;
-    }
-    return normalized === entry.path || normalized.startsWith(`${entry.path}/`);
-}
-function entriesMatchingPath(path, catalog = AGENTIC_LOCATION_CATALOG) {
-    return catalog.filter((entry)=>matchesLocationEntry(path, entry));
-}
-function specificityScore(entry) {
-    // Exact matches outrank any prefix; longer prefixes outrank shorter ones.
-    const kindBonus = entry.matchKind === "exact" ? 1_000_000 : 0;
-    return kindBonus + entry.path.length;
-}
-function bestMatchingEntry(path, catalog = AGENTIC_LOCATION_CATALOG) {
-    const matches = entriesMatchingPath(path, catalog);
-    if (matches.length === 0) {
-        return null;
-    }
-    let best = matches[0];
-    let bestScore = specificityScore(best);
-    for(let i = 1; i < matches.length; i++){
-        const candidate = matches[i];
-        const score = specificityScore(candidate);
-        if (score > bestScore) {
-            best = candidate;
-            bestScore = score;
-        }
-    }
-    return best;
-}
-function primaryConstructTypeForPath(path, catalog = AGENTIC_LOCATION_CATALOG) {
-    return bestMatchingEntry(path, catalog)?.primaryConstruct ?? null;
-}
-function constructTypesForPath(path, catalog = AGENTIC_LOCATION_CATALOG) {
-    const best = bestMatchingEntry(path, catalog);
-    if (!best) {
-        return [];
-    }
-    const secondary = best.secondaryConstructs ?? [];
-    if (secondary.length === 0) {
-        return [
-            best.primaryConstruct
-        ];
-    }
-    return [
-        best.primaryConstruct,
-        ...secondary
-    ];
-}
-function lintTargetEntries(target, catalog = agentic_location_catalog_AGENTIC_LOCATION_CATALOG) {
-    return catalog.filter((entry)=>entry.lintTarget === target);
-}
-function skillDirectoryRoots(catalog = agentic_location_catalog_AGENTIC_LOCATION_CATALOG) {
-    return lintTargetEntries("skills", catalog).filter((entry)=>entry.matchKind === "directory-prefix").map((entry)=>entry.path);
-}
-function agentDirectoryRoots(catalog = AGENTIC_LOCATION_CATALOG) {
-    return lintTargetEntries("agents", catalog).filter((entry)=>entry.matchKind === "directory-prefix").map((entry)=>entry.path);
-}
-function subagentDirectoryRoots(catalog = AGENTIC_LOCATION_CATALOG) {
-    return lintTargetEntries("subagents", catalog).filter((entry)=>entry.matchKind === "directory-prefix").map((entry)=>entry.path);
-}
-function isHookConfigEntry(entry) {
-    return entry.matchKind === "exact" && entry.hookPlatform != null;
-}
-function hookConfigPaths(catalog = AGENTIC_LOCATION_CATALOG) {
-    return lintTargetEntries("hooks", catalog).filter(isHookConfigEntry).map((entry)=>({
-            relativePath: entry.path,
-            platform: entry.hookPlatform
-        }));
-}
-function instructionDiscoveryEntries(catalog = agentic_location_catalog_AGENTIC_LOCATION_CATALOG) {
-    return catalog.filter((entry)=>entry.instructionFormat != null);
-}
-
 ;// CONCATENATED MODULE: ../core/src/gateways/skill-lint-gateway.ts
 /**
  * Gateway for skill lint file system operations.
@@ -56532,87 +57284,78 @@ const MAX_WORKFLOW_FILE_BYTES = 1_048_576;
     return patterns.includes(actionName);
 }
 /**
- * Iterates over all steps in a workflow that have a "uses" field
+ * Narrows to a truthy, object-typed value (arrays included).
+ */ function isObjectLike(value) {
+    return Boolean(value) && typeof value === "object";
+}
+/**
+ * Returns every step object in every job of a workflow, in job and step order.
+ * Anything that is not an object (a missing "jobs" map, a job without a
+ * "steps" array, a non-object step) contributes no steps.
  * @param workflow The parsed workflow object
- * @param callback Function to call for each step with a "uses" field
- */ function forEachWorkflowStep(workflow, callback) {
-    if (!workflow || typeof workflow !== "object") {
-        return;
-    }
-    const jobs = workflow.jobs;
-    if (!jobs || typeof jobs !== "object") {
-        return;
+ */ function workflowStepObjects(workflow) {
+    if (!isObjectLike(workflow) || !isObjectLike(workflow.jobs)) {
+        return [];
     }
-    for (const job of Object.values(jobs)){
-        if (!job || typeof job !== "object") {
-            continue;
-        }
-        const steps = job.steps;
-        if (!Array.isArray(steps)) {
-            continue;
-        }
-        for (const step of steps){
-            if (!step || typeof step !== "object") {
-                continue;
-            }
-            const stepObj = step;
-            const uses = stepObj.uses;
-            if (typeof uses === "string") {
-                const withConfig = stepObj.with;
-                callback({
-                    uses,
-                    with: withConfig && typeof withConfig === "object" ? withConfig : undefined
-                });
+    return Object.values(workflow.jobs).filter(isObjectLike).flatMap((job)=>Array.isArray(job.steps) ? job.steps.filter(isObjectLike) : []);
+}
+/**
+ * Reads a step's "with" configuration, ignoring anything that is not an object
+ */ function toWithConfig(value) {
+    return isObjectLike(value) ? value : undefined;
+}
+/**
+ * Returns all steps in a workflow that have a "uses" field
+ * @param workflow The parsed workflow object
+ */ function workflowUsesSteps(workflow) {
+    return workflowStepObjects(workflow).flatMap((step)=>typeof step.uses === "string" ? [
+            {
+                uses: step.uses,
+                with: toWithConfig(step.with)
             }
-        }
-    }
+        ] : []);
+}
+/**
+ * Builds the key under which a run step is recorded in the set of existing
+ * workflow steps. Run steps have no "uses" field, so they are matched by
+ * their command.
+ * @example "npm ci" -> "run-command:npm ci"
+ */ function runCommandKey(command) {
+    return `run-command:${command.trim()}`;
 }
 /**
  * Extracts all steps from a workflow (including steps without "uses")
  * @param workflow The parsed workflow object
  * @returns Array of step details
  */ function extractAllWorkflowSteps(workflow) {
-    const steps = [];
-    if (!workflow || typeof workflow !== "object") {
-        return steps;
-    }
-    const jobs = workflow.jobs;
-    if (!jobs || typeof jobs !== "object") {
-        return steps;
+    return workflowStepObjects(workflow).map((step)=>({
+            name: typeof step.name === "string" ? step.name : undefined,
+            uses: typeof step.uses === "string" ? step.uses : undefined,
+            with: toWithConfig(step.with)
+        }));
+}
+/**
+ * The key a step contributes to the set of existing workflow steps: its action
+ * name when it uses an action, otherwise its run command key.
+ */ function existingActionKeys(step) {
+    if (typeof step.uses === "string") {
+        return [
+            parseActionName(step.uses)
+        ];
     }
-    for (const job of Object.values(jobs)){
-        if (!job || typeof job !== "object") {
-            continue;
-        }
-        const jobSteps = job.steps;
-        if (!Array.isArray(jobSteps)) {
-            continue;
-        }
-        for (const step of jobSteps){
-            if (!step || typeof step !== "object") {
-                continue;
-            }
-            const stepObj = step;
-            const withConfig = stepObj.with;
-            steps.push({
-                name: typeof stepObj.name === "string" ? stepObj.name : undefined,
-                uses: typeof stepObj.uses === "string" ? stepObj.uses : undefined,
-                with: withConfig && typeof withConfig === "object" ? withConfig : undefined
-            });
-        }
+    if (typeof step.run === "string") {
+        return [
+            runCommandKey(step.run)
+        ];
     }
-    return steps;
+    return [];
 }
 /**
  * Extracts existing setup actions from a parsed workflow
  * @param workflow The parsed workflow object
- * @returns Set of action names already present
+ * @returns Set of action names already present, plus a runCommandKey for each run step
  */ function getExistingActionsFromWorkflow(workflow) {
-    const actions = new Set();
-    forEachWorkflowStep(workflow, (step)=>{
-        actions.add(parseActionName(step.uses));
-    });
-    return actions;
+    return new Set(workflowStepObjects(workflow).flatMap(existingActionKeys));
 }
 /**
  * Identifies candidates that are missing from an existing workflow
@@ -56620,24 +57363,14 @@ const MAX_WORKFLOW_FILE_BYTES = 1_048_576;
  * @param existingActions Actions already present in the workflow
  * @returns Candidates that need to be added
  */ function findMissingCandidates(candidates, existingActions) {
-    return candidates.filter((candidate)=>!existingActions.has(candidate.action));
+    return candidates.filter((candidate)=>candidate.run ? !existingActions.has(runCommandKey(candidate.run)) : !existingActions.has(candidate.action));
 }
 /**
  * Merges candidates from multiple sources, with earlier sources taking precedence
  * @param candidateSources Arrays of candidates, in order of precedence
  * @returns Merged and deduplicated candidates
  */ function mergeCandidates(...candidateSources) {
-    const result = [];
-    const seen = new Set();
-    for (const candidates of candidateSources){
-        for (const candidate of candidates){
-            if (!seen.has(candidate.action)) {
-                seen.add(candidate.action);
-                result.push(candidate);
-            }
-        }
-    }
-    return result;
+    return deduplicateCandidates(candidateSources.flat());
 }
 /**
  * Extracts version from a "uses" string
@@ -56653,19 +57386,16 @@ const MAX_WORKFLOW_FILE_BYTES = 1_048_576;
  * @param workflow The parsed workflow object
  * @returns Array of action references with name and version
  */ function extractActionsFromWorkflow(workflow) {
-    const actions = [];
-    forEachWorkflowStep(workflow, (step)=>{
-        const name = parseActionName(step.uses);
+    return workflowUsesSteps(workflow).flatMap((step)=>{
         const version = parseActionVersion(step.uses);
         // Skip actions without versions - these are incomplete references
-        if (version) {
-            actions.push({
-                name,
+        return version ? [
+            {
+                name: parseActionName(step.uses),
                 version
-            });
-        }
+            }
+        ] : [];
     });
-    return actions;
 }
 /**
  * Extracts setup step candidates from a parsed workflow based on action patterns
@@ -56673,19 +57403,17 @@ const MAX_WORKFLOW_FILE_BYTES = 1_048_576;
  * @param patterns List of action patterns to detect
  * @returns Array of setup step candidates
  */ function extractSetupStepsFromWorkflow(workflow, patterns) {
-    const candidates = [];
-    forEachWorkflowStep(workflow, (step)=>{
+    return workflowUsesSteps(workflow).flatMap((step)=>{
         const action = parseActionName(step.uses);
-        if (isSetupAction(action, patterns)) {
-            candidates.push({
+        return isSetupAction(action, patterns) ? [
+            {
                 action,
                 version: parseActionVersion(step.uses),
                 config: step.with,
                 source: "workflow"
-            });
-        }
+            }
+        ] : [];
     });
-    return candidates;
 }
 /**
  * Deduplicates candidates by action name, keeping the first occurrence
@@ -56719,9 +57447,16 @@ const COPILOT_SETUP_WORKFLOW_FILENAMES = [
 const file_system_workflow_gateway_MAX_WORKFLOW_FILE_BYTES = 1024 * 1024;
 class FileSystemWorkflowGateway {
     cwd;
-    config = null;
-    constructor(cwd){
+    config;
+    /**
+     * @param cwd Directory the configuration is loaded from (defaults to
+     * process.cwd()), unless `config` is given
+     * @param config A configuration loaded by the caller. The gateway uses it
+     * as it is and does not read the configuration file itself, so a caller
+     * that also needs the configuration reads the file once for both.
+     */ constructor(cwd, config){
         this.cwd = cwd;
+        this.config = config ?? null;
     }
     async getConfig() {
         if (!this.config) {
@@ -56792,6 +57527,13 @@ class FileSystemWorkflowGateway {
 function createWorkflowGateway(cwd) {
     return new FileSystemWorkflowGateway(cwd);
 }
+/**
+ * Creates a workflow gateway that scans workflows with a configuration the
+ * caller has already loaded, so the configuration file is read once and the
+ * gateway and the caller cannot see two different versions of it.
+ */ function createWorkflowGatewayWithConfig(config) {
+    return new FileSystemWorkflowGateway(undefined, config);
+}
 
 ;// CONCATENATED MODULE: ../core/src/gateways/workflow-gateway.ts
 /**
@@ -56820,7 +57562,8 @@ function createWorkflowGateway(cwd) {
 ;// CONCATENATED MODULE: ./src/tools/types.ts
 /**
  * Shared types and utilities for MCP tool handlers.
- */ /**
+ */ 
+/**
  * Creates an error response for MCP tools.
  */ function types_errorResponse(error) {
     return {
@@ -56832,9 +57575,23 @@ function createWorkflowGateway(cwd) {
                     error
                 })
             }
-        ]
+        ],
+        isError: true
     };
 }
+/**
+ * Returns an error response when the target path is missing or is not a
+ * directory, or null when it is a directory the tool can operate on.
+ */ async function validateTargetDirectory(dir) {
+    const dirStat = await (0,promises_.stat)(dir).catch(()=>null);
+    if (dirStat === null) {
+        return types_errorResponse(`Target directory does not exist: ${dir}`);
+    }
+    if (!dirStat.isDirectory()) {
+        return types_errorResponse(`Target path is not a directory: ${dir}`);
+    }
+    return null;
+}
 /**
  * Creates a success response for MCP tools.
  */ function successResponse(data) {
@@ -56859,7 +57616,6 @@ function createWorkflowGateway(cwd) {
 
 
 
-
 /**
  * Parses a workflow file and extracts action references.
  */ async function parseWorkflowFile(rootDir, relativePath) {
@@ -56891,9 +57647,9 @@ function createWorkflowGateway(cwd) {
  */ const analyzeActionVersionsHandler = async (args)=>{
     try {
         const dir = args.targetDir || process.cwd();
-        const dirStat = await (0,promises_.stat)(dir).catch(()=>null);
-        if (dirStat === null || !dirStat.isDirectory()) {
-            return types_errorResponse(`Target directory does not exist: ${dir}`);
+        const targetDirError = await validateTargetDirectory(dir);
+        if (targetDirError !== null) {
+            return targetDirError;
         }
         const workflowsRelativeDir = (0,external_node_path_.join)(".github", "workflows");
         if (!await file_system_utils_pathExistsWithinRoot(dir, workflowsRelativeDir)) {
@@ -56939,101 +57695,699 @@ function createWorkflowGateway(cwd) {
 ;// CONCATENATED MODULE: ../core/src/entities/source-position.ts
 /**
  * Pure helpers for mapping string offsets to 1-based line/column positions.
- */ /** 1-based line and column within a text document */ /**
- * Maps a 0-based string offset into a 1-based line and column.
+ */ /** 1-based line and column within a text document */ const LINE_FEED = 0x0a;
+/**
+ * Indexes the line starts of a content once, and answers each offset with a
+ * binary search, so mapping many offsets of one content costs the length of
+ * the content plus a logarithm per offset, not a rescan from the start.
  * Offsets are clamped to [0, content.length]. Newlines (`\n`) advance the line.
+ *
+ * @param countSteps Told one step per character when the index is built, and
+ * one per comparison when an offset is answered, so a test can show that the
+ * work stays linear and logarithmic and not quadratic
+ */ function createSourcePositionIndex(content, countSteps) {
+    const lineStarts = [
+        0
+    ];
+    for(let i = 0; i < content.length; i += 1){
+        if (content.charCodeAt(i) === LINE_FEED) {
+            lineStarts.push(i + 1);
+        }
+    }
+    countSteps?.(content.length);
+    return (offset)=>{
+        const safeOffset = Math.max(0, Math.min(offset, content.length));
+        let low = 0;
+        let high = lineStarts.length - 1;
+        countSteps?.(1);
+        while(low < high){
+            countSteps?.(1);
+            const middle = low + high + 1 >> 1;
+            if ((lineStarts[middle] ?? 0) <= safeOffset) {
+                low = middle;
+            } else {
+                high = middle - 1;
+            }
+        }
+        return {
+            line: low + 1,
+            column: safeOffset - (lineStarts[low] ?? 0) + 1
+        };
+    };
+}
+/**
+ * Maps a 0-based string offset into a 1-based line and column. To map many
+ * offsets of the same content, build one index with createSourcePositionIndex.
  */ function offsetToSourcePosition(content, offset) {
-    const safeOffset = Math.max(0, Math.min(offset, content.length));
-    let line = 1;
-    let column = 1;
-    for(let i = 0; i < safeOffset; i++){
-        if (content[i] === "\n") {
-            line += 1;
-            column = 1;
-        } else {
-            column += 1;
+    return createSourcePositionIndex(content)(offset);
+}
+
+;// CONCATENATED MODULE: ../core/src/entities/external-import-message.ts
+/**
+ * The one wording for a Claude `@import` that resolves outside the working
+ * directory, shared by lint (instruction/import-escape) and doctor
+ * (external-claude-import) so the two cannot drift apart.
+ */ /**
+ * - `outside-working-directory`: an absolute path outside the repository, or a
+ *   relative path that leaves it. Observed: in headless runs it was not loaded
+ *   (Claude Code 2.1.316, absolute path outside the working directory).
+ * - `home`: a `~/` path. Claude Code's documentation says it is external, but
+ *   that case was not run in testing, so the message must not claim it was.
+ */ const MOVE_ADVICE = "Move the file into the repo, or import it from ~/.claude/CLAUDE.md instead.";
+const OBSERVATION_BY_KIND = {
+    "outside-working-directory": "In headless, `-p` or CI runs it was not loaded in testing (Claude Code 2.1.316).",
+    home: "This `~/` case is docs-based and was not observed in testing."
+};
+function externalImportMessage(path, kind) {
+    return `External import: \`${path}\` resolves outside the working directory. Claude Code loads it only after a one-time approval in an interactive session (docs: memory, 'Import additional files'). ${OBSERVATION_BY_KIND[kind]} ${MOVE_ADVICE}`;
+}
+
+;// CONCATENATED MODULE: ../core/src/gateways/read-regular-file-no-follow.ts
+/**
+ * Bounded, verified reads of a single regular file.
+ *
+ * Unlike `readFileNoFollow`, which throws, `readRegularFileNoFollow` reports
+ * every refusal as a value, bounds the bytes it reads, and verifies the opened
+ * file is the file it was asked to read.
+ */ 
+
+function read_regular_file_no_follow_isEloopError(error) {
+    return error instanceof Error && "code" in error && error.code === "ELOOP";
+}
+const nodeFsPort = {
+    open: (path, flags)=>(0,promises_.open)(path, flags),
+    lstat: (path)=>(0,promises_.lstat)(path)
+};
+const read_regular_file_no_follow_READ_CHUNK_BYTES = 64 * 1024;
+/**
+ * Opening a named pipe for reading waits for a writer. With O_NONBLOCK the
+ * open returns at once, and the check on the open descriptor then refuses
+ * anything that is not a regular file. It has no effect on a regular file.
+ */ const NON_BLOCKING = external_node_fs_.constants.O_NONBLOCK ?? 0;
+function isSameFile(a, b) {
+    return a.dev === b.dev && a.ino === b.ino;
+}
+function platformHasKernelNoFollow() {
+    return typeof external_node_fs_.constants.O_NOFOLLOW === "number" && external_node_fs_.constants.O_NOFOLLOW !== 0;
+}
+function hasKernelNoFollow(fs) {
+    return fs.kernelNoFollow ?? platformHasKernelNoFollow();
+}
+/**
+ * Without kernel O_NOFOLLOW support, a symlink is rejected up front with lstat.
+ */ async function isSymlinkWithoutKernelSupport(fs, filePath) {
+    if (hasKernelNoFollow(fs)) {
+        return false;
+    }
+    return (await fs.lstat(filePath)).isSymbolicLink();
+}
+async function openForBoundedRead(fs, filePath) {
+    try {
+        if (await isSymlinkWithoutKernelSupport(fs, filePath)) {
+            return {
+                failure: "symlink"
+            };
         }
+        const flags = (hasKernelNoFollow(fs) ? external_node_fs_.constants.O_RDONLY | external_node_fs_.constants.O_NOFOLLOW : external_node_fs_.constants.O_RDONLY) | NON_BLOCKING;
+        return {
+            handle: await fs.open(filePath, flags)
+        };
+    } catch (error) {
+        return {
+            failure: read_regular_file_no_follow_isEloopError(error) ? "symlink" : "unreadable"
+        };
+    }
+}
+/**
+ * Reads at most maxBytes + 1 bytes, so a file that grows after it was
+ * measured can never make the read unbounded. Returns null when the file
+ * holds more than maxBytes.
+ */ async function readAtMost(handle, maxBytes) {
+    const chunks = [];
+    let total = 0;
+    while(true){
+        const want = Math.min(read_regular_file_no_follow_READ_CHUNK_BYTES, maxBytes + 1 - total);
+        const chunk = Buffer.alloc(want);
+        const { bytesRead } = await handle.read(chunk, 0, want, null);
+        if (bytesRead === 0) {
+            return Buffer.concat(chunks).toString("utf8");
+        }
+        chunks.push(chunk.subarray(0, bytesRead));
+        total += bytesRead;
+        if (total > maxBytes) {
+            return null;
+        }
+    }
+}
+/**
+ * Verifies the opened descriptor is a plain regular file that is still the
+ * file at the path (and the file that was checked earlier, when an identity
+ * was recorded). Returns the failure, or null when the file is acceptable.
+ */ async function checkOpenedFile(fs, handle, filePath, maxBytes, expectedIdentity) {
+    const opened = await handle.stat();
+    if (!opened.isFile()) {
+        return "not-regular";
+    }
+    // Defense in depth: a hard link may alias a file outside the root. This
+    // only fires locally (for example pnpm stores or `cp -al` trees).
+    if (opened.nlink > 1) {
+        return "hard-linked";
+    }
+    if (expectedIdentity !== undefined && !isSameFile(opened, expectedIdentity)) {
+        return "identity-mismatch";
+    }
+    const atPath = await fs.lstat(filePath);
+    if (!atPath.isFile() || !isSameFile(opened, atPath)) {
+        return "identity-mismatch";
+    }
+    return opened.size > maxBytes ? "too-large" : null;
+}
+/**
+ * Applies the checks of readRegularFileNoFollow (no symlink at the final
+ * component, a plain regular file, a single hard link, the file now at the
+ * path, within the size cap) to a file without reading its content. Returns
+ * the refusal, or null when the file would be read.
+ */ async function checkRegularFileNoFollow(filePath, maxBytes, options = {}) {
+    const fs = options.fs ?? nodeFsPort;
+    const opened = await openForBoundedRead(fs, filePath);
+    if ("failure" in opened) {
+        return opened.failure;
+    }
+    const { handle } = opened;
+    try {
+        return await checkOpenedFile(fs, handle, filePath, maxBytes, options.expectedIdentity);
+    } catch  {
+        return "unreadable";
+    } finally{
+        await handle.close().catch(()=>undefined);
+    }
+}
+/**
+ * Reads a regular file without following a symlink at the final path
+ * component, never throwing for an unacceptable file.
+ *
+ * Opens with O_NOFOLLOW (an ELOOP is a "symlink" outcome), checks on the open
+ * descriptor that it is a plain regular file within the size cap and the same
+ * file that is currently at the path, then reads at most maxBytes + 1 bytes.
+ * Pass the real (symlink-free) path of a file inside the root: O_NOFOLLOW
+ * protects only the final component.
+ */ async function readRegularFileNoFollow(filePath, maxBytes, options = {}) {
+    const fs = options.fs ?? nodeFsPort;
+    const opened = await openForBoundedRead(fs, filePath);
+    if ("failure" in opened) {
+        return {
+            ok: false,
+            reason: opened.failure
+        };
+    }
+    const { handle } = opened;
+    try {
+        const failure = await checkOpenedFile(fs, handle, filePath, maxBytes, options.expectedIdentity);
+        if (failure !== null) {
+            return {
+                ok: false,
+                reason: failure
+            };
+        }
+        const content = await readAtMost(handle, maxBytes);
+        return content === null ? {
+            ok: false,
+            reason: "too-large"
+        } : {
+            ok: true,
+            content
+        };
+    } catch  {
+        return {
+            ok: false,
+            reason: "unreadable"
+        };
+    } finally{
+        await handle.close().catch(()=>undefined);
     }
-    return {
-        line,
-        column
-    };
 }
 
-;// CONCATENATED MODULE: ../core/src/lib/instruction-import-expand.ts
+;// CONCATENATED MODULE: ../core/src/lib/import-file-location.ts
 /**
- * Pure Claude `@` import expander that builds an ordered EffectiveDocument.
+ * Maps what the file system reported about an import target to the file to
+ * read, or to the import failure it means. Pure: no I/O.
  */ 
+function toPosix(pathValue) {
+    return pathValue.split(external_node_path_.sep).join("/");
+}
+/**
+ * The repository-relative path of an absolute target that lies strictly
+ * inside one of the roots, or the "absolute" failure when it does not.
+ */ function relativeToAnyRoot(absoluteTarget, repoRoots) {
+    for (const root of repoRoots){
+        const inside = (0,external_node_path_.relative)(root, absoluteTarget);
+        const isInside = inside !== "" && inside !== ".." && !inside.startsWith(`..${external_node_path_.sep}`);
+        if (isInside && !(0,external_node_path_.isAbsolute)(inside)) {
+            return {
+                ok: true,
+                relativePath: toPosix(inside)
+            };
+        }
+    }
+    return {
+        ok: false,
+        status: "absolute"
+    };
+}
+/**
+ * Maps a path inspection to a usable file, or to the import failure it means.
+ * Only a path that is not there is "unresolved". A path that only resolves
+ * outside the repository is a symlink violation, one the system would not let
+ * the process look at is "unreadable", and one that is there but cannot be
+ * used as a file (a directory, a named pipe, a symbolic link that loops) is
+ * "not-regular".
+ */ function toLocatedFile(rootReal, inspection) {
+    switch(inspection.status){
+        case "outside-root":
+            return {
+                ok: false,
+                status: "symlink"
+            };
+        case "unreadable":
+            return {
+                ok: false,
+                status: "unreadable"
+            };
+        case "unsupported":
+            return {
+                ok: false,
+                status: "not-regular"
+            };
+        case "missing":
+            return {
+                ok: false,
+                status: "unresolved"
+            };
+        case "ok":
+            return locateInspectedFile(rootReal, inspection);
+    }
+}
+function locateInspectedFile(rootReal, inspection) {
+    if (inspection.kind !== "file") {
+        return {
+            ok: false,
+            status: "not-regular"
+        };
+    }
+    return {
+        ok: true,
+        real: toPosix((0,external_node_path_.relative)(rootReal, inspection.real)),
+        realAbsolute: inspection.real,
+        identity: inspection.identity
+    };
+}
+function statusForReadFailure(reason) {
+    switch(reason){
+        case "symlink":
+            return "symlink";
+        case "too-large":
+            return "size-exceeded";
+        case "not-regular":
+            return "not-regular";
+        case "hard-linked":
+            return "hard-linked";
+        case "unreadable":
+        case "identity-mismatch":
+            return "unreadable";
+    }
+}
 
-const DEFAULT_MAX_IMPORT_DEPTH = 4;
-const DEFAULT_MAX_UNIQUE_FILES = 64;
-const DEFAULT_MAX_EDGES = 256;
-const DEFAULT_MAX_EMITTED_BYTES = 512_000;
-const DEFAULT_MAX_FILE_BYTES = 1_048_576;
-/** Aligns with doctor HARD_IMPORT: line-start `@path` where path includes `/`. */ const HARD_IMPORT_GLOBAL_RE = /^@([^\s@][^\s]*)/gm;
-const FENCED_CODE_RE = /^(`{3,}|~{3,})[^\r\n]*\r?\n[\s\S]*?^\1[ \t]*$/gm;
+;// CONCATENATED MODULE: ../core/src/lib/import-tokens.ts
+/**
+ * The single tokenizer for Claude `@` imports, shared by import expansion and
+ * the doctor edge parser, so lint and doctor agree on what an import is.
+ *
+ * Rules (documented for Claude Code, and for the first four observed on 2.1.316):
+ * - A token is `@` at the start of a line followed by a path: a relative or
+ *   bare file name (`@./a.md`, `@AGENTS.md`), an absolute path, or `~/`.
+ * - A backslash-escaped space stays in the path; the path ends at the first
+ *   unescaped space.
+ * - A quoted path (`@"..."`, `@'...'`) is not an import.
+ * - Inside a code span or a fenced block nothing is an import.
+ * - A token whose last segment has no extension and that does not begin with a
+ *   path prefix (`@types/node`, `@no-such-thing`) is not clearly a path
+ *   (`looksLikePath` is false): if it resolves to a file it is an import, and
+ *   if it does not, nothing should be reported.
+ */ /**
+ * Receives the number of steps a scan has just taken: lines looked at,
+ * characters walked, lookups made. It exists so a test can pin the cost of a
+ * scan exactly, without timing it.
+ */ const ignoreSteps = ()=>undefined;
+/**
+ * The lines that can close fences of one character and length, in file order.
+ * The cursor moves forward only: a lookup never goes back to a line before the
+ * one an earlier lookup stopped at, so all lookups together cost one pass.
+ */ class ClosingLines {
+    starts = [];
+    ends = [];
+    cursor = 0;
+    add(start, end) {
+        this.starts.push(start);
+        this.ends.push(end);
+    }
+    firstEndFrom(from, countSteps) {
+        const startedAt = this.cursor;
+        while(this.cursor < this.starts.length && (this.starts[this.cursor] ?? 0) < from){
+            this.cursor += 1;
+        }
+        countSteps(this.cursor - startedAt + 1);
+        return this.ends[this.cursor];
+    }
+}
+/** The closing lines, indexed by fence character and length. */ class ClosingIndex {
+    byKey = new Map();
+    add(key, start, end) {
+        const existing = this.byKey.get(key);
+        if (existing) {
+            existing.add(start, end);
+            return;
+        }
+        const created = new ClosingLines();
+        created.add(start, end);
+        this.byKey.set(key, created);
+    }
+    get(key) {
+        return this.byKey.get(key);
+    }
+}
+/**
+ * Line-start `@` and a path of non-space characters, where `\ ` (a backslash
+ * and a space) belongs to the path. The first character is not a space or `@`.
+ */ const HARD_IMPORT_RE = /^@(?![\s@])((?:\\ |\S)+)/gm;
 const INLINE_CODE_RE = /`+[^`\r\n]*`+/g;
-function resolveLimits(overrides) {
+const import_tokens_LINE_FEED = 0x0a;
+const CARRIAGE_RETURN = 0x0d;
+const LINE_SEPARATOR = 0x2028;
+const PARAGRAPH_SEPARATOR = 0x2029;
+const SPACE = 0x20;
+const TAB = 0x09;
+const BACKTICK = 0x60;
+const TILDE = 0x7e;
+const MIN_FENCE_LENGTH = 3;
+const QUOTE_OPENERS = new Set([
+    '"',
+    "'",
+    "`"
+]);
+const PATH_PREFIXES = [
+    "./",
+    "../",
+    "/",
+    "~/"
+];
+const EXTENSION_RE = /\.[A-Za-z0-9]+$/;
+function isLineTerminator(code) {
+    return code === import_tokens_LINE_FEED || code === CARRIAGE_RETURN || code === LINE_SEPARATOR || code === PARAGRAPH_SEPARATOR;
+}
+function isLineStart(content, index) {
+    return index === 0 || isLineTerminator(content.charCodeAt(index - 1));
+}
+function fenceRunLength(content, start) {
+    const code = content.charCodeAt(start);
+    if (code !== BACKTICK && code !== TILDE) {
+        return 0;
+    }
+    let end = start + 1;
+    while(content.charCodeAt(end) === code){
+        end += 1;
+    }
+    return end - start;
+}
+function skipSpacesAndTabs(content, from) {
+    let index = from;
+    while(content.charCodeAt(index) === SPACE || content.charCodeAt(index) === TAB){
+        index += 1;
+    }
+    return index;
+}
+function closingKey(code, length) {
+    return length * 2 + (code === TILDE ? 1 : 0);
+}
+/**
+ * One pass over the lines that begin with three or more fence characters.
+ * A line that is only the fence run and trailing spaces or tabs can close a
+ * fence of exactly that length, so those lines are indexed by character and
+ * length, in file order.
+ */ function collectFenceLines(content, countSteps) {
+    const fenceLines = {
+        starts: [],
+        lengths: []
+    };
+    const closers = new ClosingIndex();
+    for(let index = 0; index < content.length; index += 1){
+        if (!isLineStart(content, index)) {
+            continue;
+        }
+        const length = fenceRunLength(content, index);
+        countSteps(length + 1);
+        if (length < MIN_FENCE_LENGTH) {
+            continue;
+        }
+        fenceLines.starts.push(index);
+        fenceLines.lengths.push(length);
+        const trailingEnd = skipSpacesAndTabs(content, index + length);
+        countSteps(trailingEnd - index - length);
+        if (trailingEnd >= content.length || isLineTerminator(content.charCodeAt(trailingEnd))) {
+            closers.add(closingKey(content.charCodeAt(index), length), index, trailingEnd);
+        }
+    }
     return {
-        maxDepth: overrides?.maxDepth ?? DEFAULT_MAX_IMPORT_DEPTH,
-        maxUniqueFiles: overrides?.maxUniqueFiles ?? DEFAULT_MAX_UNIQUE_FILES,
-        maxEdges: overrides?.maxEdges ?? DEFAULT_MAX_EDGES,
-        maxEmittedBytes: overrides?.maxEmittedBytes ?? DEFAULT_MAX_EMITTED_BYTES,
-        maxFileBytes: overrides?.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES
+        fenceLines,
+        closers
     };
 }
-function toPosixRelative(pathValue) {
-    return pathValue.split(external_node_path_.sep).join("/");
+/**
+ * Finds the first carriage return or line feed at or after `from`. Calls
+ * arrive in increasing order, so the last answer is reused while it still
+ * applies and the whole scan reads each character once.
+ */ function createLineBreakFinder(content, countSteps) {
+    let answeredFrom = -1;
+    let answer = -1;
+    return (from)=>{
+        if (answeredFrom <= from && answer >= from) {
+            countSteps(1);
+            return answer;
+        }
+        let index = from;
+        while(index < content.length && content.charCodeAt(index) !== import_tokens_LINE_FEED && content.charCodeAt(index) !== CARRIAGE_RETURN){
+            index += 1;
+        }
+        countSteps(index - from + 1);
+        answeredFrom = from;
+        answer = index;
+        return index;
+    };
+}
+/**
+ * Where the body of a fence begins: the opening line must end in a line feed
+ * or a carriage return and a line feed.
+ */ function fenceBodyStart(content, infoStart, findLineBreak) {
+    const lineBreak = findLineBreak(infoStart);
+    const code = content.charCodeAt(lineBreak);
+    if (code === import_tokens_LINE_FEED) {
+        return lineBreak + 1;
+    }
+    if (code === CARRIAGE_RETURN && content.charCodeAt(lineBreak + 1) === import_tokens_LINE_FEED) {
+        return lineBreak + 2;
+    }
+    return undefined;
 }
-function isInsideCodeRegion(index, regions) {
-    return regions.some((region)=>index >= region.start && index < region.end);
+/**
+ * A fence is closed by the first line after it that is exactly as many fence
+ * characters as the opener. When no such line follows, shorter lengths are
+ * tried in turn, down to three.
+ */ function findClosingEnd(closers, code, fenceLength, bodyStart, countSteps) {
+    for(let length = fenceLength; length >= MIN_FENCE_LENGTH; length -= 1){
+        countSteps(1);
+        const closing = closers.get(closingKey(code, length));
+        const end = closing?.firstEndFrom(bodyStart, countSteps);
+        if (end !== undefined) {
+            return end;
+        }
+    }
+    return undefined;
 }
-function collectRegexRanges(content, pattern, skipInside) {
-    const regions = [];
-    for (const match of content.matchAll(pattern)){
-        if (match.index === undefined) {
+/**
+ * Finds the fenced blocks in time linear in the content. A fence that is
+ * never closed hides nothing, so a file of unclosed fences costs one lookup
+ * per fence line.
+ */ function findFencedRegions(content, countSteps) {
+    const { fenceLines, closers } = collectFenceLines(content, countSteps);
+    const findLineBreak = createLineBreakFinder(content, countSteps);
+    const regions = {
+        starts: [],
+        ends: []
+    };
+    let scanFrom = 0;
+    for(let line = 0; line < fenceLines.starts.length; line += 1){
+        const start = fenceLines.starts[line] ?? 0;
+        const length = fenceLines.lengths[line] ?? 0;
+        countSteps(1);
+        if (start < scanFrom) {
             continue;
         }
-        if (skipInside && isInsideCodeRegion(match.index, skipInside)) {
+        const bodyStart = fenceBodyStart(content, start + length, findLineBreak);
+        if (bodyStart === undefined) {
             continue;
         }
-        regions.push({
-            start: match.index,
-            end: match.index + match[0].length
-        });
+        const end = findClosingEnd(closers, content.charCodeAt(start), length, bodyStart, countSteps);
+        if (end !== undefined) {
+            regions.starts.push(start);
+            regions.ends.push(end);
+            scanFrom = end;
+        }
     }
     return regions;
 }
-function findCodeRegions(content) {
-    const fenced = collectRegexRanges(content, FENCED_CODE_RE);
-    const inline = collectRegexRanges(content, INLINE_CODE_RE, fenced);
-    return [
-        ...fenced,
-        ...inline
-    ];
+/**
+ * Answers whether an index falls inside any region, in logarithmic time per
+ * question: the regions are ordered by start, each carries the furthest end
+ * reached so far, and a binary search finds the last region that starts at or
+ * before the index.
+ */ function createRegionLookup(regions, countSteps) {
+    const furthestEnds = [];
+    let furthest = 0;
+    for (const end of regions.ends){
+        furthest = Math.max(furthest, end);
+        furthestEnds.push(furthest);
+    }
+    countSteps(furthestEnds.length);
+    return (index)=>{
+        let low = 0;
+        let high = regions.starts.length - 1;
+        let lastStartingAtOrBefore = -1;
+        while(low <= high){
+            countSteps(1);
+            const middle = low + high >> 1;
+            if ((regions.starts[middle] ?? 0) <= index) {
+                lastStartingAtOrBefore = middle;
+                low = middle + 1;
+            } else {
+                high = middle - 1;
+            }
+        }
+        return lastStartingAtOrBefore >= 0 && (furthestEnds[lastStartingAtOrBefore] ?? 0) > index;
+    };
 }
-function findImportTokens(content) {
-    const codeRegions = findCodeRegions(content);
-    const tokens = [];
-    for (const match of content.matchAll(HARD_IMPORT_GLOBAL_RE)){
-        if (match.index === undefined) {
-            continue;
+function findInlineRegions(content, isInsideFence, countSteps) {
+    const regions = {
+        starts: [],
+        ends: []
+    };
+    for (const match of content.matchAll(INLINE_CODE_RE)){
+        countSteps(1);
+        const start = match.index ?? 0;
+        if (!isInsideFence(start)) {
+            regions.starts.push(start);
+            regions.ends.push(start + match[0].length);
         }
-        const rawTarget = match[1];
-        if (!rawTarget?.includes("/")) {
-            continue;
+    }
+    return regions;
+}
+/** Merges two lists that are each ordered by start into one. */ function mergeRegionLists(first, second, countSteps) {
+    countSteps(first.starts.length + second.starts.length);
+    const merged = {
+        starts: [],
+        ends: []
+    };
+    let a = 0;
+    let b = 0;
+    while(a < first.starts.length || b < second.starts.length){
+        const takeFirst = b >= second.starts.length || a < first.starts.length && (first.starts[a] ?? 0) <= (second.starts[b] ?? 0);
+        const source = takeFirst ? first : second;
+        const position = takeFirst ? a : b;
+        merged.starts.push(source.starts[position] ?? 0);
+        merged.ends.push(source.ends[position] ?? 0);
+        if (takeFirst) {
+            a += 1;
+        } else {
+            b += 1;
         }
-        if (isInsideCodeRegion(match.index, codeRegions)) {
+    }
+    return merged;
+}
+function findCodeRegions(content, countSteps) {
+    const fenced = findFencedRegions(content, countSteps);
+    const inline = findInlineRegions(content, createRegionLookup(fenced, countSteps), countSteps);
+    return mergeRegionLists(fenced, inline, countSteps);
+}
+function looksLikePath(rawTarget) {
+    const lastSegment = rawTarget.slice(rawTarget.lastIndexOf("/") + 1);
+    return PATH_PREFIXES.some((prefix)=>rawTarget.startsWith(prefix)) || EXTENSION_RE.test(lastSegment);
+}
+function isQuoted(rawTarget) {
+    return QUOTE_OPENERS.has(rawTarget.charAt(0));
+}
+/**
+ * Finds the Claude `@path` import tokens in markdown content, ignoring
+ * fenced and inline code, quoted paths, and anything not at the start of a
+ * line.
+ */ function findImportTokens(content, countSteps = ignoreSteps) {
+    const isInsideCode = createRegionLookup(findCodeRegions(content, countSteps), countSteps);
+    const tokens = [];
+    for (const match of content.matchAll(HARD_IMPORT_RE)){
+        countSteps(1);
+        const start = match.index ?? 0;
+        const target = match[1] ?? "";
+        if (isInsideCode(start) || isQuoted(target)) {
             continue;
         }
+        const rawTarget = target.replaceAll("\\ ", " ");
         tokens.push({
-            start: match.index,
-            end: match.index + match[0].length,
-            rawTarget
+            start,
+            end: start + match[0].length,
+            rawTarget,
+            looksLikePath: looksLikePath(rawTarget)
         });
     }
     return tokens;
 }
+
+;// CONCATENATED MODULE: ../core/src/lib/instruction-import-expand.ts
+/**
+ * Claude `@` import expander that builds an ordered EffectiveDocument.
+ *
+ * It reads the file system through an injectable port (real paths, bounded
+ * reads of regular files, no symlink followed at the final component), so it
+ * is deterministic for a given tree but not pure.
+ */ 
+
+
+
+
+
+
+
+
+
+const DEFAULT_MAX_IMPORT_DEPTH = 4;
+const DEFAULT_MAX_UNIQUE_FILES = 64;
+const DEFAULT_MAX_EDGES = 256;
+const DEFAULT_MAX_EMITTED_BYTES = 512_000;
+const DEFAULT_MAX_FILE_BYTES = MAX_INSTRUCTION_FILE_BYTES;
+const nodeImportFileSystem = {
+    inspect: inspectPathWithinRoot,
+    read: (realPath, maxBytes, expectedIdentity)=>readRegularFileNoFollow(realPath, maxBytes, {
+            expectedIdentity
+        })
+};
+function resolveLimits(overrides) {
+    return {
+        maxDepth: overrides?.maxDepth ?? DEFAULT_MAX_IMPORT_DEPTH,
+        maxUniqueFiles: overrides?.maxUniqueFiles ?? DEFAULT_MAX_UNIQUE_FILES,
+        maxEdges: overrides?.maxEdges ?? DEFAULT_MAX_EDGES,
+        maxEmittedBytes: overrides?.maxEmittedBytes ?? DEFAULT_MAX_EMITTED_BYTES,
+        maxFileBytes: overrides?.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES
+    };
+}
+function toPosixRelative(pathValue) {
+    return pathValue.split(external_node_path_.sep).join("/");
+}
 function rebaseSegments(segments, offset) {
     return segments.map((segment)=>({
             ...segment,
@@ -57065,6 +58419,8 @@ function createLiteralSegment(contentOffset, sourcePath, sourceStart, text, impo
 const RULE_ID_BY_STATUS = {
     unresolved: "instruction/import-unresolved",
     "not-regular": "instruction/import-unresolved",
+    "hard-linked": "instruction/import-unresolved",
+    unreadable: "instruction/import-unresolved",
     escape: "instruction/import-escape",
     absolute: "instruction/import-escape",
     home: "instruction/import-escape",
@@ -57076,14 +58432,16 @@ const RULE_ID_BY_STATUS = {
 };
 const FAILURE_MESSAGE_BY_STATUS = {
     unresolved: (rawTarget)=>`Import target could not be resolved: ${rawTarget}`,
-    escape: (rawTarget)=>`Import target escapes the repository root: ${rawTarget}`,
-    absolute: (rawTarget)=>`Absolute import paths are not allowed: ${rawTarget}`,
-    home: (rawTarget)=>`Home-directory import paths are not allowed: ${rawTarget}`,
+    escape: (rawTarget)=>externalImportMessage(rawTarget, "outside-working-directory"),
+    absolute: (rawTarget)=>externalImportMessage(rawTarget, "outside-working-directory"),
+    home: (rawTarget)=>externalImportMessage(rawTarget, "home"),
     symlink: (rawTarget)=>`Import target path contains a symbolic link: ${rawTarget}`,
     cycle: (rawTarget)=>`Import cycle detected while resolving: ${rawTarget}`,
     "depth-exceeded": (rawTarget)=>`Import depth limit exceeded while resolving: ${rawTarget}`,
     "size-exceeded": (rawTarget)=>`Import expansion size or graph limit exceeded while resolving: ${rawTarget}`,
     "not-regular": (rawTarget)=>`Import target is not a regular file: ${rawTarget}`,
+    "hard-linked": (rawTarget)=>`Import target has more than one hard link and is not read: ${rawTarget}`,
+    unreadable: (rawTarget)=>`Import target could not be read, for example because access was denied or too many files were open: ${rawTarget}`,
     resolved: ()=>""
 };
 function ruleIdForStatus(status) {
@@ -57108,7 +58466,17 @@ function classifyPathError(error) {
     }
     return "unresolved";
 }
-function normalizeRelativeWithinRoot(importerRelativePath, rawTarget) {
+/**
+ * Classifies an import target relative to its importer without touching the
+ * file system: home-directory targets, absolute targets outside every given
+ * root, and repository-escaping targets are rejected as external; anything
+ * else yields a repository-relative POSIX path.
+ *
+ * An absolute target inside one of `repoRoots` is valid, because Claude Code
+ * loads absolute paths inside the working directory (observed on Claude Code
+ * 2.1.316). Pass every spelling of the root (its path and its real path). With
+ * no roots, every absolute target is rejected.
+ */ function normalizeRelativeWithinRoot(importerRelativePath, rawTarget, repoRoots = []) {
     if (rawTarget === "~" || rawTarget.startsWith("~/") || rawTarget.startsWith("~\\")) {
         return {
             ok: false,
@@ -57116,10 +58484,7 @@ function normalizeRelativeWithinRoot(importerRelativePath, rawTarget) {
         };
     }
     if ((0,external_node_path_.isAbsolute)(rawTarget)) {
-        return {
-            ok: false,
-            status: "absolute"
-        };
+        return relativeToAnyRoot(rawTarget, repoRoots);
     }
     const importerDir = (0,external_node_path_.dirname)(importerRelativePath);
     const joined = (0,external_node_path_.normalize)((0,external_node_path_.join)(importerDir, rawTarget));
@@ -57149,17 +58514,77 @@ function isUnsafeRootPath(rootRelativePath) {
  * Mutations stay on the session instance rather than shared parameter bags.
  */ class ExpansionSession {
     limits;
-    contentCache = new Map();
+    rootReal;
+    fileSystem;
+    /** File content keyed by real repository-relative path */ contentByReal = new Map();
+    /** Real path of every logical path already resolved */ realByLogical = new Map();
     uniqueFiles = new Set();
     edges = [];
     diagnostics = [];
+    importersAtTheLimit = new Set();
+    tokensAttempted = 0;
     emittedBytes = 0;
-    constructor(limits){
+    constructor(limits, rootReal, fileSystem){
         this.limits = limits;
+        this.rootReal = rootReal;
+        this.fileSystem = fileSystem;
+    }
+    /** Every spelling of the repository root an absolute import may use. */ rootSpellings(repoRoot) {
+        return [
+            repoRoot,
+            this.rootReal
+        ];
     }
     get edgeCount() {
         return this.edges.length;
     }
+    /**
+     * Counts a token against the edge limit. Every token counts, including
+     * one that is not clearly a path and does not resolve, so the work a file
+     * can cost is bounded by the limit and not by its size.
+     */ hasEdgeBudgetLeft() {
+        if (this.tokensAttempted >= this.limits.maxEdges) {
+            return false;
+        }
+        this.tokensAttempted += 1;
+        return true;
+    }
+    /**
+     * Reports that a size limit stopped an importer, once per importer: the
+     * first token it could not expand carries the diagnostic, and the tokens
+     * after it are left alone without one each.
+     */ recordLimitAtToken(importer, token, message) {
+        if (this.importersAtTheLimit.has(importer)) {
+            return;
+        }
+        this.importersAtTheLimit.add(importer);
+        this.recordFailure(importer, token, "size-exceeded", undefined, message);
+    }
+    /**
+     * Reports that the importer has more `@` tokens than the limit, the cause
+     * of a stop that is neither a file size nor a graph size.
+     */ recordTokenLimitAtToken(importer, token) {
+        this.recordLimitAtToken(importer, token, `Too many @ tokens (the limit is ${this.limits.maxEdges}), so this import and the ones after it in ${importer} were not expanded: ${token.rawTarget}`);
+    }
+    /**
+     * Reports that the emit budget cut the text of an importer short, from the
+     * offset where the text stopped to its end. An importer already reported
+     * for hitting a size limit is not reported again. The budget is spent once
+     * it has cut text, so no importer is expanded again after this.
+     */ recordClippedContent(importer, stoppedAt, contentLength) {
+        if (this.importersAtTheLimit.has(importer)) {
+            return;
+        }
+        this.diagnostics.push({
+            ruleId: RULE_ID_BY_STATUS["size-exceeded"],
+            message: `Effective instruction content stopped at ${this.limits.maxEmittedBytes} characters, so the rest of this file was not analyzed.`,
+            filePath: importer,
+            range: {
+                start: stoppedAt,
+                end: contentLength
+            }
+        });
+    }
     get remainingEmitBudget() {
         return this.limits.maxEmittedBytes - this.emittedBytes;
     }
@@ -57176,7 +58601,7 @@ function isUnsafeRootPath(rootRelativePath) {
             ]
         };
     }
-    recordEdge(edge) {
+    recordEdge(edge, message) {
         this.edges.push(edge);
         // Failures always carry ruleId; resolved edges do not.
         if (!edge.ruleId) {
@@ -57184,12 +58609,12 @@ function isUnsafeRootPath(rootRelativePath) {
         }
         this.diagnostics.push({
             ruleId: edge.ruleId,
-            message: messageForFailure(edge.status, edge.rawTarget),
+            message: message ?? messageForFailure(edge.status, edge.rawTarget),
             filePath: edge.importer,
             range: edge.tokenRange
         });
     }
-    recordFailure(importer, token, status, target) {
+    recordFailure(importer, token, status, target, message) {
         this.recordEdge({
             importer,
             tokenRange: {
@@ -57200,7 +58625,7 @@ function isUnsafeRootPath(rootRelativePath) {
             target,
             status,
             ruleId: ruleIdForStatus(status)
-        });
+        }, message);
     }
     recordResolved(importer, token, target) {
         this.recordEdge({
@@ -57244,65 +58669,65 @@ function isUnsafeRootPath(rootRelativePath) {
             complete: false
         };
     }
-    async readFile(repoRoot, relativePath) {
-        const cached = this.contentCache.get(relativePath);
-        if (cached !== undefined) {
+    /**
+     * Resolves a logical repository-relative path to a real file inside the
+     * repository (following symlinks that stay inside it) and reads it. A
+     * file is identified by its real path everywhere: content, the unique-file
+     * budget, cycle detection and the base for the imports it contains.
+     */ async readFile(repoRoot, relativePath) {
+        const known = this.realByLogical.get(relativePath);
+        const knownContent = known === undefined ? undefined : this.contentByReal.get(known);
+        if (known !== undefined && knownContent !== undefined) {
             return {
                 ok: true,
-                content: cached
+                content: knownContent,
+                real: known
             };
         }
-        try {
-            await resolvePathWithinRoot(repoRoot, relativePath);
-        } catch (error) {
-            return {
-                ok: false,
-                status: classifyPathError(error)
-            };
+        const located = await this.locate(repoRoot, relativePath);
+        if (!located.ok) {
+            return located;
         }
-        try {
-            const stats = await file_system_utils_statWithinRoot(repoRoot, relativePath);
-            if (stats.isSymbolicLink) {
-                return {
-                    ok: false,
-                    status: "symlink"
-                };
-            }
-            if (!stats.isFile) {
-                return {
-                    ok: false,
-                    status: "not-regular"
-                };
-            }
-        } catch (error) {
-            return {
-                ok: false,
-                status: classifyPathError(error)
-            };
-        }
-        const isNewUnique = !this.uniqueFiles.has(relativePath);
+        const isNewUnique = !this.uniqueFiles.has(located.real);
         if (isNewUnique && this.uniqueFiles.size >= this.limits.maxUniqueFiles) {
             return {
                 ok: false,
                 status: "size-exceeded"
             };
         }
+        const cached = this.contentByReal.get(located.real);
+        const content = cached ?? await this.readLocated(located);
+        if (typeof content !== "string") {
+            return content;
+        }
+        this.contentByReal.set(located.real, content);
+        this.uniqueFiles.add(located.real);
+        this.realByLogical.set(relativePath, located.real);
+        return {
+            ok: true,
+            content,
+            real: located.real
+        };
+    }
+    async locate(repoRoot, relativePath) {
+        let absolutePath;
         try {
-            const content = await file_system_utils_readTextWithinRoot(repoRoot, relativePath, this.limits.maxFileBytes);
-            this.contentCache.set(relativePath, content);
-            if (isNewUnique) {
-                this.uniqueFiles.add(relativePath);
-            }
-            return {
-                ok: true,
-                content
-            };
+            absolutePath = await resolvePathWithinRoot(repoRoot, relativePath);
         } catch (error) {
             return {
                 ok: false,
                 status: classifyPathError(error)
             };
         }
+        const inspection = await this.fileSystem.inspect(this.rootReal, absolutePath);
+        return toLocatedFile(this.rootReal, inspection);
+    }
+    async readLocated(located) {
+        const outcome = await this.fileSystem.read(located.realAbsolute, this.limits.maxFileBytes, located.identity);
+        return outcome.ok ? outcome.content : {
+            ok: false,
+            status: statusForReadFailure(outcome.reason)
+        };
     }
 }
 class ContentBuilder {
@@ -57340,15 +58765,30 @@ class ContentBuilder {
 }
 function emitSourceSlice(session, builder, sourcePath, content, from, to, importChain) {
     if (to <= from) {
-        return true;
+        return {
+            complete: true,
+            stoppedAt: from
+        };
     }
     const { emitted, complete } = session.takeEmitBudget(content.slice(from, to));
     builder.appendLiteral(sourcePath, from, emitted, importChain);
-    return complete;
+    return {
+        complete,
+        stoppedAt: from + emitted.length
+    };
+}
+const NON_BLANK = /\S/;
+/**
+ * Reports text the emit budget cut off, unless nothing but whitespace was
+ * lost, which no reader of the file would miss.
+ */ function recordIfClipped(session, sourcePath, content, outcome) {
+    if (!outcome.complete && NON_BLANK.test(content.slice(outcome.stoppedAt))) {
+        session.recordClippedContent(sourcePath, outcome.stoppedAt, content.length);
+    }
 }
 async function expandToken(session, repoRoot, importerPath, token, hop, stack, importChain, outputOffset) {
-    if (session.edgeCount >= session.limits.maxEdges) {
-        session.recordFailure(importerPath, token, "size-exceeded");
+    if (!session.hasEdgeBudgetLeft()) {
+        session.recordTokenLimitAtToken(importerPath, token);
         return {
             kind: "unexpanded"
         };
@@ -57360,7 +58800,7 @@ async function expandToken(session, repoRoot, importerPath, token, hop, stack, i
             kind: "unexpanded"
         };
     }
-    const normalized = normalizeRelativeWithinRoot(importerPath, token.rawTarget);
+    const normalized = normalizeRelativeWithinRoot(importerPath, token.rawTarget, session.rootSpellings(repoRoot));
     if (!normalized.ok) {
         session.recordFailure(importerPath, token, normalized.status);
         return {
@@ -57368,33 +58808,45 @@ async function expandToken(session, repoRoot, importerPath, token, hop, stack, i
         };
     }
     const targetPath = normalized.relativePath;
-    if (stack.includes(targetPath)) {
-        session.recordFailure(importerPath, token, "cycle", targetPath);
+    const readResult = await session.readFile(repoRoot, targetPath);
+    if (!readResult.ok) {
+        // `@types/node` or `@no-such-thing` at the start of a line is prose
+        // as often as an import: when it does not resolve to a file and does
+        // not look like a path, leave it alone instead of warning.
+        if (readResult.status === "unresolved" && !token.looksLikePath) {
+            return {
+                kind: "unexpanded"
+            };
+        }
+        session.recordFailure(importerPath, token, readResult.status, targetPath);
         return {
             kind: "unexpanded"
         };
     }
-    const readResult = await session.readFile(repoRoot, targetPath);
-    if (!readResult.ok) {
-        session.recordFailure(importerPath, token, readResult.status, targetPath);
+    // From here the target is identified by its real path, so two symlinks to
+    // one file are one node of the import graph and a symlink that leads back
+    // to an importer is a cycle.
+    const targetReal = readResult.real;
+    if (stack.includes(targetReal)) {
+        session.recordFailure(importerPath, token, "cycle", targetReal);
         return {
             kind: "unexpanded"
         };
     }
     if (session.isEmitBudgetExhausted()) {
-        session.recordFailure(importerPath, token, "size-exceeded", targetPath);
+        session.recordFailure(importerPath, token, "size-exceeded", targetReal);
         return {
             kind: "unexpanded"
         };
     }
-    const child = await expandContent(session, repoRoot, targetPath, readResult.content, nextHop, [
+    const child = await expandContent(session, repoRoot, targetReal, readResult.content, nextHop, [
         ...stack,
-        targetPath
+        targetReal
     ], [
         ...importChain,
-        targetPath
+        targetReal
     ]);
-    session.recordResolved(importerPath, token, targetPath);
+    session.recordResolved(importerPath, token, targetReal);
     return {
         kind: "expanded",
         content: child.content,
@@ -57406,9 +58858,9 @@ async function expandContent(session, repoRoot, sourcePath, content, hop, stack,
     const builder = new ContentBuilder();
     let cursor = 0;
     for (const token of tokens){
-        const literalOk = emitSourceSlice(session, builder, sourcePath, content, cursor, token.start, importChain);
-        if (!literalOk) {
-            session.recordFailure(sourcePath, token, "size-exceeded");
+        const literal = emitSourceSlice(session, builder, sourcePath, content, cursor, token.start, importChain);
+        if (!literal.complete) {
+            session.recordLimitAtToken(sourcePath, token);
             emitSourceSlice(session, builder, sourcePath, content, token.start, content.length, importChain);
             return builder.toResult();
         }
@@ -57416,14 +58868,15 @@ async function expandContent(session, repoRoot, sourcePath, content, hop, stack,
         if (expansion.kind === "expanded") {
             builder.appendExpanded(expansion.content, expansion.segments);
         } else {
-            const tokenOk = emitSourceSlice(session, builder, sourcePath, content, token.start, token.end, importChain);
-            if (!tokenOk) {
+            const emittedToken = emitSourceSlice(session, builder, sourcePath, content, token.start, token.end, importChain);
+            if (!emittedToken.complete) {
+                recordIfClipped(session, sourcePath, content, emittedToken);
                 return builder.toResult();
             }
         }
         cursor = token.end;
     }
-    emitSourceSlice(session, builder, sourcePath, content, cursor, content.length, importChain);
+    recordIfClipped(session, sourcePath, content, emitSourceSlice(session, builder, sourcePath, content, cursor, content.length, importChain));
     return builder.toResult();
 }
 /**
@@ -57434,15 +58887,22 @@ async function expandContent(session, repoRoot, sourcePath, content, hop, stack,
     if (isUnsafeRootPath(rootRelativePath)) {
         throw new Error(`Root path is outside repository root: ${input.rootRelativePath}`);
     }
-    const session = new ExpansionSession(limits);
+    const rootReal = await (0,promises_.realpath)(input.repoRoot).catch(()=>null);
+    if (rootReal === null) {
+        throw new Error(`Unable to read root instruction file ${rootRelativePath}: unresolved`);
+    }
+    const session = new ExpansionSession(limits, rootReal, {
+        ...nodeImportFileSystem,
+        ...input.fileSystem
+    });
     const rootRead = await session.readFile(input.repoRoot, rootRelativePath);
     if (!rootRead.ok) {
         throw new Error(`Unable to read root instruction file ${rootRelativePath}: ${rootRead.status}`);
     }
-    const expanded = await expandContent(session, input.repoRoot, rootRelativePath, rootRead.content, 0, [
-        rootRelativePath
+    const expanded = await expandContent(session, input.repoRoot, rootRead.real, rootRead.content, 0, [
+        rootRead.real
     ], [
-        rootRelativePath
+        rootRead.real
     ]);
     const snapshot = session.snapshot();
     return {
@@ -57471,39 +58931,45 @@ function toRepoRelativePosix(repoRoot, absoluteFilePath) {
 function toAbsolutePath(repoRoot, relativePosixPath) {
     return (0,external_node_path_.join)(repoRoot, ...relativePosixPath.split("/"));
 }
-async function mapExpansionDiagnostics(repoRoot, diagnostics) {
-    const contentByRelative = new Map();
-    const mapped = [];
-    for (const diagnostic of diagnostics){
-        const absolutePath = toAbsolutePath(repoRoot, diagnostic.filePath);
-        let content = contentByRelative.get(diagnostic.filePath);
-        if (content === undefined) {
-            content = await (0,promises_.readFile)(absolutePath, "utf8");
-            contentByRelative.set(diagnostic.filePath, content);
-        }
-        if (diagnostic.range === undefined) {
-            mapped.push({
-                ruleId: diagnostic.ruleId,
-                message: diagnostic.message,
-                filePath: absolutePath,
-                line: 1,
-                column: 1
-            });
-            continue;
-        }
-        const start = offsetToSourcePosition(content, diagnostic.range.start);
-        const end = offsetToSourcePosition(content, diagnostic.range.end);
-        mapped.push({
+async function readImporterSource(readSource, createPositionIndex, absolutePath) {
+    const outcome = await readSource(absolutePath, DEFAULT_MAX_FILE_BYTES);
+    return [
+        absolutePath,
+        outcome.ok ? createPositionIndex(outcome.content) : null
+    ];
+}
+async function mapExpansionDiagnostics(repoRoot, diagnostics, readSource, createPositionIndex) {
+    const located = diagnostics.map((diagnostic)=>({
+            diagnostic,
+            absolutePath: toAbsolutePath(repoRoot, diagnostic.filePath)
+        }));
+    const importerPaths = new Set(located.map((entry)=>entry.absolutePath));
+    const contentByPath = new Map(await Promise.all([
+        ...importerPaths
+    ].map((path)=>readImporterSource(readSource, createPositionIndex, path))));
+    return located.map(({ diagnostic, absolutePath })=>toExpansionDiagnostic(diagnostic, absolutePath, contentByPath.get(absolutePath) ?? null));
+}
+function toExpansionDiagnostic(diagnostic, absolutePath, positionOf) {
+    if (diagnostic.range === undefined || positionOf === null) {
+        return {
             ruleId: diagnostic.ruleId,
             message: diagnostic.message,
             filePath: absolutePath,
-            line: start.line,
-            column: start.column,
-            endLine: end.line,
-            endColumn: end.column
-        });
+            line: 1,
+            column: 1
+        };
     }
-    return mapped;
+    const start = positionOf(diagnostic.range.start);
+    const end = positionOf(diagnostic.range.end);
+    return {
+        ruleId: diagnostic.ruleId,
+        message: diagnostic.message,
+        filePath: absolutePath,
+        line: start.line,
+        column: start.column,
+        endLine: end.line,
+        endColumn: end.column
+    };
 }
 function collectResolvedImports(repoRoot, edges) {
     const resolved = [];
@@ -57523,7 +58989,9 @@ function collectResolvedImports(repoRoot, edges) {
 }
 /**
  * Creates the default Claude instruction import expander used by composition roots.
- */ function createClaudeInstructionImportExpander() {
+ */ function createClaudeInstructionImportExpander(options = {}) {
+    const readSource = options.readSource ?? readRegularFileNoFollow;
+    const createPositionIndex = options.createPositionIndex ?? ((content)=>createSourcePositionIndex(content));
     return {
         async expandClaudeEntrypoint (input) {
             const rootRelativePath = toRepoRelativePosix(input.repoRoot, input.absoluteFilePath);
@@ -57531,7 +58999,7 @@ function collectResolvedImports(repoRoot, edges) {
                 repoRoot: input.repoRoot,
                 rootRelativePath
             });
-            const expansionDiagnostics = await mapExpansionDiagnostics(input.repoRoot, document.expansionDiagnostics);
+            const expansionDiagnostics = await mapExpansionDiagnostics(input.repoRoot, document.expansionDiagnostics, readSource, createPositionIndex);
             return {
                 content: document.content,
                 effectiveRoot: input.absoluteFilePath,
@@ -57542,86 +59010,6 @@ function collectResolvedImports(repoRoot, edges) {
     };
 }
 
-;// CONCATENATED MODULE: ../core/src/gateways/instruction-file-discovery-gateway.ts
-/**
- * Gateway for discovering instruction files across multiple formats.
- * Supports GitHub Copilot, Claude Code, and community agent instruction formats.
- */ 
-
-
-/**
- * File system implementation of the instruction file discovery gateway.
- */ class FileSystemInstructionFileDiscoveryGateway {
-    async discoverInstructionFiles(targetDir) {
-        const files = [];
-        for (const entry of instructionDiscoveryEntries()){
-            const format = entry.instructionFormat;
-            if (format == null) {
-                continue;
-            }
-            const relativePath = (0,external_node_path_.join)(...entry.path.split("/"));
-            if (entry.matchKind === "exact") {
-                if (await this.safePathExists(targetDir, relativePath)) {
-                    files.push({
-                        filePath: (0,external_node_path_.join)(targetDir, relativePath),
-                        format
-                    });
-                }
-                continue;
-            }
-            await this.discoverMdFilesInDir(targetDir, relativePath, format, files);
-        }
-        return files;
-    }
-    async safePathExists(targetDir, relativePath) {
-        try {
-            return await file_system_utils_pathExistsWithinRoot(targetDir, relativePath);
-        } catch  {
-            return false;
-        }
-    }
-    async discoverMdFilesInDir(targetDir, dirPath, format, files) {
-        if (!await this.safePathExists(targetDir, dirPath)) {
-            return;
-        }
-        try {
-            const entries = await file_system_utils_listDirectoryWithinRoot(targetDir, dirPath);
-            const resolvedDirPath = (0,external_node_path_.resolve)(targetDir, dirPath);
-            for (const entry of entries){
-                if (entry.isSymbolicLink()) {
-                    continue;
-                }
-                if (!entry.isFile()) {
-                    continue;
-                }
-                const name = entry.name;
-                if (name.includes("..") || name.includes("/") || name.includes("\\")) {
-                    continue;
-                }
-                if (name.endsWith(".md")) {
-                    const filePath = (0,external_node_path_.join)(targetDir, dirPath, name);
-                    const resolvedFilePath = (0,external_node_path_.resolve)(filePath);
-                    const rel = (0,external_node_path_.relative)(resolvedDirPath, resolvedFilePath);
-                    if (rel.startsWith("..") || rel.startsWith(external_node_path_.sep)) {
-                        continue;
-                    }
-                    files.push({
-                        filePath,
-                        format
-                    });
-                }
-            }
-        } catch  {
-        // Skip directory if we can't read it
-        }
-    }
-}
-/**
- * Creates and returns the default instruction file discovery gateway.
- */ function createInstructionFileDiscoveryGateway() {
-    return new FileSystemInstructionFileDiscoveryGateway();
-}
-
 ;// CONCATENATED MODULE: ../../node_modules/mdast-util-to-string/lib/index.js
 /**
  * @typedef {import('mdast').Nodes} Nodes
@@ -78148,6 +79536,19 @@ const HEADING_PATTERN_DESCRIPTIONS = new Map(Object.entries(HEADING_PATTERN_DESC
 /** Type guard narrowing an `unknown` AST child to {@link AstNodeLike}. */ function isAstNodeLike(node) {
     return typeof node === "object" && node !== null && "type" in node && typeof node.type === "string";
 }
+/**
+ * Turns something discovery reported about itself into a lint diagnostic. It
+ * concerns the whole run, not one file, so it points at the target directory.
+ */ function toDiscoveryLintDiagnostic(targetDir, report) {
+    return {
+        filePath: targetDir,
+        line: 1,
+        severity: "warning",
+        message: report.message,
+        ruleId: report.ruleId,
+        target: "instruction"
+    };
+}
 /** Maximum number of raw heading pattern entries accepted before deduplication. */ const MAX_RAW_HEADING_PATTERNS = 1000;
 /** Maximum number of heading patterns accepted in a single execute() call. */ const MAX_HEADING_PATTERNS = 50;
 /** Maximum character length for a single heading pattern. */ const analyze_instruction_quality_MAX_PATTERN_LENGTH = 200;
@@ -78277,7 +79678,9 @@ const HEADING_PATTERN_DESCRIPTIONS = new Map(Object.entries(HEADING_PATTERN_DESC
             }
         }
         const proximityWindow = parsed.proximityWindow ?? 3;
-        const discoveredFiles = await this.discoveryGateway.discoverInstructionFiles(parsed.targetDir);
+        const discoveryReports = [];
+        const discoveredFiles = await this.discoveryGateway.discoverInstructionFiles(parsed.targetDir, (report)=>discoveryReports.push(report));
+        const discoveryDiagnostics = discoveryReports.map((report)=>toDiscoveryLintDiagnostic(parsed.targetDir, report));
         const mandatoryCommands = await this.commandsGateway.getMandatoryCommands(parsed.targetDir);
         if (discoveredFiles.length === 0) {
             return {
@@ -78287,12 +79690,12 @@ const HEADING_PATTERN_DESCRIPTIONS = new Map(Object.entries(HEADING_PATTERN_DESC
                     overallQualityScore: 0,
                     suggestions: [
                         {
-                            message: "No agent instruction files found. Supported formats: .github/copilot-instructions.md, .github/instructions/*.md, .github/agents/*.md, AGENTS.md, CLAUDE.md"
+                            message: "No agent instruction files found. Supported formats: .github/copilot-instructions.md, .github/instructions/**/*.instructions.md, .github/agents/*.md, AGENTS.md, AGENTS.override.md, CLAUDE.md, .claude/CLAUDE.md"
                         }
                     ],
                     parsingErrors: []
                 },
-                diagnostics: []
+                diagnostics: discoveryDiagnostics
             };
         }
         // Analyze each file (Claude entrypoints use effective import-expanded content)
@@ -78320,7 +79723,9 @@ const HEADING_PATTERN_DESCRIPTIONS = new Map(Object.entries(HEADING_PATTERN_DESC
         parsingErrors.sort((a, b)=>a.filePath < b.filePath ? -1 : a.filePath > b.filePath ? 1 : 0);
         // Score each mandatory command across all files
         const commandScores = [];
-        const diagnostics = [];
+        const diagnostics = [
+            ...discoveryDiagnostics
+        ];
         // Emit diagnostics for parsing errors
         for (const pe of parsingErrors){
             diagnostics.push({
@@ -78333,7 +79738,7 @@ const HEADING_PATTERN_DESCRIPTIONS = new Map(Object.entries(HEADING_PATTERN_DESC
             });
         }
         // Import-expansion failures (stable ruleIds, importer-token provenance)
-        diagnostics.push(...importDiagnostics);
+        diagnostics.push(...AnalyzeInstructionQualityUseCase.withoutRepeats(importDiagnostics));
         // Check each successfully parsed file for missing structural headings
         const sortedFilePaths = Array.from(fileStructures.keys()).sort((a, b)=>a < b ? -1 : a > b ? 1 : 0);
         for (const filePath of sortedFilePaths){
@@ -78401,7 +79806,7 @@ const HEADING_PATTERN_DESCRIPTIONS = new Map(Object.entries(HEADING_PATTERN_DESC
         if (file.format === "claude-md" && this.claudeImportExpander !== undefined) {
             const effective = await this.claudeImportExpander.expandClaudeEntrypoint({
                 repoRoot: targetDir,
-                absoluteFilePath: file.filePath
+                absoluteFilePath: file.contentPath ?? file.filePath
             });
             const importDiagnostics = effective.expansionDiagnostics.map((diagnostic)=>AnalyzeInstructionQualityUseCase.toImportLintDiagnostic(diagnostic));
             importDiagnostics.sort(AnalyzeInstructionQualityUseCase.compareImportDiagnostics);
@@ -78415,7 +79820,7 @@ const HEADING_PATTERN_DESCRIPTIONS = new Map(Object.entries(HEADING_PATTERN_DESC
             };
         }
         return {
-            structure: await this.astGateway.parseFile(file.filePath),
+            structure: await this.astGateway.parseFile(file.contentPath ?? file.filePath),
             importDiagnostics: []
         };
     }
@@ -78432,6 +79837,27 @@ const HEADING_PATTERN_DESCRIPTIONS = new Map(Object.entries(HEADING_PATTERN_DESC
             target: "instruction"
         };
     }
+    /**
+     * An imported file that several import paths or several entrypoints reach
+     * is expanded once per path, so the same failure at the same place in it
+     * is found more than once. Keeps the first of each.
+     */ static withoutRepeats(diagnostics) {
+        const seen = new Set();
+        return diagnostics.filter((diagnostic)=>{
+            const identity = JSON.stringify([
+                diagnostic.ruleId,
+                diagnostic.filePath,
+                diagnostic.line,
+                diagnostic.column,
+                diagnostic.message
+            ]);
+            if (seen.has(identity)) {
+                return false;
+            }
+            seen.add(identity);
+            return true;
+        });
+    }
     static compareImportDiagnostics(a, b) {
         if (a.filePath !== b.filePath) {
             return a.filePath < b.filePath ? -1 : 1;
@@ -78729,12 +80155,12 @@ const HEADING_PATTERN_DESCRIPTIONS = new Map(Object.entries(HEADING_PATTERN_DESC
 
 
 
-/** Maximum instruction file size: 1 MB */ const markdown_ast_gateway_MAX_INSTRUCTION_FILE_BYTES = 1_048_576;
+
 /**
  * Remark-based implementation of the Markdown AST gateway.
  */ class RemarkMarkdownAstGateway {
     async parseFile(filePath) {
-        const content = await read_file_no_follow_readFileNoFollow(filePath, markdown_ast_gateway_MAX_INSTRUCTION_FILE_BYTES);
+        const content = await read_file_no_follow_readFileNoFollow(filePath, MAX_INSTRUCTION_FILE_BYTES);
         return this.parseContent(content);
     }
     parseContent(content) {
@@ -78848,14 +80274,14 @@ const HEADING_PATTERN_DESCRIPTIONS = new Map(Object.entries(HEADING_PATTERN_DESC
 
 
 
-
 /**
  * Analyzes the structural quality of feedback loop documentation in instruction files.
  * Assesses structural context, execution clarity, and loop completeness.
  */ const analyzeInstructionQualityHandler = async (args)=>{
     const dir = args.targetDir || process.cwd();
-    if (!await file_system_utils_fileExists(dir)) {
-        return types_errorResponse(`Target directory does not exist: ${dir}`);
+    const targetDirError = await validateTargetDirectory(dir);
+    if (targetDirError) {
+        return targetDirError;
     }
     try {
         const discoveryGateway = createInstructionFileDiscoveryGateway();
@@ -79238,13 +80664,14 @@ const HEADING_PATTERN_DESCRIPTIONS = new Map(Object.entries(HEADING_PATTERN_DESC
  */ const createClaudeCodeWebSetupHandler = async (args)=>{
     try {
         const dir = args.targetDir || process.cwd();
-        if (!await file_system_utils_fileExists(dir)) {
-            return types_errorResponse(`Target directory does not exist: ${dir}`);
+        const targetDirError = await validateTargetDirectory(dir);
+        if (targetDirError) {
+            return targetDirError;
         }
-        const environmentGateway = createEnvironmentGateway();
+        const copilotSetupConfig = await loadCopilotSetupConfig(dir);
+        const environmentGateway = createEnvironmentGatewayWithConfig(copilotSetupConfig);
         const claudeGateway = createClaudeFileGateway();
         const environment = await environmentGateway.detectEnvironment(dir);
-        const copilotSetupConfig = await loadCopilotSetupConfig(dir);
         const hooks = await buildSessionStartHooks(environment, copilotSetupConfig);
         const existingSettings = await claudeGateway.readSettings(dir);
         const mergedSettings = mergeClaudeSettings(existingSettings, hooks);
@@ -79376,16 +80803,17 @@ Example resolved format: actions/setup-node@1a2b3c4d5e6f  # v4.0.0`;
 }
 /**
  * Builds an array of ActionToResolve entries from setup step candidates.
- * Filters out actions that already have resolved versions.
+ * Filters out run steps and actions that already have resolved versions.
  * @param candidates The setup step candidates
  * @param resolvedVersions Optional array of already-resolved versions
  * @returns Array of actions that need version resolution
  */ function buildActionsToResolve(candidates, resolvedVersions) {
     const resolvedActions = new Set(resolvedVersions?.map((r)=>r.action) ?? []);
-    // Include checkout action which is always added to workflows
+    // Include checkout action which is always added to workflows.
+    // Run steps (e.g., install commands) have no action version to resolve.
     const allActions = [
         "actions/checkout",
-        ...candidates.map((c)=>c.action)
+        ...candidates.filter((candidate)=>!candidate.run).map((candidate)=>candidate.action)
     ];
     // Deduplicate and filter out already-resolved actions
     const uniqueActions = [
@@ -79552,6 +80980,64 @@ function getInstallStepName(packageManagerType) {
     return names[packageManagerType] || "Install dependencies";
 }
 
+;// CONCATENATED MODULE: ../core/src/use-cases/placeholder-pinning.ts
+/**
+ * Finds steps of an existing workflow that still hold the version
+ * placeholder and have a resolved SHA-pinned version available.
+ */ 
+const PLACEHOLDER_SUFFIX = `@${VERSION_PLACEHOLDER}`;
+function isRecord(value) {
+    return value !== null && typeof value === "object";
+}
+/**
+ * Collects every step object in a parsed workflow's jobs.
+ */ function collectStepObjects(jobs) {
+    return Object.values(jobs).map((job)=>isRecord(job) ? job.steps : undefined).filter((steps)=>Array.isArray(steps)).flat().filter(isRecord);
+}
+/**
+ * Finds the resolved version for a step whose "uses" still holds the
+ * version placeholder.
+ */ function findResolvedVersionForPlaceholderStep(step, resolvedVersions) {
+    const uses = step.uses;
+    if (typeof uses !== "string" || !uses.endsWith(PLACEHOLDER_SUFFIX)) {
+        return undefined;
+    }
+    const action = uses.slice(0, -PLACEHOLDER_SUFFIX.length);
+    return findResolvedVersion(action, resolvedVersions);
+}
+/**
+ * Lists the steps in a workflow's jobs that still hold the version
+ * placeholder and for which a resolved version is available.
+ * @param jobs The parsed "jobs" mapping of a workflow
+ * @param resolvedVersions Resolved versions to apply
+ */ function findPlaceholderStepsToPin(jobs, resolvedVersions) {
+    if (!resolvedVersions || resolvedVersions.length === 0) {
+        return [];
+    }
+    return collectStepObjects(jobs).flatMap((step)=>{
+        const resolved = findResolvedVersionForPlaceholderStep(step, resolvedVersions);
+        return resolved ? [
+            {
+                step,
+                resolved
+            }
+        ] : [];
+    });
+}
+/**
+ * Lists the actions in an existing workflow whose steps still hold the version
+ * placeholder and for which a resolved version is available.
+ * @param existingWorkflow The parsed existing workflow
+ * @param resolvedVersions Resolved versions to apply
+ * @returns Action names that would be SHA-pinned by updateWorkflowWithMissingSteps
+ */ function findPlaceholderActionsToPin(existingWorkflow, resolvedVersions) {
+    const jobs = isRecord(existingWorkflow) ? existingWorkflow.jobs : undefined;
+    if (!isRecord(jobs)) {
+        return [];
+    }
+    return findPlaceholderStepsToPin(jobs, resolvedVersions).map(({ resolved })=>resolved.action);
+}
+
 ;// CONCATENATED MODULE: ../../node_modules/@github-actions-workflow-ts/lib/dist/esm/workflow/index.js
 /**
  * Represents a GitHub Actions workflow.
@@ -79943,6 +81429,10 @@ function getGlobalWacContext() {
 
 
 
+
+/**
+ * Name of the job that Copilot runs to prepare its environment.
+ */ const COPILOT_SETUP_JOB_NAME = "copilot-setup-steps";
 const workflow_generator_DEFAULT_ACTION_VERSIONS = {
     "actions/checkout": "v4"
 };
@@ -80040,6 +81530,22 @@ const workflow_generator_defaultActionVersionPort = createActionVersionPort(work
         steps.push(newStep.step);
     }
 }
+/**
+ * Selects the job that receives missing setup steps: the copilot-setup-steps
+ * job when it exists (Copilot runs only that job), otherwise the first job.
+ */ function selectSetupJobName(jobs) {
+    return COPILOT_SETUP_JOB_NAME in jobs ? COPILOT_SETUP_JOB_NAME : Object.keys(jobs)[0];
+}
+/**
+ * Replaces the version placeholder of existing steps with the resolved
+ * SHA-pinned version, in place.
+ */ function pinPlaceholderSteps(jobs, resolvedVersions) {
+    for (const { step, resolved } of findPlaceholderStepsToPin(jobs, resolvedVersions)){
+        step.uses = buildUsesValue(resolved.action, resolved.sha, {
+            resolvedVersions
+        });
+    }
+}
 /**
  * Gets the checkout version based on resolved versions, placeholders, or gateway.
  * Reduces duplication by centralizing the version resolution logic.
@@ -80076,7 +81582,7 @@ const workflow_generator_defaultActionVersionPort = createActionVersionPort(work
         new Step(checkoutStepProps),
         ...buildStepsFromCandidates(candidates, stepOptions)
     ];
-    const job = new NormalJob("copilot-setup-steps", {
+    const job = new NormalJob(COPILOT_SETUP_JOB_NAME, {
         "runs-on": "ubuntu-latest",
         "timeout-minutes": 30,
         permissions: options?.includeIdTokenPermission ? {
@@ -80115,7 +81621,10 @@ const workflow_generator_defaultActionVersionPort = createActionVersionPort(work
     })}`;
 }
 /**
- * Updates an existing workflow by appending missing setup steps
+ * Updates an existing workflow by appending missing setup steps to the
+ * copilot-setup-steps job (or the first job when it is absent), and by
+ * SHA-pinning existing steps that still hold the version placeholder when a
+ * resolved version is provided.
  * @param existingWorkflow The parsed existing workflow
  * @param missingCandidates Candidates to add to the workflow
  * @param versionGateway Optional gateway for looking up action versions (defaults to local)
@@ -80130,12 +81639,8 @@ const workflow_generator_defaultActionVersionPort = createActionVersionPort(work
     if (!jobs) {
         return generateWorkflowContent(missingCandidates, versionGateway, options);
     }
-    const jobNames = Object.keys(jobs);
-    if (jobNames.length === 0) {
-        return generateWorkflowContent(missingCandidates, versionGateway, options);
-    }
-    const mainJobName = jobNames[0];
-    const mainJob = jobs[mainJobName];
+    const mainJobName = selectSetupJobName(jobs);
+    const mainJob = mainJobName !== undefined ? jobs[mainJobName] : undefined;
     if (!mainJob || !Array.isArray(mainJob.steps)) {
         return generateWorkflowContent(missingCandidates, versionGateway, options);
     }
@@ -80143,6 +81648,7 @@ const workflow_generator_defaultActionVersionPort = createActionVersionPort(work
         usePlaceholders: options?.usePlaceholders,
         resolvedVersions: options?.resolvedVersions
     };
+    pinPlaceholderSteps(jobs, options?.resolvedVersions);
     appendMissingStepsToJob(mainJob.steps, missingCandidates, stepOptions);
     return `---\n${(0,yaml_dist/* .stringify */.As)(workflow, {
         lineWidth: 0
@@ -80159,6 +81665,7 @@ const workflow_generator_defaultActionVersionPort = createActionVersionPort(work
 // Re-export workflow generation functionality
 
 
+
 ;// CONCATENATED MODULE: ./src/tools/create-copilot-setup-workflow.ts
 /**
  * MCP tool handler for creating or updating Copilot Setup Steps workflow.
@@ -80171,10 +81678,8 @@ const workflow_generator_defaultActionVersionPort = createActionVersionPort(work
 
 /**
  * Gathers setup step candidates from environment and existing workflows.
- */ async function gatherCandidates(dir, workflowsDirExists) {
-    const environmentGateway = createEnvironmentGateway();
-    const workflowGateway = createWorkflowGateway();
-    const copilotSetupConfig = await loadCopilotSetupConfig();
+ */ async function gatherCandidates(dir, workflowsDirExists, workflowGateway, copilotSetupConfig) {
+    const environmentGateway = createEnvironmentGatewayWithConfig(copilotSetupConfig);
     // Detect environment configuration
     const environment = await environmentGateway.detectEnvironment(dir);
     // Parse existing workflows for setup actions
@@ -80186,12 +81691,12 @@ const workflow_generator_defaultActionVersionPort = createActionVersionPort(work
 }
 /**
  * Updates an existing workflow with missing steps.
- */ async function updateExistingWorkflow(dir, workflowPath, allCandidates, args) {
-    const workflowGateway = createWorkflowGateway();
+ */ async function updateExistingWorkflow(dir, workflowGateway, workflowPath, allCandidates, args) {
     const existingWorkflow = await workflowGateway.readCopilotSetupWorkflow(dir);
     const existingActions = getExistingActionsFromWorkflow(existingWorkflow);
     const missingCandidates = findMissingCandidates(allCandidates, existingActions);
-    if (missingCandidates.length === 0) {
+    const actionsToPin = findPlaceholderActionsToPin(existingWorkflow, args.resolvedVersions);
+    if (missingCandidates.length === 0 && actionsToPin.length === 0) {
         // Build actions to resolve for version resolution metadata
         const actionsToResolve = buildActionsToResolve(allCandidates, args.resolvedVersions);
         return successResponse({
@@ -80215,7 +81720,8 @@ const workflow_generator_defaultActionVersionPort = createActionVersionPort(work
         action: "updated",
         workflowPath,
         stepsAdded: missingCandidates.map((c)=>c.action),
-        message: `Updated workflow with ${missingCandidates.length} new step(s)`,
+        actionsPinned: actionsToPin,
+        message: `Updated workflow with ${missingCandidates.length} new step(s) and ${actionsToPin.length} SHA-pinned action(s)`,
         workflowTemplate: updatedContent,
         actionsToResolve,
         instructions: actionsToResolve.length > 0 ? VERSION_RESOLUTION_INSTRUCTIONS : undefined
@@ -80223,8 +81729,7 @@ const workflow_generator_defaultActionVersionPort = createActionVersionPort(work
 }
 /**
  * Creates a new workflow with the provided candidates.
- */ async function createNewWorkflow(dir, workflowPath, allCandidates, args) {
-    const workflowGateway = createWorkflowGateway();
+ */ async function createNewWorkflow(dir, workflowGateway, workflowPath, allCandidates, args) {
     // Generate workflow with placeholder mode and resolved versions
     const content = await generateWorkflowContent(allCandidates, undefined, {
         usePlaceholders: true,
@@ -80244,33 +81749,45 @@ const workflow_generator_defaultActionVersionPort = createActionVersionPort(work
     });
 }
 /**
- * Creates or updates the Copilot Setup Steps workflow.
- */ const createCopilotSetupWorkflowHandler = async (args)=>{
-    try {
-        const dir = args.targetDir || process.cwd();
-        if (!await file_system_utils_fileExists(dir)) {
-            return types_errorResponse(`Target directory does not exist: ${dir}`);
-        }
-        const workflowGateway = createWorkflowGateway();
-        const workflowsDir = await file_system_utils_resolveSafePath(dir, ".github/workflows");
-        const workflowsDirExists = await file_system_utils_fileExists(workflowsDir);
-        const allCandidates = await gatherCandidates(dir, workflowsDirExists);
-        if (!workflowsDirExists) {
-            await (0,promises_.mkdir)(workflowsDir, {
-                recursive: true
-            });
-        }
-        const workflowPath = await workflowGateway.getCopilotSetupWorkflowPath(dir);
-        const workflowExists = await workflowGateway.copilotSetupWorkflowExists(dir);
-        if (workflowExists) {
-            return await updateExistingWorkflow(dir, workflowPath, allCandidates, args);
+ * Builds the handler for creating or updating the Copilot Setup Steps
+ * workflow. The configuration is loaded once per call and shared by the
+ * environment detection and the workflow scan, so the two cannot see two
+ * different versions of the file.
+ */ function buildCreateCopilotSetupWorkflowHandler(ports) {
+    return async (args)=>{
+        try {
+            const dir = args.targetDir || process.cwd();
+            const targetDirError = await validateTargetDirectory(dir);
+            if (targetDirError) {
+                return targetDirError;
+            }
+            const copilotSetupConfig = await ports.loadConfig(dir);
+            const workflowGateway = createWorkflowGatewayWithConfig(copilotSetupConfig);
+            const workflowsDir = await file_system_utils_resolveSafePath(dir, ".github/workflows");
+            const workflowsDirExists = await file_system_utils_fileExists(workflowsDir);
+            const allCandidates = await gatherCandidates(dir, workflowsDirExists, workflowGateway, copilotSetupConfig);
+            if (!workflowsDirExists) {
+                await (0,promises_.mkdir)(workflowsDir, {
+                    recursive: true
+                });
+            }
+            const workflowPath = await workflowGateway.getCopilotSetupWorkflowPath(dir);
+            const workflowExists = await workflowGateway.copilotSetupWorkflowExists(dir);
+            if (workflowExists) {
+                return await updateExistingWorkflow(dir, workflowGateway, workflowPath, allCandidates, args);
+            }
+            return await createNewWorkflow(dir, workflowGateway, workflowPath, allCandidates, args);
+        } catch (error) {
+            const message = error instanceof Error ? error.message : "Unknown error occurred";
+            return types_errorResponse(`Failed to create/update workflow: ${message}`);
         }
-        return await createNewWorkflow(dir, workflowPath, allCandidates, args);
-    } catch (error) {
-        const message = error instanceof Error ? error.message : "Unknown error occurred";
-        return types_errorResponse(`Failed to create/update workflow: ${message}`);
-    }
-};
+    };
+}
+/**
+ * Creates or updates the Copilot Setup Steps workflow.
+ */ const createCopilotSetupWorkflowHandler = buildCreateCopilotSetupWorkflowHandler({
+    loadConfig: loadCopilotSetupConfig
+});
 
 ;// CONCATENATED MODULE: ./src/tools/discover-environment.ts
 /**
@@ -80282,10 +81799,11 @@ const workflow_generator_defaultActionVersionPort = createActionVersionPort(work
  */ const discoverEnvironmentHandler = async (args)=>{
     try {
         const dir = args.targetDir || process.cwd();
-        if (!await file_system_utils_fileExists(dir)) {
-            return types_errorResponse(`Target directory does not exist: ${dir}`);
+        const targetDirError = await validateTargetDirectory(dir);
+        if (targetDirError) {
+            return targetDirError;
         }
-        const environmentGateway = createEnvironmentGateway();
+        const environmentGateway = createEnvironmentGateway(dir);
         const environment = await environmentGateway.detectEnvironment(dir);
         return successResponse({
             hasMise: environment.hasMise,
@@ -80366,16 +81884,30 @@ const workflow_generator_defaultActionVersionPort = createActionVersionPort(work
 
 
 
+/** Groups items by their phase, each as the entry the response shows. */ function groupByPhase(items, toEntry) {
+    const grouped = {};
+    for (const item of items){
+        grouped[item.phase] = [
+            ...grouped[item.phase] ?? [],
+            toEntry(item)
+        ];
+    }
+    return grouped;
+}
 /**
  * Discovers npm scripts from package.json and CLI tools from GitHub Actions workflows,
  * mapping them to SDLC feedback loop phases (test, build, lint, format, etc.).
  */ const discoverFeedbackLoopsHandler = async (args)=>{
     const dir = args.targetDir || process.cwd();
+    const targetDirError = await validateTargetDirectory(dir);
+    if (targetDirError) {
+        return targetDirError;
+    }
     try {
         // Create gateways
         const scriptGateway = createScriptDiscoveryGateway();
         const toolGateway = createToolDiscoveryGateway();
-        const environmentGateway = createEnvironmentGateway();
+        const environmentGateway = createEnvironmentGateway(dir);
         // Adapter for package manager gateway
         const packageManagerGateway = {
             async detectPackageManagers (targetDir) {
@@ -80391,29 +81923,17 @@ const workflow_generator_defaultActionVersionPort = createActionVersionPort(work
         });
         const { scripts, tools, packageManager } = result.feedbackLoops;
         // Group by phase for better readability
-        const scriptsByPhase = scripts.reduce((acc, script)=>{
-            if (!acc[script.phase]) {
-                acc[script.phase] = [];
-            }
-            acc[script.phase].push({
+        const scriptsByPhase = groupByPhase(scripts, (script)=>({
                 name: script.name,
                 command: script.command,
                 mandatory: script.isMandatory
-            });
-            return acc;
-        }, {});
-        const toolsByPhase = tools.reduce((acc, tool)=>{
-            if (!acc[tool.phase]) {
-                acc[tool.phase] = [];
-            }
-            acc[tool.phase].push({
+            }));
+        const toolsByPhase = groupByPhase(tools, (tool)=>({
                 name: tool.name,
                 command: tool.fullCommand,
                 mandatory: tool.isMandatory,
                 source: tool.sourceWorkflow
-            });
-            return acc;
-        }, {});
+            }));
         const mandatoryScripts = scripts.filter((s)=>s.isMandatory);
         const mandatoryTools = tools.filter((t)=>t.isMandatory);
         return successResponse({
@@ -80444,10 +81964,11 @@ const workflow_generator_defaultActionVersionPort = createActionVersionPort(work
  */ const discoverWorkflowSetupActionsHandler = async (args)=>{
     try {
         const dir = args.targetDir || process.cwd();
-        if (!await file_system_utils_fileExists(dir)) {
-            return types_errorResponse(`Target directory does not exist: ${dir}`);
+        const targetDirError = await validateTargetDirectory(dir);
+        if (targetDirError) {
+            return targetDirError;
         }
-        const workflowGateway = createWorkflowGateway();
+        const workflowGateway = createWorkflowGateway(dir);
         const workflowsDir = (0,external_node_path_.join)(dir, ".github", "workflows");
         const workflowsDirExists = await file_system_utils_fileExists(workflowsDir);
         if (!workflowsDirExists) {
@@ -80483,8 +82004,9 @@ const workflow_generator_defaultActionVersionPort = createActionVersionPort(work
  */ const readCopilotSetupWorkflowHandler = async (args)=>{
     try {
         const dir = args.targetDir || process.cwd();
-        if (!await file_system_utils_fileExists(dir)) {
-            return types_errorResponse(`Target directory does not exist: ${dir}`);
+        const targetDirError = await validateTargetDirectory(dir);
+        if (targetDirError) {
+            return targetDirError;
         }
         const workflowGateway = createWorkflowGateway();
         const exists = await workflowGateway.copilotSetupWorkflowExists(dir);
@@ -80521,13 +82043,14 @@ const workflow_generator_defaultActionVersionPort = createActionVersionPort(work
  */ 
 
 
-
 /**
  * Resolves action versions for the provided actions or detected candidates.
  */ const resolveActionVersionsHandler = async (args)=>{
     try {
         if (args.actions && args.actions.length > 0) {
-            const actionsToResolve = args.actions.filter((action)=>{
+            const actionsToResolve = [
+                ...new Set(args.actions)
+            ].filter((action)=>{
                 if (args.resolvedVersions) {
                     return !args.resolvedVersions.some((r)=>r.action === action);
                 }
@@ -80540,8 +82063,9 @@ const workflow_generator_defaultActionVersionPort = createActionVersionPort(work
             });
         }
         const dir = args.targetDir || process.cwd();
-        if (!await file_system_utils_fileExists(dir)) {
-            return types_errorResponse(`Target directory does not exist: ${dir}`);
+        const targetDirError = await validateTargetDirectory(dir);
+        if (targetDirError) {
+            return targetDirError;
         }
         const config = await loadCopilotSetupConfig(dir);
         const defaultActions = [
@@ -80566,10 +82090,37 @@ const workflow_generator_defaultActionVersionPort = createActionVersionPort(work
     }
 };
 
+;// CONCATENATED MODULE: ../core/src/entities/coverage-discovery-caveat.ts
+/**
+ * What a coverage result says when instruction file discovery left files out
+ * (it hit a limit, or skipped a symbolic link that points outside the
+ * repository). A mandatory item reported as undocumented may be documented in
+ * a file that was not checked, and a fully documented result covers only the
+ * files found. The use case that writes the suggestions and the MCP tool that
+ * writes the message use these once, so they cannot say different things.
+ */ /** Whether discovery reported anything about itself, which means it left files out. */ function discoveryLeftFilesOut(diagnostics) {
+    return diagnostics.length > 0;
+}
+const ALL_DOCUMENTED_IN_FILES_FOUND = "✅ All mandatory feedback loops are documented in the instruction files found, but discovery left some instruction files out, so they were not checked";
+const UNDOCUMENTED_IN_FILES_FOUND = " in the instruction files found; discovery left some instruction files out, so they may be documented in files that were not checked";
+/**
+ * The statement that every mandatory item is documented: the caller's own
+ * sentence, or the qualified one when discovery left files out.
+ */ function qualifyAllDocumented(plain, leftFilesOut) {
+    return leftFilesOut ? ALL_DOCUMENTED_IN_FILES_FOUND : plain;
+}
+/**
+ * The statement that mandatory items are not documented, with the caveat that
+ * they may be documented in a file discovery left out.
+ */ function qualifyUndocumented(plain, leftFilesOut) {
+    return leftFilesOut ? `${plain}${UNDOCUMENTED_IN_FILES_FOUND}` : plain;
+}
+
 ;// CONCATENATED MODULE: ../core/src/use-cases/validate-instruction-coverage.ts
 /**
  * Use case for validating instruction coverage of feedback loops
- */ /**
+ */ 
+/**
  * Use case for validating that repository instructions cover mandatory feedback loops
  */ class ValidateInstructionCoverageUseCase {
     discoverFeedbackLoops;
@@ -80596,11 +82147,14 @@ const workflow_generator_defaultActionVersionPort = createActionVersionPort(work
     }
     generateSuggestions(coverage, packageManager) {
         const suggestions = [];
+        const leftFilesOut = discoveryLeftFilesOut(coverage.diagnostics);
         if (coverage.missingInInstructions.length === 0) {
-            suggestions.push("✅ All mandatory feedback loops are documented in instructions");
+            suggestions.push(qualifyAllDocumented("✅ All mandatory feedback loops are documented in instructions", leftFilesOut));
             return suggestions;
         }
-        suggestions.push(`⚠️  ${coverage.missingInInstructions.length} mandatory feedback loop(s) are not documented:`);
+        const missingCount = coverage.missingInInstructions.length;
+        const undocumented = qualifyUndocumented(`⚠️  ${missingCount} mandatory feedback loop(s) are not documented`, leftFilesOut);
+        suggestions.push(`${undocumented}:`);
         suggestions.push("");
         const byPhase = new Map();
         for (const item of coverage.missingInInstructions){
@@ -80635,17 +82189,34 @@ const workflow_generator_defaultActionVersionPort = createActionVersionPort(work
 
 
 
+
 /**
- * Validates that repository instructions (.github/copilot-instructions.md and .github/instructions/*.md)
+ * Summarizes the coverage. When discovery left instruction files out (it hit a
+ * limit, or skipped a symbolic link that points outside the repository) the
+ * result says so: a mandatory item reported as undocumented may be documented
+ * in a file that was not checked, and a fully documented result covers only the
+ * files found.
+ */ function coverageMessage({ hasFullCoverage, coveragePercentage, missingCount, leftFilesOut }) {
+    if (hasFullCoverage) {
+        return qualifyAllDocumented("✅ All mandatory feedback loops are documented", leftFilesOut);
+    }
+    return qualifyUndocumented(`⚠️  ${coveragePercentage.toFixed(1)}% coverage - ${missingCount} mandatory items not documented`, leftFilesOut);
+}
+/**
+ * Validates that repository instruction files (the catalog shared with analyze_instruction_quality)
  * document all mandatory feedback loop scripts and tools.
  * Returns coverage percentage and suggestions for missing documentation.
  */ const validateInstructionCoverageHandler = async (args)=>{
     const dir = args.targetDir || process.cwd();
+    const targetDirError = await validateTargetDirectory(dir);
+    if (targetDirError) {
+        return targetDirError;
+    }
     try {
         // Create gateways
         const scriptGateway = createScriptDiscoveryGateway();
         const toolGateway = createToolDiscoveryGateway();
-        const environmentGateway = createEnvironmentGateway();
+        const environmentGateway = createEnvironmentGateway(dir);
         const instructionGateway = createInstructionAnalysisGateway();
         // Adapter for package manager gateway
         const packageManagerGateway = {
@@ -80708,7 +82279,16 @@ const workflow_generator_defaultActionVersionPort = createActionVersionPort(work
             missing,
             documented,
             suggestions,
-            message: hasFullCoverage ? "✅ All mandatory feedback loops are documented" : `⚠️  ${coverage.summary.coveragePercentage.toFixed(1)}% coverage - ${missing.length} mandatory items not documented`
+            diagnostics: coverage.diagnostics.map((d)=>({
+                    ruleId: d.ruleId,
+                    message: d.message
+                })),
+            message: coverageMessage({
+                hasFullCoverage,
+                coveragePercentage: coverage.summary.coveragePercentage,
+                missingCount: missing.length,
+                leftFilesOut: discoveryLeftFilesOut(coverage.diagnostics)
+            })
         });
     } catch (error) {
         return types_errorResponse(`Failed to validate instruction coverage: ${error instanceof Error ? error.message : "Unknown error"}`);
@@ -80741,12 +82321,13 @@ const workflow_generator_defaultActionVersionPort = createActionVersionPort(work
  */ 
 
 
+
 /**
  * Resolved version schema for input validation.
  */ const resolvedVersionSchema = schemas_object({
     action: schemas_string().describe("Action name (e.g., 'actions/setup-node')"),
-    sha: schemas_string().describe("Commit SHA for the action version"),
-    versionTag: schemas_string().describe("Version tag (e.g., 'v4.0.0')")
+    sha: schemas_string().regex(/^[0-9a-f]{40}$/i, "sha must be a full 40-character commit SHA").describe("Full 40-character commit SHA for the action version"),
+    versionTag: schemas_string().regex(/^[A-Za-z0-9][A-Za-z0-9._+/-]*$/, "versionTag must be a single-line version tag").describe("Version tag (e.g., 'v4.0.0')")
 });
 /**
  * Shared input schema for tools that operate on a target directory.
@@ -80789,7 +82370,7 @@ const workflow_generator_defaultActionVersionPort = createActionVersionPort(work
     },
     {
         name: "validate_instruction_coverage",
-        description: "Validate that repository instructions (.github/copilot-instructions.md and .github/instructions/*.md) document all mandatory feedback loop scripts and tools. Returns coverage percentage and suggestions for missing documentation.",
+        description: "Validate that repository instruction files (the same files analyze_instruction_quality discovers: .github/copilot-instructions.md, .github/instructions/**/*.instructions.md, .github/agents/*.md, AGENTS.md, AGENTS.override.md, CLAUDE.md, .claude/CLAUDE.md) document all mandatory feedback loop scripts and tools. Returns coverage percentage and suggestions for missing documentation.",
         handler: validateInstructionCoverageHandler,
         inputSchema: targetDirInputSchema
     },
@@ -80847,7 +82428,7 @@ const workflow_generator_defaultActionVersionPort = createActionVersionPort(work
  */ function createMcpServer() {
     const server = new McpServer({
         name: "lousy-agents",
-        version: "0.1.0"
+        version: readPackageVersion()
     });
     registerTools(server);
     return server;
@@ -91334,4 +92915,4 @@ if (installedChunkData !== 0) { // 0 means "already installed".'
 // module factories are used so entry inlining is disabled
 // startup
 // Load entry module and return exports
-var __webpack_exports__ = __webpack_require__(3904);
+var __webpack_exports__ = __webpack_require__(8066);