vigiles 2.5.0 → 3.0.0

package/dist/codex.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `vigiles/codex` — the OpenAI Codex harness adapter. Sits beside
+ * `vigiles/claude-code`: same harness-agnostic `vigiles/testing` core, a
+ * different transport (the `codex` binary + the OpenAI **Responses** SSE mock).
+ *
+ * Pillar 2 (harness testing) is proven here — `startCodexMock` serves the
+ * Responses SSE that real `codex exec` completes a turn against, keylessly (see
+ * `codexMockArgs`/`codexMockEnv` for the wiring). Pillar 1 instruction/skill
+ * *renderers* still emit the Claude-Code shape until the format-axis renderers
+ * land (see `research/code-adapter-architecture.md`).
+ */
+export * from "./adapters/codex/dialect.js";
+export * from "./adapters/codex/layout.js";
+export * from "./adapters/codex/runtime.js";
+export * from "./adapters/codex/hook-protocol.js";
+export * from "./adapters/codex/model-mock.js";
+export * from "./adapters/codex/mock-model.js";
+export * from "./adapters/codex/driver.js";
+export * from "./adapters/codex/adapter.js";
+//# sourceMappingURL=codex.d.ts.map

package/dist/codex.js

@@ -0,0 +1,36 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * `vigiles/codex` — the OpenAI Codex harness adapter. Sits beside
+ * `vigiles/claude-code`: same harness-agnostic `vigiles/testing` core, a
+ * different transport (the `codex` binary + the OpenAI **Responses** SSE mock).
+ *
+ * Pillar 2 (harness testing) is proven here — `startCodexMock` serves the
+ * Responses SSE that real `codex exec` completes a turn against, keylessly (see
+ * `codexMockArgs`/`codexMockEnv` for the wiring). Pillar 1 instruction/skill
+ * *renderers* still emit the Claude-Code shape until the format-axis renderers
+ * land (see `research/code-adapter-architecture.md`).
+ */
+__exportStar(require("./adapters/codex/dialect.js"), exports);
+__exportStar(require("./adapters/codex/layout.js"), exports);
+__exportStar(require("./adapters/codex/runtime.js"), exports);
+__exportStar(require("./adapters/codex/hook-protocol.js"), exports);
+__exportStar(require("./adapters/codex/model-mock.js"), exports);
+__exportStar(require("./adapters/codex/mock-model.js"), exports);
+__exportStar(require("./adapters/codex/driver.js"), exports);
+__exportStar(require("./adapters/codex/adapter.js"), exports);
+//# sourceMappingURL=codex.js.map

package/dist/community-skills.d.ts

@@ -12,7 +12,7 @@
  *
  * These are exercised in community-skills.test.ts with a scripted model.
  */
-import { type SkillProgram } from "./skill-driver.js";
+import { type SkillProgram } from "./adapters/claude-code/skill-driver.js";
 /** COLLECT → BATCH → FIX rounds; ceiling 7; exit when no actionable feedback. */
 export declare const prReviewLoop: SkillProgram;
 /** Red → Green → Refactor, once per behavior until done. */

package/dist/community-skills.js

@@ -15,8 +15,8 @@ exports.subagentDriven = exports.tdd = exports.prReviewLoop = void 0;
  *
  * These are exercised in community-skills.test.ts with a scripted model.
  */
-const skill_driver_js_1 = require("./skill-driver.js");
-const spec_js_1 = require("./spec.js");
+const skill_driver_js_1 = require("./adapters/claude-code/skill-driver.js");
+const spec_js_1 = require("./core/spec.js");
 /** COLLECT → BATCH → FIX rounds; ceiling 7; exit when no actionable feedback. */
 const prReviewLoop = function* () {
     let round = 0;

package/dist/core/adapter.d.ts

@@ -0,0 +1,88 @@
+/**
+ * HarnessAdapter — the bundle that makes a harness a single, addable unit.
+ *
+ * Each port (HarnessDialect, PluginLayout, HarnessRuntime, HookProtocol,
+ * ModelMock) decouples one axis of Claude-Code coupling. A `HarnessAdapter`
+ * groups a harness's five port implementations plus a `detect` predicate, so
+ * **adding a harness is writing one object** — `codexAdapter`, `geminiAdapter`,
+ * `myHarnessAdapter` — not editing the core. The library stays import-named
+ * (`import { claudeCodeAdapter } from "vigiles/claude-code"`); the bundle is the
+ * thing the CLI auto-detects and the conformance kit checks.
+ *
+ * See `docs/authoring-an-adapter.md` (third-party guide) and
+ * `research/code-adapter-architecture.md` (the design).
+ */
+import type { HarnessDialect } from "./dialect.js";
+import type { PluginLayout } from "./layout.js";
+import type { HarnessRuntime } from "./runtime.js";
+import type { HookProtocol } from "./hook-protocol.js";
+import type { ModelMock } from "./model-mock.js";
+import type { HarnessTestDriver } from "./harness-driver.js";
+/**
+ * Which vigiles pillars/tiers a harness can drive — the capability matrix made
+ * executable (see `docs/harnesses.md`). Not every harness reaches every tier:
+ * a closed, un-mockable one (Cursor, Devin, Amp, Amazon Q) can only ever do
+ * pillar 1, and a harness whose hooks are in-process code modules (OpenCode)
+ * has no shell-hook tier. Declaring this lets the conformance kit relax the
+ * port requirements for what an adapter says it can't do (instead of forcing a
+ * fake `runtime`/`modelMock`/`hookProtocol`), and lets the pillar-2 runners
+ * refuse — rather than mysteriously hang on — an adapter that can't be mocked.
+ */
+export interface AdapterCapabilities {
+    /**
+     * Pillar 1 — reference verification (dialect + layout). Always `true`: every
+     * harness with an instruction-file format can have its references verified.
+     */
+    readonly referenceVerification: true;
+    /**
+     * Pillar 2 — deterministic harness tests + evals: the binary can be spawned
+     * and pointed at a mock model. Requires `runtime` + `modelMock`. `false` for
+     * closed harnesses that route through a fixed backend (no BYOM): Cursor,
+     * Devin, Amp, Amazon Q — they are pillar-1-only adapters.
+     */
+    readonly harnessTesting: boolean;
+    /**
+     * Hooks are shell processes speaking the exit-code/env block protocol —
+     * Claude Code, Codex, Crush. Requires `hookProtocol`. `false` when hooks are
+     * in-process code modules (OpenCode's TS plugins), so the `run-hook` unit
+     * tier and the `HookProtocol` port do not apply.
+     */
+    readonly shellHooks: boolean;
+}
+export interface HarnessAdapter {
+    /** Stable identifier, e.g. "claude-code". The CLI/registry key. */
+    readonly name: string;
+    /** What this harness can drive — gates which ports below are required. */
+    readonly capabilities: AdapterCapabilities;
+    /** Format axis: tool catalog, hook events, instruction targets, plugin-root token. */
+    readonly dialect: HarnessDialect;
+    /** Layout axis: where the instruction file / skills / agents / hooks live on disk. */
+    readonly layout: PluginLayout;
+    /** Transport axis: the agent binary to spawn + the mock-model env. Present iff
+     *  `capabilities.harnessTesting`. */
+    readonly runtime?: HarnessRuntime;
+    /** Transport axis: how a hook signals a block/deny. Present iff
+     *  `capabilities.shellHooks`. */
+    readonly hookProtocol?: HookProtocol;
+    /** Transport axis: the mock model's wire format + endpoints. Present iff
+     *  `capabilities.harnessTesting`. */
+    readonly modelMock?: ModelMock;
+    /**
+     * Pillar-2 deterministic-runner driver: how `runHarnessTest` builds this
+     * harness's argv, starts its scripted mock, and parses its stdout. Present iff
+     * `capabilities.harnessTesting` (it composes the runtime + modelMock into the
+     * one seam the runner dispatches through). Carried on the bundle so the runner
+     * never imports a sibling adapter to find it.
+     */
+    readonly harnessTestDriver?: HarnessTestDriver;
+    /**
+     * How strongly a repo at `root` looks like it targets this harness — the CLI
+     * uses it to auto-detect which adapter to use (the library selects by import).
+     * Returns a **specificity score**: 0 = not this harness; higher = a more
+     * specific match. The registry picks the highest scorer, so a strong signal
+     * (a `.claude-plugin/` manifest) beats a weak one (a bare `CLAUDE.md`, or an
+     * `AGENTS.md` that many harnesses share) regardless of registration order.
+     */
+    detect(root: string): number;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/core/adapter.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=adapter.js.map

package/dist/{compile.d.ts → core/compile.d.ts}

@@ -6,6 +6,7 @@
  */
 import type { ClaudeSpec, SkillSpec, AgentSpec, Railway } from "./spec.js";
 import type { LinterCheckResult } from "./linters.js";
+import type { HarnessDialect } from "./dialect.js";
 /** @internal Compute SHA-256 hash of content (excluding any existing hash line). */
 export declare function computeHash(content: string): string;
 /** @internal Prepend a hash comment to compiled content. */
@@ -44,6 +45,8 @@ export interface CompileClaudeResult {
 export interface CompileClaudeOptions {
     basePath?: string;
     specFile?: string;
+    /** Injected harness dialect; its instructionTargets[0] is the default target. */
+    dialect?: HarnessDialect;
     /** Maximum number of rules allowed. Compilation fails if exceeded. */
     maxRules?: number;
     /** Maximum estimated tokens for compiled output. */
@@ -78,6 +81,9 @@ export interface CompileSkillResult {
 export declare function compileSkill(spec: SkillSpec, options?: {
     basePath?: string;
     specFile?: string;
+    /** The harness dialect — selects the SKILL.md frontmatter profile. Omitting
+     *  it defaults to the Claude Code profile, so existing callers are unchanged. */
+    dialect?: HarnessDialect;
 }): CompileSkillResult;
 export interface CompileAgentResult {
     markdown: string;
@@ -88,9 +94,12 @@ export interface CompileAgentResult {
  * Verifies the tool contract and the body's references; the marks the body
  * carries (`vigiles:symbol`, file/cmd refs) are the same ones `audit` re-checks.
  */
-export declare function compileAgent(spec: AgentSpec, options?: {
+export declare function compileAgent(spec: AgentSpec, options: {
     basePath?: string;
     specFile?: string;
+    /** The harness dialect to verify the tool contract against (required — the
+     *  core defines no default dialect; the adapter/composition root injects it). */
+    dialect: HarnessDialect;
 }): CompileAgentResult;
 export interface CompileRailwayOptions {
     /** Names of compiled agents, to resolve `delegate` targets. Skipped if omitted. */
@@ -130,5 +139,5 @@ export interface AdoptResult {
  * Compare a generated file against what the spec would produce.
  * Returns the diff so users can see what was manually changed.
  */
-export declare function adoptDiff(filePath: string, spec: ClaudeSpec | SkillSpec | AgentSpec, basePath: string): AdoptResult;
+export declare function adoptDiff(filePath: string, spec: ClaudeSpec | SkillSpec | AgentSpec, basePath: string, dialect: HarnessDialect): AdoptResult;
 //# sourceMappingURL=compile.d.ts.map

package/dist/{compile.js → core/compile.js}

@@ -26,6 +26,10 @@ const node_path_1 = require("node:path");
 const hash_js_1 = require("./hash.js");
 const symbols_js_1 = require("./symbols.js");
 const linters_js_1 = require("./linters.js");
+// vigiles's default compile target when a spec names none and no dialect is
+// injected — a product convention (vigiles emits CLAUDE.md by default), not a
+// harness dialect. When a dialect IS injected its instructionTargets win.
+const DEFAULT_TARGET = "CLAUDE.md";
 // ---------------------------------------------------------------------------
 // Hash utilities
 // ---------------------------------------------------------------------------
@@ -388,8 +392,14 @@ function compileRulesSection(spec, basePath, options) {
  * Returns the compiled markdown, validation errors, and linter check results.
  * The markdown is generated even if there are errors (with warnings).
  */
+// The instruction-file renderer is format-neutral: it emits plain markdown (h1
+// from the dialect's instructionTargets, prose/Key-Files/Commands/Rules sections,
+// and the trailing integrity-hash comment). That is exactly the AGENTS.md shape
+// (no frontmatter), so Codex/OpenCode reuse it unchanged — only the h1 target
+// differs, which already comes from the injected dialect. Nothing here is
+// CC-only, so there is no per-dialect branch to gate.
 function compileClaude(spec, options = {}) {
-    const targets = spec.target ?? "CLAUDE.md";
+    const targets = spec.target ?? options.dialect?.instructionTargets[0] ?? DEFAULT_TARGET;
     const target = Array.isArray(targets) ? targets[0] : targets;
     const basePath = options.basePath ?? process.cwd();
     const specFile = options.specFile ?? `${target}.spec.ts`;
@@ -546,22 +556,32 @@ function collectSkillRefs(spec) {
         refs.push(spec.result);
     return refs;
 }
-/** Build the SKILL.md YAML frontmatter block. */
-function renderSkillFrontmatter(spec) {
+/**
+ * Build the SKILL.md YAML frontmatter block under the harness's frontmatter
+ * profile. The `"minimal"` profile (Codex/OpenCode) emits ONLY name +
+ * description; `"claude-code"` adds the CC-only keys (disable-model-invocation,
+ * argument-hint). Default is `"claude-code"` so callers that pass no dialect get
+ * byte-identical output to before.
+ */
+function renderSkillFrontmatter(spec, profile = "claude-code") {
     const fm = [
         "---",
         "",
         `name: ${spec.name}`,
         `description: ${spec.description}`,
     ];
-    if (spec.disableModelInvocation !== undefined) {
-        fm.push(`disable-model-invocation: ${String(spec.disableModelInvocation)}`);
-    }
-    const argHint = spec.inputs && spec.inputs.length > 0
-        ? renderArgumentHint(spec.inputs)
-        : spec.argumentHint;
-    if (argHint)
-        fm.push(`argument-hint: ${argHint}`);
+    // The CC-only keys below are inert in a minimal (Codex/OpenCode) SKILL.md, so
+    // they're omitted entirely under that profile.
+    if (profile === "claude-code") {
+        if (spec.disableModelInvocation !== undefined) {
+            fm.push(`disable-model-invocation: ${String(spec.disableModelInvocation)}`);
+        }
+        const argHint = spec.inputs && spec.inputs.length > 0
+            ? renderArgumentHint(spec.inputs)
+            : spec.argumentHint;
+        if (argHint)
+            fm.push(`argument-hint: ${argHint}`);
+    }
     fm.push("", "---");
     return fm.join("\n");
 }
@@ -621,6 +641,7 @@ function checkInlineCode(markdown, max) {
 function compileSkill(spec, options = {}) {
     const basePath = options.basePath ?? process.cwd();
     const specFile = options.specFile ?? "SKILL.md.spec.ts";
+    const profile = options.dialect?.skillFrontmatter ?? "claude-code";
     const errors = [];
     // Verify spec file naming
     if (!specFile.endsWith(".spec.ts")) {
@@ -641,45 +662,29 @@ function compileSkill(spec, options = {}) {
     errors.push(...validateRefs(collectSkillRefs(spec), basePath));
     const sections = renderSkillSections(spec);
     errors.push(...checkInlineCode(sections, spec.maxInlineCodeLines ?? DEFAULT_MAX_INLINE_CODE_LINES));
-    const content = renderSkillFrontmatter(spec) + "\n\n" + sections.trim() + "\n";
+    const content = renderSkillFrontmatter(spec, profile) + "\n\n" + sections.trim() + "\n";
     return { markdown: addHash(content, specFile), errors };
 }
 // ---------------------------------------------------------------------------
 // Compile a subagent spec → agents/<name>.md
 // ---------------------------------------------------------------------------
-// The tool contract a subagent may declare — the rails it runs on. Anything
-// else must be an MCP tool (mcp__server__tool), else it's a typo / nonexistent
-// tool the dispatched worker could never call.
-const KNOWN_AGENT_TOOLS = [
-    "Read",
-    "Write",
-    "Edit",
-    "Bash",
-    "Grep",
-    "Glob",
-    "WebSearch",
-    "WebFetch",
-    "NotebookEdit",
-    "TodoWrite",
-    "Task",
-    "Skill",
-];
-const MCP_TOOL_RE = /^mcp__[a-z0-9_-]+__[a-z0-9_-]+$/i;
-// Tools the platform never exposes to a subagent, whatever the list says — so a
-// subagent listing one is a guaranteed-dead reference only a compiler catches.
-const NEVER_AVAILABLE_TOOLS = new Set([
-    "Agent",
-    "AskUserQuestion",
-    "EnterPlanMode",
-    "ExitPlanMode",
-    "ScheduleWakeup",
-    "WaitForMcpServers",
-]);
+// The subagent tool catalog (built-in / never-available / MCP shape) is the
+// harness's format-axis vocabulary — it lives in the HarnessDialect port
+// (src/core/dialect.ts), injected here, never hard-coded for one harness.
+//
+// SCOPE: compileAgent renders vigiles's agent() — a VERIFIED TOOL CONTRACT — to
+// a Claude-Code-shaped subagent markdown file. Compiling that to Codex is a
+// deliberate NON-GOAL, not a missing renderer: a Codex "subagent" is an
+// [agents.<name>] TOML concurrency table (max_threads / max_depth), which is a
+// runtime-orchestration knob, NOT a tool contract. The two models don't map, so
+// vigiles does not emit a TOML [agents] block. The Codex dialect still verifies
+// an agent()'s tool contract (its built-in catalog) — only the OUTPUT renderer
+// is CC-only here. See research/codex-prototype-findings.md (gaps).
 /** Closest known tool by edit distance (≤ 3), for a "did you mean" hint. */
-function closestTool(tool) {
+function closestTool(tool, dialect) {
     let best = null;
     let bestDistance = Infinity;
-    for (const known of KNOWN_AGENT_TOOLS) {
+    for (const known of dialect.builtinAgentTools) {
         const d = (0, linters_js_1.editDistance)(tool.toLowerCase(), known.toLowerCase());
         if (d < bestDistance) {
             bestDistance = d;
@@ -689,25 +694,26 @@ function closestTool(tool) {
     return bestDistance <= 3 ? best : null;
 }
 /** Verify a subagent's allowed-tools contract — the rails are real tools. */
-function validateAgentTools(tools) {
+function validateAgentTools(tools, dialect) {
+    const never = new Set(dialect.neverAvailableTools);
     const errors = [];
     for (const tool of tools) {
-        if (NEVER_AVAILABLE_TOOLS.has(tool)) {
+        if (never.has(tool)) {
             errors.push({
                 type: "unknown-tool",
                 message: `Tool "${tool}" is never available to a subagent — remove it from the tools list.`,
             });
             continue;
         }
-        if (KNOWN_AGENT_TOOLS.includes(tool))
+        if (dialect.builtinAgentTools.includes(tool))
             continue;
-        if (MCP_TOOL_RE.test(tool))
+        if (dialect.mcpToolPattern.test(tool))
             continue;
-        const near = closestTool(tool);
+        const near = closestTool(tool, dialect);
         const hint = near ? ` Did you mean "${near}"?` : "";
         errors.push({
             type: "unknown-tool",
-            message: `Unknown tool "${tool}" in agent tools — use a built-in tool (${KNOWN_AGENT_TOOLS.join(", ")}) or an MCP tool (mcp__server__tool).${hint}`,
+            message: `Unknown tool "${tool}" in agent tools — use a built-in tool (${dialect.builtinAgentTools.join(", ")}) or an MCP tool (mcp__server__tool).${hint}`,
         });
     }
     return errors;
@@ -798,9 +804,10 @@ function renderAgentRules(rules) {
  * Verifies the tool contract and the body's references; the marks the body
  * carries (`vigiles:symbol`, file/cmd refs) are the same ones `audit` re-checks.
  */
-function compileAgent(spec, options = {}) {
+function compileAgent(spec, options) {
     const basePath = options.basePath ?? process.cwd();
     const specFile = options.specFile ?? "agent.md.spec.ts";
+    const dialect = options.dialect;
     const errors = [];
     if (!specFile.endsWith(".spec.ts")) {
         errors.push({
@@ -815,7 +822,7 @@ function compileAgent(spec, options = {}) {
         });
     }
     if (spec.tools)
-        errors.push(...validateAgentTools(spec.tools));
+        errors.push(...validateAgentTools(spec.tools, dialect));
     if (Array.isArray(spec.body)) {
         errors.push(...validateRefs(spec.body, basePath));
     }
@@ -921,7 +928,7 @@ function checkFileHash(filePath) {
  * Compare a generated file against what the spec would produce.
  * Returns the diff so users can see what was manually changed.
  */
-function adoptDiff(filePath, spec, basePath) {
+function adoptDiff(filePath, spec, basePath, dialect) {
     const fullPath = (0, node_path_1.resolve)(basePath, filePath);
     const currentContent = (0, node_fs_1.existsSync)(fullPath)
         ? (0, node_fs_1.readFileSync)(fullPath, "utf-8")
@@ -930,7 +937,11 @@ function adoptDiff(filePath, spec, basePath) {
     // Compile the spec to get what it WOULD produce
     let compiledContent = null;
     if (spec._specType === "claude") {
-        const { markdown } = compileClaude(spec, { basePath, specFile: filePath });
+        const { markdown } = compileClaude(spec, {
+            basePath,
+            specFile: filePath,
+            dialect,
+        });
         compiledContent = markdown;
     }
     else if (spec._specType === "skill") {
@@ -938,7 +949,11 @@ function adoptDiff(filePath, spec, basePath) {
         compiledContent = markdown;
     }
     else if (spec._specType === "agent") {
-        const { markdown } = compileAgent(spec, { basePath, specFile: filePath });
+        const { markdown } = compileAgent(spec, {
+            basePath,
+            specFile: filePath,
+            dialect,
+        });
         compiledContent = markdown;
     }
     // Simple line-based diff

package/dist/core/compose.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Sync-tool compatibility detector — keep vigiles composable with the rule-sync
+ * tools (Ruler, rulesync) instead of fighting them for the same files.
+ *
+ * Both vigiles and a sync tool want to *write* CLAUDE.md / AGENTS.md. That
+ * collision is the whole compatibility problem: vigiles stamps a SHA-256
+ * integrity header on line 1 (see `integrity.ts`), but Ruler concatenates its
+ * source files into CLAUDE.md (prepending `<!-- Source: … -->`) and rulesync
+ * regenerates it — either way the hash silently goes stale. The clean topology
+ * is "vigiles upstream": compile into the tool's *source slot* and let the tool
+ * distribute (see `research/sync-tool-compatibility.md`).
+ *
+ * This detector is pure filesystem inspection — the same deterministic-detector
+ * shape as `orphans.ts` / `test-coverage.ts`. It reports which tools are present
+ * and any target that collides with a file the tool regenerates, so `vigiles
+ * audit` can warn before the integrity guarantee is lost.
+ */
+/** A rule-sync tool vigiles should compose with rather than reimplement. */
+export type SyncToolName = "ruler" | "rulesync";
+export interface DetectedSyncTool {
+    readonly name: SyncToolName;
+    /**
+     * Where vigiles should compile its canonical output so the tool picks it up
+     * as a source (Topology A), e.g. `.ruler/AGENTS.md`.
+     */
+    readonly sourceSlot: string;
+    /**
+     * Files the tool regenerates/concatenates as distribution output. A vigiles
+     * compile target that lands in this set collides (the integrity hazard).
+     */
+    readonly distributes: readonly string[];
+}
+export interface ComposeCollision {
+    readonly tool: SyncToolName;
+    /** The vigiles compile target that the tool also owns. */
+    readonly target: string;
+    /** The source slot to compile into instead. */
+    readonly redirectTo: string;
+    readonly reason: string;
+}
+/** CLAUDE.md and AGENTS.md recognized as one artifact (symlinked or synced). */
+export interface InstructionMirror {
+    /** The two instruction filenames that mirror each other. */
+    readonly files: readonly [string, string];
+    /** How they're kept identical: a symlink, or byte-identical synced content. */
+    readonly kind: "symlink" | "identical-content";
+    /** For `kind: "symlink"`, which filename is the link and which is the real file. */
+    readonly link?: string;
+    readonly realTarget?: string;
+    readonly reason: string;
+}
+/**
+ * Detect the rule-sync tools configured in the repo at `root`. Ruler is keyed
+ * on its `.ruler/` source dir or a `ruler.toml`; rulesync on its `.rulesync/`
+ * dir. Returns each tool's recommended source slot and the files it owns as
+ * distribution output (used to find collisions).
+ */
+export declare function detectSyncTools(root: string): DetectedSyncTool[];
+/**
+ * Detect whether `CLAUDE.md` and `AGENTS.md` at `root` are ONE artifact, not two
+ * — a symlink in either direction (`ln -s CLAUDE.md AGENTS.md`) or byte-identical
+ * content (a sync tool keeping them in lockstep). Claude Code reads CLAUDE.md
+ * only ([anthropics/claude-code#34235]); users bridge to the AGENTS.md tools this
+ * way (see `research/sync-tool-compatibility.md` requirement 7). When mirrored,
+ * vigiles must treat them as the same file — hash + `require-spec` run once on the
+ * real one, and the mirror is never flagged as a second, spec-less instruction
+ * file. Returns null when one is absent, or both exist but genuinely differ.
+ */
+export declare function detectInstructionMirror(root: string): InstructionMirror | null;
+/**
+ * Given the repo `root` and the spec's compile `targets`, report every case
+ * where a target is also a file a detected sync tool regenerates. Each
+ * collision carries the source slot to compile into instead — the actionable
+ * fix that preserves the integrity hash (the tool distributes from there).
+ *
+ * No detected tool, or no overlapping target, yields an empty list.
+ */
+export declare function composeCollisions(root: string, targets: readonly string[]): ComposeCollision[];
+//# sourceMappingURL=compose.d.ts.map