buddy-agent-harness 0.5.0 → 0.7.0

package/dist/index.d.mts

@@ -1,20 +1,161 @@
+import { run } from "./cli.mjs";
 import { cli as cli$1 } from "clibuilder";
+//#region src/harness-registry/instruction-bridge.d.ts
+/**
+ * What a harness needs in order to read the repository's `AGENTS.md`.
+ *
+ * A skills projection is one shape — a directory pointing at `.agents/skills` — so the registry
+ * models it as a path. Instruction bridges are not one shape: Claude Code needs a Markdown file
+ * whose body imports `AGENTS.md`, and Gemini CLI needs `AGENTS.md` added to an array inside a JSON
+ * settings file. A second bare path field would describe the first and lie about the second, so the
+ * variant carries what its own check needs.
+ *
+ * The `init` command writes none of these. They are the `init` skill's work, which is why every
+ * finding against one names the skill rather than a flag.
+ */
+type InstructionBridge = {
+  /**
+   * A Markdown file whose body is an `@AGENTS.md` import, or a symlink to `AGENTS.md`. One is
+   * needed beside every `AGENTS.md` in the tree, not only the root file: an import bridges the
+   * one file next to it, so a nested `AGENTS.md` is invisible until it has its own.
+   */
+  kind: "import";
+  /** Repository-relative name, the same in every directory that holds an `AGENTS.md`. */
+  path: string;
+} | {
+  /** An `AGENTS.md` entry in an array inside a JSON settings file. */
+  kind: "settings-entry";
+  /** Repository-relative path of the settings file. */
+  path: string;
+  /** Dotted path to the array within it, as the harness documents it. */
+  key: string;
+};
+//#endregion
+//#region src/harness-registry/mcp-config.d.ts
+/**
+ * Where one harness keeps its MCP server configuration at one scope, as that harness's own vendor
+ * documents it.
+ *
+ * Recorded per scope like everything else in a `HarnessScope`, and populated at **project** scope
+ * only. Much of the world's MCP configuration lives at user scope — `~/.codex/config.toml`,
+ * `~/.claude.json`, `claude_desktop_config.json` — and the registry records user scope as
+ * described and diagnosable, never written. Reading a user's home directory into output that
+ * lands in every session's transcript is a wider blast radius than diagnosis needs, so those paths
+ * stay out until something needs them.
+ *
+ * A harness with no documented project-scope MCP file gets no entry. Copilot CLI is the case that
+ * matters: its own documentation states that `.vscode/mcp.json` "is not read by Copilot CLI", and
+ * names `~/.copilot/mcp-config.json` instead. That is a documented absence, not a gap — see
+ * `.research/mcp-canonical-location/` (E-MCP-11).
+ */
+type McpConfig = {
+  /** Repository-relative path of the file, as the vendor documents it. */
+  path: string;
+  /**
+   * The key the servers sit under. Not one key across hosts: `mcpServers` for Claude Code, Cursor,
+   * and Gemini CLI, `mcp_servers` for Codex, `servers` for VS Code. Reading the wrong one finds
+   * nothing and reports a repository as unconfigured.
+   */
+  key: string;
+  /**
+   * How the file is serialized. It decides the parser, and it is also why comparison is semantic:
+   * the same server in TOML and in JSON shares no bytes.
+   */
+  format: "json" | "toml";
+  /**
+   * Set when the file holds far more than MCP configuration. `.gemini/settings.json` also carries
+   * the instruction bridge, so anything reading it must take its key and leave the rest alone —
+   * and anything writing it must never rewrite the file wholesale.
+   */
+  shared?: true;
+};
+//#endregion
+//#region src/harness-registry/nonstandard-artifact.d.ts
+/**
+ * Configuration a harness reads that no other harness can, declared per harness beside the paths
+ * `doctor` already knows about it.
+ *
+ * These are not faults. Every one of them works — for exactly one harness — which is the whole
+ * problem: the guidance in a Cursor rule reaches Cursor and nothing else, and nobody finds out
+ * except by noticing an agent behaving differently in another tool. `doctor` surfaces them so they
+ * can be converted, one at a time, toward a repository whose agent configuration is canonical and
+ * whose harness files are generated from it. Zero of these is the north star, not a release gate.
+ *
+ * `kind` carries the conversion, because the canonical form differs per kind and nothing else about
+ * the artifact does. It is what a finding routes on.
+ */
+type NonstandardKind = "instructions" | "rule" | "command" | "skill" | "subagent";
+type NonstandardArtifact = {
+  /**
+   * Repository-relative path. A file is reported as itself; a directory is reported per file
+   * below it, so each one can be converted on its own rather than as an all-or-nothing batch.
+   */
+  path: string;
+  /** Whether `path` names one file or a directory to walk. */
+  shape: "file" | "directory";
+  kind: NonstandardKind;
+};
+//#endregion
 //#region src/harness-registry/harness-registry.d.ts
 type HarnessName = "claude-code" | "cursor" | "codex" | "copilot-cli" | "gemini-cli" | "devin-desktop" | "windsurf";
+/** The two scopes a harness reads configuration at. Their roots differ; their shape does not. */
+type HarnessScopeName = "project" | "user";
 /**
- * `skillsDirectory` is the projection target a harness needs to see `.agents/skills`.
- * A harness that reads `.agents/skills` natively has none, and is never projected into.
+ * What one harness does at one scope. Paths are relative to that scope's root: the repository root
+ * at project scope, the user's home directory at user scope.
+ *
+ * `detect` is the directory whose presence means this harness is configured at this scope — a
+ * different question per scope, which is why it is recorded per scope rather than once.
+ *
+ * `skillsDirectory` is the projection target the harness needs to see `.agents/skills` at this
+ * scope. A harness that reads `.agents/skills` natively there has none, and is never projected into.
+ *
+ * `mcpConfig` is where this harness keeps its MCP servers at this scope. Unlike the other two it
+ * is not a bridge into a canonical file the harness cannot read — it is the harness's own
+ * configuration, which `doctor` compares against the golden set and never writes.
+ *
+ * `nonstandard` is what this harness reads that no other harness can. Unlike the three above it is
+ * not something the tool maintains — it is what a repository accumulated before it was canonical,
+ * and `doctor` reports it so it can be converted. Declared here because the paths are per harness
+ * and belong beside the harness's other paths, not in a second list that would drift from this one.
+ *
+ * `instructionBridge` is the same question for `AGENTS.md`: what the harness needs at this scope in
+ * order to read it. It belongs per scope for the same reason `skillsDirectory` does — the file
+ * differs. Unlike `skillsDirectory`, the `init` command does not write it; the `init` skill does. It
+ * is recorded here to be diagnosed and gated per harness, not to be projected.
  */
-type Harness = {
-  name: HarnessName;
+type HarnessScope = {
   detect: string;
   skillsDirectory?: string;
+  instructionBridge?: InstructionBridge;
+  mcpConfig?: McpConfig;
+  nonstandard?: readonly NonstandardArtifact[];
+};
+type Harness = {
+  name: HarnessName;
+  /** What this harness does inside a repository. `init` and `doctor` act only here. */
+  project: HarnessScope;
+  /**
+   * What this harness does for the user, outside any repository. Absent when no user-scope path is
+   * primary-sourced — Devin documents none. Described and diagnosable; never written to.
+   */
+  user?: HarnessScope;
   /** Set when this name has been superseded; the value is the name that replaces it. */
   deprecated?: HarnessName;
 };
 /**
- * Codex, Cursor, Copilot CLI, and Devin Desktop read `.agents/skills` directly, so they need no
- * projection. Only Claude Code and Gemini CLI read solely their own directory.
+ * The two scopes disagree in general, and a single answer per harness could only record one of them:
+ * Copilot CLI is `.github/skills` in a repository and `~/.copilot` for the user. Claude Code is the
+ * only harness that needs a skills projection, and it needs one at both scopes. Codex, Cursor,
+ * Copilot CLI, Gemini CLI, and Devin Desktop read `.agents/skills` themselves and are never
+ * projected into.
+ *
+ * Gemini CLI carried a `.gemini/skills` projection until E-GEM-02: it reads the `.agents/skills`
+ * alias at project scope too, where that alias takes precedence over `.gemini/skills`. It still
+ * needs an instruction bridge, which is a separate axis and unaffected.
+ *
+ * Instruction bridges are recorded at project scope only. The user-scope equivalents exist, but
+ * nothing writes or reads them yet: `init` works inside a repository, and so does `doctor`.
  *
  * `windsurf` is the former name of Devin Desktop, rebranded 2026-06-02. It is retained as a
  * deprecated alias: Devin still scans the legacy `.windsurf/skills` path, so its projection keeps
@@ -24,9 +165,219 @@ type Harness = {
  */
 declare const harnessRegistry: readonly Harness[];
 //#endregion
+//#region src/diagnose-bridges/diagnose-instructions.d.ts
+/** What is on disk where an instruction bridge belongs. */
+type InstructionKind = "import" | "symlink" | "settings-entry" | "file" | "none";
+/**
+ * `unbridged` is the case a skills bridge has no equivalent of: the file is there, so nothing looks
+ * wrong, and it names `AGENTS.md` nowhere — a `CLAUDE.md` overwritten with real content, or a
+ * settings file another tool rewrote.
+ */
+type InstructionStatus = "ok" | "missing" | "unbridged" | "unreadable";
+type InstructionReport = {
+  harness: HarnessName;
+  /** Repository-relative path of the file that carries the bridge. */
+  path: string;
+  kind: InstructionKind;
+  status: InstructionStatus;
+};
+/**
+ * Reports whether every enabled harness can still read `AGENTS.md`.
+ *
+ * Losing one of these is quieter than losing a skills bridge and costs more: a harness with no
+ * instruction bridge reads none of the repository's instructions, and says nothing about it. The
+ * checks are read-only, and no repair is a command — rewriting an instruction file is the `init`
+ * skill's judgment.
+ */
+declare function diagnoseInstructions(root: string, harnesses: readonly Harness[], cli: string): {
+  instructions: InstructionReport[];
+  findings: BridgeFinding[];
+};
+//#endregion
+//#region src/diagnose-bridges/locator.d.ts
+/**
+ * Where a finding is, in parts.
+ *
+ * A locator addresses a place inside a file — `.cursor/mcp.json#servers.linear.command` — because a
+ * file holding twenty servers is not an address. The parts are known wherever a finding is raised,
+ * and only the report and the repairs need the string, so the parts are what travel and this module
+ * is the one place they become one. Nothing ever recovers a part by splitting a locator back apart:
+ * a server may be named `io.github.foo`, and no split of the rendered string tells where the server
+ * name ends and the field begins.
+ */
+/**
+ * Where a malformed file failed. **Position only.** A parser's own error message quotes the
+ * offending line back, and in a file of MCP configuration that line is exactly the one holding a
+ * credential — so neither the message nor the code block it carries is ever read. Line and column
+ * are enough to fix the file and carry nothing out of it.
+ */
+type Position = {
+  line: number;
+  column: number;
+};
+type Locator = {
+  /** Repository-relative path of the file the finding is about. */
+  file: string;
+  /** The MCP server inside that file, when the finding is about one. */
+  server?: string;
+  /** The field inside that server, dotted for the per-name fields — `command`, `env.LINEAR_TOKEN`. */
+  field?: string;
+  /** Where a file that does not parse failed, when the parser gave a position. */
+  position?: Position | undefined;
+};
+//#endregion
+//#region src/diagnose-bridges/doctor-guidance.d.ts
+/**
+ * The one place `doctor`'s guidance is written. The command reads `detail` and `repair` to fill its
+ * `findings` and `help` sections; `skills/doctor/SKILL.md` is generated from the same table by
+ * `scripts/generate-skills.ts`, so the shipped skill cannot drift from what the command says.
+ */
+/** Every way a skills bridge can fail, in the order `doctor` reports them. */
+type BridgeProblem = "no-canonical" | "missing" | "degraded" | "stale" | "diverged-bridge" | "diverged-canonical" | "diverged-both" | "diverged-unknown" | "unpinned-copy";
+/**
+ * Every way an instruction bridge can fail. Separate from `BridgeProblem` because the two share no
+ * repair: a skills bridge is rebuilt with `init` flags, and an instruction bridge is a file whose
+ * content is the user's, so every repair here goes back to the `init` skill.
+ */
+/**
+ * Configuration that is present and **wrong**, as against a bridge that does not resolve. These are
+ * the faults the `repair` skill owns: none is expressible as an `init` flag, because `init`
+ * consolidates and creates but never corrects a file the user already wrote.
+ */
+type ConfigurationFault = "deprecated-harness" | "ignored-bridge" | "unread-local-override" | "unloadable-skill";
+/**
+ * Every way the golden MCP server set and a harness's copy of it can disagree, plus the two
+ * credential findings.
+ *
+ * A family of its own because nothing it says is shared with the others. A bridge either resolves
+ * or does not; two MCP files never share a byte, so every finding here is the result of a semantic
+ * comparison, and each one names a **server** and usually a **field** rather than a file.
+ */
+type McpProblem = "mcp-golden-unreadable" | "mcp-target-unreadable" | "mcp-unprojected" | "mcp-undeclared" | "mcp-diverged-target" | "mcp-diverged-golden" | "mcp-diverged-both" | "mcp-diverged-unknown" | "mcp-literal-secret" | "mcp-committed-secret";
+/**
+ * Configuration that works, for exactly one harness. Not wrong and not missing — the two states the
+ * other families cover — which is why it is a family of its own: every other finding says something
+ * is broken, and these say something reaches less far than the repository meant.
+ *
+ * Each one names the canonical form it converts to, because surfacing without a destination is just
+ * a list of files somebody already knows about.
+ */
+type NonstandardProblem = "nonstandard-instructions" | "nonstandard-rule" | "nonstandard-command" | "nonstandard-skill" | "nonstandard-subagent";
+type InstructionProblem = "no-instructions" | "instructions-missing" | "instructions-unbridged" | "instructions-unreadable";
+/** Everything `doctor` can report against, across every section. */
+type DoctorProblem = BridgeProblem | InstructionProblem | ConfigurationFault | McpProblem | NonstandardProblem;
+/** Alias kept for callers that name the whole set rather than one section. */
+type ConfigurationProblem = DoctorProblem;
+/**
+ * What resolves one finding, for `doctor`'s own output. Two fields rather than one string, because
+ * the caller `doctor` is written for is an agent parsing TOON, and the question it has to answer is
+ * "can I execute this, or is this judgment I hand to a skill?" A single string leaves that
+ * answerable only by parsing English.
+ *
+ * The contract is exact, and it is what makes the field safe to act on blindly:
+ *
+ * - `command` non-empty — a shell invocation that, run verbatim, **completes** the repair.
+ * - `command` empty — no single invocation does; act on `instruction` and do not synthesize one.
+ *
+ * So a diagnostic worth running is not a `command`. `diverged-both` carries none even though
+ * `git diff --no-index …` is perfectly runnable: the diff shows what differs, it does not reconcile
+ * anything. That is what stops an agent executing every `command` it is handed from rebuilding a
+ * diverged bridge over whichever side holds the newer edit. A skill invocation is not a `command`
+ * either — nothing in a shell runs `/buddy-agent-harness:init`.
+ */
+type RepairAction = {
+  /** A shell invocation that completes the repair, or empty when none does. */
+  command: string;
+  /** The imperative, in prose, always present and complete on its own. */
+  instruction: string;
+};
+type Repair = {
+  problem: DoctorProblem;
+  /** What `doctor` prints in the `findings` row for this problem. */
+  detail: string;
+  /**
+   * What fixes it, for `doctor`'s own output. `at` is where the finding is, in parts — the file
+   * alone for a bridge, the file, server, and field for an MCP finding; `cli` is how to invoke this
+   * tool. A repair that names only part of a locator reads it off `at` rather than splitting the
+   * rendered string, which no separator survives: a server may be named `io.github.foo`.
+   */
+  repair(at: Locator, cli: string): RepairAction;
+  /**
+   * What the shipped skill tells an agent to do instead. A repair that rebuilds a bridge delegates
+   * to the `init` skill rather than calling the `init` command, because rebuilding can move
+   * user-authored skills and that judgment is the `init` skill's, not `doctor`'s.
+   */
+  skillRepair(at: Locator): string;
+};
+declare const bridgeRepairs: readonly Repair[];
+declare const instructionRepairs: readonly Repair[];
+declare const doctorRepairs: readonly Repair[];
+declare const doctorSkill: {
+  readonly name: "doctor";
+  readonly description: "Use this skill when a repository loads no project skills, when skills are missing after a clone, when a harness appears to be ignoring AGENTS.md, or when checking whether the agent configuration bridges into .claude/skills, CLAUDE.md, and the other harness files still resolve.";
+};
+/**
+ * The shipped `doctor` skill, rendered from the same table the command prints. `version` is the
+ * package version the skill ships with; it pins the `npx` invocation so the table and the CLI that
+ * produced it stay on the same breaking line.
+ *
+ * The finding tables are NOT here. They live in the reference pages below, and this file carries
+ * only what every reader needs: how to run it, how to read the report, and where to go next.
+ */
+declare function renderDoctorSkill(version: string): string;
+//#endregion
 //#region src/diagnose-bridges/git-bridge-state.d.ts
 /** Which side of a diverged bridge moved since the last commit where the two agreed. */
 type DivergenceDirection = "bridge" | "canonical" | "both" | "unknown";
+/** Whether a path is tracked, and if so whether its skip-worktree bit is still set. */
+type TrackingState = "untracked" | "tracked" | "skip-worktree";
+/**
+ * Reads git state for the two sides of a bridge. Every method degrades to "cannot tell" rather than
+ * throwing, so `doctor` still reports on a tarball, a worktree without git, or a repository with no
+ * commits.
+ */
+declare class GitBridgeState {
+  private readonly root;
+  /** Path of `root` relative to the repository root, `''` at the top, `undefined` outside a repository. */
+  private readonly prefix;
+  constructor(root: string);
+  /**
+   * `init --copy` marks a bridge skip-worktree so a machine-local copy over a tracked symlink stops
+   * showing as a pending change. The bit is a hint that some checkouts clear, so it is verified
+   * rather than assumed.
+   */
+  trackingOf(path: string): TrackingState;
+  /**
+   * Whether a `.gitignore` rule matches this path. Asked of git rather than matched against the
+   * file, so a rule on a parent directory — the common way a bridge gets ignored — is caught.
+   * Outside a repository nothing is ignored, which is the same "cannot tell" degradation the rest
+   * of this class uses.
+   */
+  isIgnored(path: string): boolean;
+  /**
+   * The newest commits that touched any of these paths, newest first. Empty outside a repository,
+   * which is the same "cannot tell" degradation as everything else here.
+   *
+   * Bounded like `lastAgreedTree` is: a baseline that is not in the recent history of the two files
+   * is not a baseline anyone can act on, and walking a whole repository to prove its absence costs
+   * more than the answer is worth.
+   */
+  commitsTouching(paths: readonly string[]): string[];
+  /** One file's content at one commit, or `undefined` when it did not exist there. */
+  contentAt(commit: string, path: string): string | undefined;
+  /**
+   * Names the side that moved by finding the newest commit whose two trees agreed, then asking which
+   * of the working directories still matches it.
+   */
+  directionOf(bridge: string, canonical: string): DivergenceDirection;
+  /** The tree of the newest commit where both paths held identical content. */
+  private lastAgreedTree;
+  /**
+   * Compares a working directory against a git tree by object id. `hash-object` is used rather than
+   * hashing in-process so the comparison follows whatever object format the repository uses.
+   */
+  private matchesTree;
+}
 //#endregion
 //#region src/diagnose-bridges/diagnose-bridges.d.ts
 type BridgeKind = "symlink" | "copy" | "file" | "none";
@@ -40,9 +391,14 @@ type BridgeReport = {
 };
 type BridgeFinding = {
   path: string;
+  /**
+   * Which problem this is. Emitted so a caller routes on a name rather than by matching `detail`
+   * prose, which would break the moment the wording is improved.
+   */
+  problem: DoctorProblem;
   detail: string;
-  /** The command that repairs this finding, already carrying the bridge path. */
-  repair: string;
+  /** What repairs this finding, already carrying the bridge path. Empty `command` means judgment. */
+  repair: RepairAction;
 };
 type DivergenceReport = {
   path: string;
@@ -56,54 +412,139 @@ type DiagnoseOptions = {
 };
 type DiagnoseResult = {
   bridges: BridgeReport[];
+  /**
+   * The instruction bridges into `AGENTS.md`, kept out of `bridges` on purpose: a different `kind`
+   * and `status` vocabulary, and a repair that is the `init` skill rather than a command.
+   */
+  instructions: InstructionReport[];
   divergence: DivergenceReport[];
   findings: BridgeFinding[];
 };
 /**
- * Reports whether every bridge `init` would create for this repository still resolves into
- * `.agents/skills`. Read-only: nothing is created, moved, or repaired, so the caller decides what
- * to run from the repair each finding carries.
+ * Reports whether every bridge this repository needs still resolves: the skills bridges into
+ * `.agents/skills`, and the instruction bridges into `AGENTS.md`. Read-only: nothing is created,
+ * moved, or repaired, so the caller decides what to run from the repair each finding carries.
  */
 declare function diagnoseBridges({ root, harnesses: preferred, cli }: DiagnoseOptions): DiagnoseResult;
 //#endregion
-//#region src/diagnose-bridges/doctor.command.d.ts
-declare const doctorCommand: cli$1.Command;
-//#endregion
-//#region src/diagnose-bridges/doctor-guidance.d.ts
+//#region src/diagnose-configuration/diagnose-configuration.d.ts
 /**
- * The one place `doctor`'s guidance is written. The command reads `detail` and `repair` to fill its
- * `findings` and `help` sections; `skills/doctor/SKILL.md` is generated from the same table by
- * `scripts/generate-skills.ts`, so the shipped skill cannot drift from what the command says.
+ * The configuration half of `doctor`. Where `diagnose-bridges` asks whether a bridge still
+ * resolves, this asks whether the configuration around it is still *right* — a harness name that
+ * has been superseded, an instruction file that never reaches `AGENTS.md`, a bridge git-ignores.
+ *
+ * Everything here is present-and-wrong rather than missing. Configuration that is absent is
+ * `init`'s to create; configuration that is wrong is what the `repair` skill acts on, and this
+ * module is where it reads its work from. Detection has one home so the two cannot drift.
+ *
+ * Instruction bridges are deliberately not here: `diagnose-instructions` owns them, and every one
+ * of its repairs goes back to the `init` skill rather than to `repair`.
+ *
+ * Read-only, like every other part of `doctor`.
  */
-/** Every way a bridge can fail, in the order `doctor` reports them. */
-type BridgeProblem = "no-canonical" | "missing" | "degraded" | "stale" | "diverged-bridge" | "diverged-canonical" | "diverged-both" | "diverged-unknown" | "unpinned-copy";
-type Repair = {
-  problem: BridgeProblem;
-  /** What `doctor` prints in the `findings` row for this problem. */
+type ConfigurationFinding = {
+  /** Repository-relative path the finding is about. */
+  path: string;
+  problem: ConfigurationProblem;
   detail: string;
+  /** What repairs it, already carrying the path. Every fault here is judgment, so `command` is empty. */
+  repair: RepairAction;
+};
+//#endregion
+//#region src/diagnose-bridges/doctor.command.d.ts
+type DoctorReport = {
+  bin: string;
+  bridges: DiagnoseResult["bridges"];
+  instructions: DiagnoseResult["instructions"];
+  divergence?: DiagnoseResult["divergence"];
   /**
-   * The command that fixes it, for `doctor`'s own output. `path` is the repository-relative bridge
-   * path; `cli` is how to invoke this tool.
+   * The repair is lifted out into `help`, so a finding row stays to the diagnosis itself. `problem`
+   * stays on the row: it is how a caller routes without parsing `detail` prose.
    */
-  repair(path: string, cli: string): string;
+  findings: {
+    path: string;
+    problem: DoctorProblem;
+    detail: string;
+  }[] | string;
   /**
-   * What the shipped skill tells an agent to do instead. A repair that rebuilds a bridge delegates
-   * to the `init` skill rather than calling the `init` command, because rebuilding can move
-   * user-authored skills and that judgment is the `init` skill's, not `doctor`'s.
+   * One entry per distinct repair. Two fields rather than a sentence, because the caller has to
+   * tell an executable repair from an instruction, and `RepairAction` is where that lives.
+   *
+   * Both keys are always emitted, `command` as an empty string when there is none. An optional key
+   * would drop the whole array out of TOON's tabular form into the nested list form — worse for
+   * exactly the consumer the default format exists for.
    */
-  skillRepair(path: string): string;
+  help?: RepairAction[];
 };
-declare const doctorRepairs: readonly Repair[];
-declare const doctorSkill: {
-  readonly name: "doctor";
-  readonly description: "Use this skill when a repository loads no project skills, when skills are missing after a clone, or when checking whether the agent configuration bridges into .claude/skills and the other harness directories still resolve.";
+/**
+ * AXI §5: the healthy answer states the zero with context, so an agent does not re-run with other
+ * flags to confirm that an empty section really meant "nothing wrong".
+ */
+declare function buildDoctorReport(bin: string, result: DiagnoseResult, configuration?: ConfigurationFinding[]): DoctorReport;
+declare const doctorCommand: cli$1.Command;
+//#endregion
+//#region src/diagnose-mcp/diagnose-mcp.d.ts
+/**
+ * The MCP half of `doctor`: how a repository's **golden MCP server set** and the harness copies of
+ * it have drifted apart, and where a literal credential is sitting in either.
+ *
+ * The golden set is a file the user authors. That is what makes this capability possible at all:
+ * `init` reports MCP configuration rather than converting it because converting a config someone
+ * wrote for one harness into another's format has to invent values they never wrote, and `init`
+ * invents nothing. A set the user authored inverts the premise — a field they filled in is
+ * transcription. **No golden set means no drift diagnosis**, and nothing here invents anything
+ * either.
+ *
+ * Read-only, like the rest of `doctor`. Projecting the golden set forward and reconciling a
+ * target-side change back into it are writes, and they need an approval-gated home; this module is
+ * where that home reads its work from.
+ */
+type DiagnoseMcpOptions = {
+  root: string;
+  git: GitBridgeState;
+  /** How to name this tool in the repair commands. */
+  cli: string;
 };
+declare function diagnoseMcp({ root, git, cli }: DiagnoseMcpOptions): ConfigurationFinding[];
+//#endregion
+//#region src/diagnose-mcp/mcp-model.d.ts
 /**
- * The shipped `doctor` skill, rendered from the same table the command prints. `version` is the
- * package version the skill ships with; it pins the `npx` invocation so the table and the CLI that
- * produced it stay on the same breaking line.
+ * The shape both sides of an MCP comparison are normalized into.
+ *
+ * No two MCP configuration files are ever byte-equal — the supported harnesses spread the same
+ * servers across six config keys and three serialization formats — so comparison cannot be a
+ * diff. Each side is parsed into this model and the models are compared.
+ *
+ * The field list is a **superset** of what the hosts accept, which is the whole premise of a
+ * golden set: `description`, `enabled`, and `timeout` are Goose's, `source` is Zed's, and a
+ * converter writing into either has to supply them. Supplying a value the user wrote is
+ * transcription; supplying one they did not is invention, and `init` invents nothing. See
+ * `.research/agentic-configuration-standards/` (E-MCP-05) for what each host makes up today.
  */
-declare function renderDoctorSkill(version: string): string;
+type McpTransport = "stdio" | "http" | "sse";
+type McpServer = {
+  transport?: McpTransport;
+  command?: string;
+  args?: readonly string[];
+  env?: Readonly<Record<string, string>>;
+  url?: string;
+  headers?: Readonly<Record<string, string>>;
+  description?: string;
+  enabled?: boolean;
+  timeout?: number;
+  source?: string;
+};
+/** Every field of the model, in the order a finding reports them. */
+declare const mcpFields: readonly ["transport", "command", "args", "env", "url", "headers", "description", "enabled", "timeout", "source"];
+type McpField = (typeof mcpFields)[number];
+//#endregion
+//#region src/diagnose-mcp/mcp-baseline.d.ts
+/** Which side of a diverged server moved since the two last agreed. */
+type McpDirection = "target" | "golden" | "both" | "unknown";
+//#endregion
+//#region src/diagnose-mcp/mcp-sources.d.ts
+/** Where the golden set lives, and why it is namespaced rather than sitting at `.agents/mcp.json`. */
+declare const goldenSetPath = ".agents/buddy-agent-harness/mcp.toml";
 //#endregion
 //#region src/initialize-harnesses/init.command.d.ts
 declare const initCommand: cli$1.Command;
@@ -112,18 +553,28 @@ declare function activate({ addCommand }: {
   addCommand(command: typeof harnessCommand): void;
 }): void;
 //#endregion
+//#region src/skill-projection/skill-projection.d.ts
+/**
+ * Which conflicting targets a run may replace. `true` is every one of them; a list names them
+ * individually, so a run invoked to fix one bridge cannot reach past it to another. `false` and an
+ * empty list both mean none, which is what makes a conflict stop the run.
+ */
+type ForceSelection = boolean | readonly string[];
+//#endregion
 //#region src/initialize-harnesses/initialize-harnesses.d.ts
 type InitializeOptions = {
   root: string;
   harnesses?: HarnessName[];
   copy?: boolean;
-  force?: boolean;
+  force?: ForceSelection;
 };
 type InitializeResult = {
   root: string;
   harnesses: HarnessName[];
   native: HarnessName[];
   linked: HarnessName[];
+  /** Enabled harnesses left untouched because their target conflicts and `--force` did not name it. */
+  skipped: HarnessName[];
   /** Enabled harnesses whose name has been superseded, as `{ name, replacedBy }`. */
   deprecated: {
     name: HarnessName;
@@ -134,5 +585,5 @@ type InitializeResult = {
 };
 declare function initializeHarnesses({ root, harnesses: preferred, copy, force }: InitializeOptions): InitializeResult;
 //#endregion
-export { type BridgeFinding, type BridgeKind, type BridgeProblem, type BridgeReport, type BridgeStatus, type DiagnoseOptions, type DiagnoseResult, type DivergenceDirection, type DivergenceReport, type HarnessName, type InitializeOptions, type InitializeResult, type Repair, activate, diagnoseBridges, doctorCommand, doctorRepairs, doctorSkill, harnessCommand, harnessRegistry, initCommand, initializeHarnesses, renderDoctorSkill };
+export { type BridgeFinding, type BridgeKind, type BridgeProblem, type BridgeReport, type BridgeStatus, type ConfigurationFault, type ConfigurationProblem, type DiagnoseMcpOptions, type DiagnoseOptions, type DiagnoseResult, type DivergenceDirection, type DivergenceReport, type DoctorProblem, type DoctorReport, type Harness, type HarnessName, type HarnessScope, type HarnessScopeName, type InitializeOptions, type InitializeResult, type InstructionBridge, type InstructionKind, type InstructionProblem, type InstructionReport, type InstructionStatus, type McpConfig, type McpDirection, type McpField, type McpProblem, type McpServer, type McpTransport, type Repair, activate, bridgeRepairs, buildDoctorReport, diagnoseBridges, diagnoseInstructions, diagnoseMcp, doctorCommand, doctorRepairs, doctorSkill, goldenSetPath, harnessCommand, harnessRegistry, initCommand, initializeHarnesses, instructionRepairs, renderDoctorSkill, run };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/harness-registry/harness-registry.ts","../src/diagnose-bridges/git-bridge-state.ts","../src/diagnose-bridges/diagnose-bridges.ts","../src/diagnose-bridges/doctor.command.ts","../src/diagnose-bridges/doctor-guidance.ts","../src/initialize-harnesses/init.command.ts","../src/initialize-harnesses/initialize-harnesses.ts"],"mappings":";;KAGY;;;;;KAaA;EACX,MAAM;EACN;EACA;;EAEA,aAAa;;;;;;;;;;;;cAaD,0BAA0B;;;;KC7B3B;;;KCEA;KACA;KAEA;EACX,SAAS;;EAET;EACA,MAAM;EACN,QAAQ;;KAGG;EACX;EACA;;EAEA;;KAGW;EACX;EACA,WAAW;;KAGA;EACX;EACA,YAAY;;EAEZ;;KAGW;EACX,SAAS;EACT,YAAY;EACZ,UAAU;;;;;;;iBA8EK,kBAAkB,MAAM,WAAW,WAAgB,OAAO,kBAAkB;;;cC7E/E,eAAe,MAAI;;;;;;;;;KClCpB;KAWA;EACX,SAAS;;EAET;;;;;EAKA,OAAO,cAAc;;;;;;EAMrB,YAAY;;cAqDA,wBAAwB;cAmExB;WACZ;WACA;;;;;;;iBAae,kBAAkB;;;cChKrB,aAAa,MAAI;cA0DjB,gBAAgB,MAAI;iBAMjB,WAAW;EAAgB,WAAW,gBAAgB;;;;KCnE1D;EACX;EACA,YAAY;EACZ;EACA;;KAEW;EACX;EACA,WAAW;EACX,QAAQ;EACR,QAAQ;;EAER;IAAc,MAAM;IAAa,YAAY;;EAC7C;EACA;;iBAGe,sBACf,MACA,WAAW,WACX,MACA,SACE,oBAAoB"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/harness-registry/instruction-bridge.ts","../src/harness-registry/mcp-config.ts","../src/harness-registry/nonstandard-artifact.ts","../src/harness-registry/harness-registry.ts","../src/diagnose-bridges/diagnose-instructions.ts","../src/diagnose-bridges/locator.ts","../src/diagnose-bridges/doctor-guidance.ts","../src/diagnose-bridges/git-bridge-state.ts","../src/diagnose-bridges/diagnose-bridges.ts","../src/diagnose-configuration/diagnose-configuration.ts","../src/diagnose-bridges/doctor.command.ts","../src/diagnose-mcp/diagnose-mcp.ts","../src/diagnose-mcp/mcp-model.ts","../src/diagnose-mcp/mcp-baseline.ts","../src/diagnose-mcp/mcp-sources.ts","../src/initialize-harnesses/init.command.ts","../src/skill-projection/skill-projection.ts","../src/initialize-harnesses/initialize-harnesses.ts"],"mappings":";;;;;;;;;;;;;;;KAYY;;;;;;EAOT;;EAEA;;;EAIA;;EAEA;;EAEA;;;;;;;;;;;;;;;;;;;;KCbS;;EAEX;;;;;;EAMA;;;;;EAKA;;;;;;EAMA;;;;;;;;;;;;;;;;;KCtBW;KAgBA;;;;;EAKX;;EAEA;EACA,MAAM;;;;KC/BK;;KAUA;;;;;;;;;;;;;;;;;;;;;;;;;KA0BA;EACX;EACA;EACA,oBAAoB;EACpB,YAAY;EACZ,uBAAuB;;KAGZ;EACX,MAAM;;EAEN,SAAS;;;;;EAKT,OAAO;;EAEP,aAAa;;;;;;;;;;;;;;;;;;;;;;cAuBD,0BAA0B;;;;KCzE3B;;;;;;KAMA;KAEA;EACX,SAAS;;EAET;EACA,MAAM;EACN,QAAQ;;;;;;;;;;iBAkFO,qBACf,cACA,oBAAoB,WACpB;EACI,cAAc;EAAqB,UAAU;;;;;;;;;;;;;;;;;;;;KC5FtC;EAAa;EAAc;;KAE3B;;EAEX;;EAEA;;EAEA;;EAEA,WAAW;;;;;;;;;;KCfA;;;;;;;;;;;KAqBA;;;;;;;;;KAUA;;;;;;;;;KAoBA;KAOA;;KAOA,gBAAgB,gBAAgB,qBAAqB,qBAAqB,aAAa;;KAGvF,uBAAuB;;;;;;;;;;;;;;;;;;KAmBvB;;EAEX;;EAEA;;KAGW;EACX,SAAS;;EAET;;;;;;;EAOA,OAAO,IAAI,SAAS,cAAc;;;;;;EAMlC,YAAY,IAAI;;cAwKJ,wBAAwB;cA4CxB,6BAA6B;cAuM7B,wBAAwB;cAOxB;WACZ;WACA;;;;;;;;;;iBAmCe,kBAAkB;;;;KC5jBtB;;KAGA;;;;;;cAwBC;mBAIA;;mBAFK;EAEjB,YAAY;;;;;;EASZ,WAAW,eAAe;;;;;;;EAa1B,UAAU;;;;;;;;;EAaV,gBAAgB;;EAMhB,UAAU,gBAAgB;;;;;EAS1B,YAAY,gBAAgB,oBAAoB;;UAYxC;;;;;UAmBA;;;;KC5GG;KACA;KAEA;EACX,SAAS;;EAET;EACA,MAAM;EACN,QAAQ;;KAGG;EACX;;;;;EAKA,SAAS;EACT;;EAEA,QAAQ;;KAGG;EACX;EACA,WAAW;;KAGA;EACX;EACA,YAAY;;EAEZ;;KAGW;EACX,SAAS;;;;;EAKT,cAAc;EACd,YAAY;EACZ,UAAU;;;;;;;iBA2EK,kBAAkB,MAAM,WAAW,WAAgB,OAAO,kBAAkB;;;;;;;;;;;;;;;;;KC1GhF;;EAEX;EACA,SAAS;EACT;;EAEA,QAAQ;;;;KCfG;EACX;EACA,SAAS;EACT,cAAc;EACd,aAAa;;;;;EAKb;IAAY;IAAc,SAAS;IAAe;;;;;;;;;;EASlD,OAAO;;;;;;iBAOQ,kBACf,aACA,QAAQ,gBACR,gBAAe,yBACb;cAgCU,eAAe,MAAI;;;;;;;;;;;;;;;;;;KC7CpB;EACX;EACA,KAAK;;EAEL;;iBAgCe,cAAc,MAAM,KAAK,OAAO,qBAAqB;;;;;;;;;;;;;;;;KClDzD;KAEA;EACX,YAAY;EACZ;EACA;EACA,MAAM,SAAS;EACf;EACA,UAAU,SAAS;EACnB;EACA;EACA;EACA;;;cAIY;KAaD,mBAAmB;;;;KCnCnB;;;;cCAC;;;cCAA,aAAa,MAAI;cAoDjB,gBAAgB,MAAI;iBAMjB,WAAW;EAAgB,WAAW,gBAAgB;;;;;;;;;KCV1D;;;KCpDA;EACX;EACA,YAAY;EACZ;EACA,QAAQ;;KAEG;EACX;EACA,WAAW;EACX,QAAQ;EACR,QAAQ;;EAER,SAAS;;EAET;IAAc,MAAM;IAAa,YAAY;;EAC7C;EACA;;iBAGe,sBACf,MACA,WAAW,WACX,MACA,SACE,oBAAoB"}

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { a as doctorCommand, c as doctorSkill, i as initializeHarnesses, l as renderDoctorSkill, n as harnessCommand, o as diagnoseBridges, r as initCommand, s as doctorRepairs, t as activate, u as harnessRegistry } from "./init.command-c0fBv15T.mjs";
-export { activate, diagnoseBridges, doctorCommand, doctorRepairs, doctorSkill, harnessCommand, harnessRegistry, initCommand, initializeHarnesses, renderDoctorSkill };
+import { _ as harnessRegistry, a as initializeHarnesses, c as diagnoseBridges, d as goldenSetPath, f as bridgeRepairs, g as renderDoctorSkill, h as instructionRepairs, i as initCommand, l as diagnoseInstructions, m as doctorSkill, n as activate, o as buildDoctorReport, p as doctorRepairs, r as harnessCommand, s as doctorCommand, t as run, u as diagnoseMcp } from "./cli-Bvnq8zOL.mjs";
+export { activate, bridgeRepairs, buildDoctorReport, diagnoseBridges, diagnoseInstructions, diagnoseMcp, doctorCommand, doctorRepairs, doctorSkill, goldenSetPath, harnessCommand, harnessRegistry, initCommand, initializeHarnesses, instructionRepairs, renderDoctorSkill, run };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buddy-agent-harness",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Initialize standards-based agent configuration across agent harnesses",
   "keywords": [
     "repobuddy",
@@ -46,7 +46,8 @@
   },
   "dependencies": {
     "@toon-format/toon": "^4.1.1",
-    "clibuilder": "^10.0.0"
+    "clibuilder": "^10.0.0",
+    "smol-toml": "^1.8.0"
   },
   "devDependencies": {
     "@types/node": "^24.12.4",