buddy-agent-harness 0.6.0 → 0.7.0

package/skills/init/references/detection.md

@@ -8,11 +8,13 @@ What to look for during the survey, and where each finding belongs.
 | Nested instructions | `**/AGENTS.md` below the root, and any `**/CLAUDE.md` beside one | canonical and scoped — report, never merge upward. Bridging is per directory and per approval; see `agents-md.md` |
 | Skills | `.claude/skills/`, `.cursor/skills/`, `.codex/skills/`, `.github/skills/`, `.windsurf/skills/`, `.gemini/skills/` | move to `.agents/skills/`, fix frontmatter, then link back |
 | Commands | `.claude/commands/*.md`, `.cursor/commands/*.md` | move to `.agents/skills/<name>/SKILL.md`. Claude Code has merged commands into skills, so this follows the harness rather than fighting it |
-| Subagents | `.claude/agents/` | canonical-only — no cross-harness format exists. Report; leave in place |
-| Rules | `.cursor/rules/**.mdc`, `.claude/rules/`, `.windsurf/rules/` | canonical-only — `.mdc` and `.md` are not interchangeable, and path-scoping syntax differs. Report |
-| MCP servers | `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `.claude/settings.json` | canonical-only. Report; never convert between formats |
+| Subagents | `.claude/agents/` | canonical-only — no cross-harness format exists. Report as having no candidate at all, so the list is not read as pending work; leave in place |
+| Rules | `.cursor/rules/**.mdc`, `.claude/rules/`, `.windsurf/rules/` | offer a skill where the paths a rule names are incidental to what it says; leave it where the path scoping is the point. `.mdc` and `.md` are not interchangeable and path-scoping has no `AGENTS.md` equivalent, so the choice is the owner's — ask per rule |
+| MCP servers | `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `.claude/settings.json` | canonical-only. Report; never convert between formats. A mapping between them exists but is not lossless, and applying it means inventing fields the source did not carry |
 | Hooks, LSP, output styles | hook blocks in settings files, `.claude/output-styles/` | canonical-only. Hook event names differ by case across harnesses, so no safe projection exists. Report |
 
+`doctor` reports every artifact only one harness can read, each with the canonical form it is a candidate for. That report is the list — the table above says what each class *is*, and the command says what this repository actually has. Do not derive a second list by walking these paths yourself.
+
 For every entry, record which of three states it is in:
 
 - a real file or directory the user authored,

package/skills/init/references/harnesses/cursor.md

@@ -14,10 +14,17 @@ Tell the user: a repository that consolidates into `AGENTS.md` keeps its instruc
 
 ## Do not
 
-- **Do not generate `.cursor/rules/*.mdc` from `AGENTS.md`.** Rules are canonical-only — `.mdc` and `.md` are not interchangeable and path-scoping has no `AGENTS.md` equivalent.
-- **Do not delete or rewrite `.cursorrules` or `.cursor/rules/**` on the assumption that `AGENTS.md` covers them.** In Chat and Composer it does not.
+- **Do not generate `.cursor/rules/*.mdc` from `AGENTS.md`.** `.mdc` and `.md` are not interchangeable and path-scoping has no `AGENTS.md` equivalent, so a generated rule would be inventing scope the source never carried.
+- **Do not delete or rewrite `.cursorrules` or `.cursor/rules/**` on the assumption that `AGENTS.md` covers them.** In Chat and Composer it does not. This is the reason a migration is *offered* rather than applied: the owner is agreeing to a trade, and they cannot agree to one nobody described.
 - Do not assert whether Cursor's `.agents/skills` discovery recurses into nested subdirectories. It is untested.
 
+## Migrating a rule, when the owner asks for it
+
+Offer, never assume, and offer the whole thing:
+
+- **A rule whose paths are incidental** — guidance that happens to name files but says something generally true — becomes a skill under `.agents/skills/`, which every harness reads. A rule whose scoping *is* the point has no equivalent; say so and leave it.
+- **Consolidating `.cursorrules` into `AGENTS.md` narrows who reads it** unless a copy stays behind for Chat and Composer. Offer the consolidation and the copy together. Never offer the consolidation alone, and never delete the file because `AGENTS.md` now carries the words.
+
 ## Frontmatter
 
 `paths`, `disable-model-invocation`, and legacy `globs` are Cursor-recognized. Other harnesses drop them — keep load-bearing behavior in the body, per `frontmatter.md`.

package/skills/init/scripts/doctor.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-skills.ts. Do not edit by hand.
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+// <package>/skills/<skill>/scripts/doctor.mjs: four levels up is the package root.
+const packageRoot = dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))))
+const { run } = await import(pathToFileURL(join(packageRoot, 'dist', 'cli.mjs')).href)
+
+// The subcommand is composed into a fresh argv rather than spliced into the global one, so nothing
+// outside this file observes the rewrite. Applied only when non-zero, so a usage code clibuilder
+// recorded itself is not overwritten by the zero `run` returns on that path.
+const code = await run([...process.argv.slice(0, 2), 'doctor', ...process.argv.slice(2)])
+if (code !== 0) process.exitCode = code

package/skills/init/scripts/init.mjs

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
 // Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-skills.ts. Do not edit by hand.
 import { dirname, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 
 // <package>/skills/<skill>/scripts/init.mjs: four levels up is the package root.
 const packageRoot = dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))))
+const { run } = await import(pathToFileURL(join(packageRoot, 'dist', 'cli.mjs')).href)
 
-process.argv.splice(2, 0, 'init')
-await import(join(packageRoot, 'bin', 'buddy-agent-harness.mjs'))
+// The subcommand is composed into a fresh argv rather than spliced into the global one, so nothing
+// outside this file observes the rewrite. Applied only when non-zero, so a usage code clibuilder
+// recorded itself is not overwritten by the zero `run` returns on that path.
+const code = await run([...process.argv.slice(0, 2), 'init', ...process.argv.slice(2)])
+if (code !== 0) process.exitCode = code

package/skills/repair/README.md

@@ -0,0 +1,21 @@
+# Harness Repair
+
+Correct agent configuration a repository already has that is wrong or outdated.
+
+## What it does
+
+`init` consolidates what a repository has, `enhance` offers what it is missing, and `doctor` reports what is wrong. Configuration that is present but **wrong** falls between all three, and that is what this skill takes: a harness name the registry retired, a git-ignored bridge, an `AGENTS.local.md` nothing reads, a skill whose frontmatter makes a harness skip it.
+
+Each correction is offered with the file as it stands and as it would read, and written only on approval.
+
+## Why a fourth skill rather than a `--fix` flag
+
+`doctor` stays read-only. Its whole safety property is that it never writes, which is what makes it safe to run from a session-start hook — a repair flag would forfeit that for every caller. Its **bridge** findings are all repairable with existing `init` flags, so a flag there would duplicate `init` rather than add anything; its **configuration** findings need judgment about files you wrote, which is a skill's job and not a flag's.
+
+That split also defines this skill's remit. `repair` owns what `init` deliberately refuses. Every bridge finding — including an instruction bridge that was never completed — is reported and handed to `init`, which is what writes bridges in the first place.
+
+## The line it does not cross
+
+`repair` corrects what the **tooling** decides is wrong, never what the project means. The discriminator is the one `init` already applies: content that would stop being true if this tool's output were removed is non-material, and non-material content is all this skill may correct. A statement about how the repository is worked in stays the user's, even when it is out of date — `repair` reports it and offers no write.
+
+`references/classes.md` carries the detection, the correction, and the stopping point for each class.

package/skills/repair/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: repair
+description: Use this skill when a repository's agent configuration is present but wrong or outdated — a retired harness name, a git-ignored bridge, an AGENTS.local.md nothing reads, or a skill a harness refuses to load. Runs doctor to find them, then offers each correction with its before and after and writes only what is approved.
+---
+
+# Harness Repair
+
+`init` consolidates what a repository has. `enhance` proposes what it does not. `doctor` reports what is wrong. `repair` corrects it.
+
+Each of the other three refuses this work deliberately. `init` has to run anywhere and invent nothing, so it never clobbers a file the user wrote. `enhance` only offers what is **missing**. `doctor` never writes, which is what makes it safe in a session-start hook. Configuration that is present but wrong falls between them.
+
+**`doctor` detects; this skill repairs.** Detection has one home, so the two cannot drift and the finding set can grow without touching this file. Do not detect anything yourself — run the command and repair what it reports.
+
+## 1. Diagnose
+
+```sh
+node scripts/doctor.mjs
+```
+
+That path is relative to this skill's own directory. The launcher runs the CLI that shipped beside it against the current working directory, so nothing is downloaded. Fall back to `npx -y buddy-agent-harness@^0.5.0 doctor` when the launcher cannot be resolved or run.
+
+The default output is TOON, which is what you parse. Each entry in `findings` carries three fields: `problem` (the finding's name), `path` (what it is about), and `detail` (what is wrong, in prose). The repairs are not on the row — they are lifted into `help`, which follows `findings` in order and collapses two entries only where the repair is word-for-word identical. Read a finding's repair off the matching position and confirm it by the `path` it names; where two findings sit at one path, what each repair says to do is what tells them apart.
+
+**Route on `problem`, never on `detail`.** The prose exists to be read by a person, and rewording it must not change what you do.
+
+If `findings` reports zero problems, say so and stop. There is nothing to repair.
+
+## 2. Sort what it found
+
+**Route on `problem`.** `references/classes.md` carries one section per fault this skill corrects, keyed by the `problem` name. A `problem` with a section there is yours; a `problem` without one is not. Nothing else decides it.
+
+That rule holds for every finding `doctor` reports today and for the ones it reports next year. A fault this skill has no correction for is not one it can repair, so what `classes.md` covers and what this skill owns are the same fact — and a finding added tomorrow gets reported rather than improvised on.
+
+**Do not read ownership off a skill name in `help`.** Most repairs name no skill — some are a shell invocation, some a `git` command, some a reconciliation by hand — and only the instruction and configuration families name one at all. An owner is not something the report can always be asked for.
+
+- **Findings that are yours.** Look the `problem` up in `references/classes.md`, which carries the correction and the stopping point for each.
+- **Findings that are not yours.** Report each one and pass on the repair `doctor` states for it, unchanged. **Who to hand it to is read off that repair, and the question is whether it names `init`.** Some name the `/buddy-agent-harness:init` skill and some name a `buddy-agent-harness init` command line; both mean the same thing — the finding is `init`'s, because `init` writes both kinds of bridge in the first place, and it writes the `CLAUDE.md` stub *without* asking, where everything here needs approval, and one write cannot have two homes and two contradictory approval rules. Hand it to the **skill** and never run the command yourself: rebuilding a projection can relocate skills a user wrote, and on the Windows case the naive repair is to recreate the link, the operation that already failed on that machine. A repair naming `init` in **neither** form — a `git` invocation, a reconciliation by hand, every MCP finding — is work for a person; say that rather than inferring an owner, and never rebuild over a two-sided divergence, which discards whichever side holds the newer edit.
+
+## 3. Draw the line at material content
+
+You correct what the **tooling** decides is wrong, never what the repository means.
+
+`../init/references/agents-md.md` draws the line: content that would stop being true if this tool's output were removed is **non-material**, and non-material content is all you may correct. A statement about how the repository is worked in is the user's, even when it is out of date — report it and offer no write.
+
+The clearest case is `unloadable-skill`. A `description` broken by an unquoted colon is a quoting fault — correct it. A `description` that is **missing** cannot be written without asserting what a skill you did not author does, and that claim holds whether or not this tool ever ran. Report it and ask.
+
+## 4. Offer
+
+Show the file **as it stands and as it would read**. Not a summary — the actual before and after, so the user is reading the change rather than your description of it.
+
+Where more than one correction is valid, present the options and ask which. Never pick for the user. `unread-local-override` is always this case, and its options come from `references/classes.md` — `doctor` names one repair per finding and has not read the file's contents.
+
+Do not argue past one sentence. The diff is the argument.
+
+## 5. Apply and re-run
+
+Write only what was approved, preserving the rest of the file exactly.
+
+Then **run `doctor` again**. A correction can fail to hold — a second `.gitignore` rule matching the same path, a frontmatter fix that leaves another fault behind. Re-running is how you know, and it costs nothing. When a finding survives, say it is still open rather than reporting it landed.
+
+## 6. Report
+
+Report every run, whichever way it went. One row per finding, naming its **path**, what was wrong, and its **outcome** — corrected, declined, handed to `init`, reported as material, or still open.
+
+A run that finds nothing still reports. "Nothing found" without saying `doctor` ran clean is indistinguishable from not having looked.
+
+## Rules
+
+- **Never write without approval.** There is no flag that skips it and none should be added.
+- **Never detect.** `doctor` owns detection. A check written here is a second home for it, and two homes drift.
+- **Never rebuild a bridge.** That is `doctor`'s diagnosis and `init`'s repair.
+- **Never consolidate.** Moving content into `AGENTS.md` is `init`'s and has one home.
+- **Correct only non-material content.** Project policy is the user's, even when it is wrong.
+- Local agent configuration only. Do not change workflows, GitHub Actions, repository settings, security scanning, branch rules, or unrelated project files — a retired harness name in a workflow file is not yours to rename.

package/skills/repair/references/classes.md

@@ -0,0 +1,49 @@
+# Correction classes
+
+One row per fault `doctor` reports here, with the correction and where it stops.
+
+**This file carries no detection.** `doctor` decides what is wrong; you decide how to correct it. If you find yourself checking whether a fault is present, you are doing the command's job — run it instead.
+
+Every correction below is non-material: it would stop being true if this tool's output were removed. That is what makes it correctable at all. Where a finding's correction would change what the repository *means*, report it and stop; `../../init/references/agents-md.md` draws the line.
+
+## `deprecated-harness`
+
+**Correct.** The replacement harness reads `.agents/skills/` natively and needs no projection at all, so the correction is to **delete** the reported projection — not to rename it, and not to create a new one under the new name. This is the one correction that removes a path rather than editing a file, so show what will be deleted and what will remain.
+
+**Stops at.** Everything under that harness's directory that is not the skills projection. `.windsurfrules` and any settings file are instruction artifacts; consolidating them is `init`'s. A harness name in a workflow, a README, or a comment is prose, not configuration — leave it.
+
+## `ignored-bridge`
+
+**Correct.** Narrow or remove the reported `.gitignore` rule so the bridge is tracked. Where the rule exists for something else under that directory, the correction is a negation (`!.claude/skills`) rather than a deletion — that keeps the rest of the rule doing its job.
+
+**Stops at.** Every rule that does not match a bridge path. `.gitignore` is a project file, and only the part swallowing a bridge is this tool's business.
+
+## `unread-local-override`
+
+**More than one correction is valid, so this fault always presents options and never picks.** The options come from this file, not from the report: `doctor` names one repair per finding, and choosing among these is a judgment about content it has not read.
+
+Read the file to describe the options, then offer all three:
+
+- move it to `CLAUDE.local.md` and add that to `.gitignore`, where the content is personal and Claude Code is the reader that matters;
+- hand it to `init` to consolidate into `AGENTS.md`, where the content is project guidance — that move is material, and `init`'s;
+- delete it, where it is dead.
+
+**Stops at.** The content. Read it to describe the options; never rewrite it.
+
+## `unloadable-skill`
+
+Two faults arrive under this name, and only one of them is correctable.
+
+**An unquoted colon in `description`.** Correctable: quote the value. The YAML then parses and the skill loads.
+
+**A missing or empty `description`.** **Not correctable — report it and ask.** Writing one would mean inventing a claim about what a skill you did not author does, and that claim is material: it stays true whether or not this tool ever ran. Name the skill, say why it will not load, and stop.
+
+**Stops at.** Everything below the frontmatter. The skill body is the author's. A `name` that mismatches its directory is not reported by `doctor` at all — it is a warning and the skill still loads.
+
+## Not yours: every `problem` with no section above
+
+`doctor` reports far more than this file covers: skills bridges that no longer resolve, instruction bridges that were never completed, and drift between the golden MCP server set and a harness's copy of it. None of them has a section here, and that is what says they are not yours.
+
+**Who to hand one to is read off the repair `doctor` gave it, and the question is whether it names `init`.** It names it one of two ways — the `/buddy-agent-harness:init` skill, or a `buddy-agent-harness init` command line — and both mean the finding is `init`'s, which writes both kinds of bridge in the first place and writes a `CLAUDE.md` stub *without* asking, where every correction here needs approval. Hand it to the skill; never run the command. A repair naming `init` in **neither** form is work for a person: `doctor` states it in full, and passing it on is the whole of what you do with it. Every MCP finding is that second case, as is every bridge finding a rebuild would not fix.
+
+Never infer an owner for a finding that names none. The wrong guess is always `init`, and on a two-sided divergence rebuilding is precisely what discards whichever side holds the newer edit.

package/skills/repair/scripts/doctor.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-skills.ts. Do not edit by hand.
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+// <package>/skills/<skill>/scripts/doctor.mjs: four levels up is the package root.
+const packageRoot = dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))))
+const { run } = await import(pathToFileURL(join(packageRoot, 'dist', 'cli.mjs')).href)
+
+// The subcommand is composed into a fresh argv rather than spliced into the global one, so nothing
+// outside this file observes the rewrite. Applied only when non-zero, so a usage code clibuilder
+// recorded itself is not overwritten by the zero `run` returns on that path.
+const code = await run([...process.argv.slice(0, 2), 'doctor', ...process.argv.slice(2)])
+if (code !== 0) process.exitCode = code

package/src/cli.ts

@@ -1,17 +1,50 @@
-import { cli } from 'clibuilder'
+import { readFileSync } from 'node:fs'
+import { cli, exitCodes } from 'clibuilder'
 import { doctorCommand } from './diagnose-bridges/doctor.command.ts'
 import { initCommand } from './initialize-harnesses/init.command.ts'
 
-export async function main(): Promise<void> {
-	const app = cli({
+/**
+ * Read from the manifest rather than restated here: a version written into this call is a second
+ * home for a number that already has one, and it stayed at `0.1.0` for five minor releases.
+ *
+ * `../package.json` resolves from `src/cli.ts` and from the bundled `dist/cli.mjs` alike — both sit
+ * one directory under the package root.
+ */
+const version = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version as string
+
+/**
+ * A factory rather than a module-level constant: `cli()` builds state, and state built at import
+ * time is shared by every later call in the process.
+ */
+function app() {
+	return cli({
 		name: 'buddy-agent-harness',
-		version: '0.1.0',
+		version,
 		description: 'Initialize agent harness skill compatibility in consumer repositories.',
 	})
+		.command(initCommand)
+		.command(doctorCommand)
+}
+
+/**
+ * The application boundary: argv in, exit code out, nothing read from or written to the process.
+ *
+ * The exit code is returned rather than written so that a caller which is not the process — a skill
+ * launcher, a test — can run a command and learn how it went. `bin/buddy-agent-harness.mjs` is the
+ * only place that turns the returned code back into a process outcome.
+ *
+ * One exit path this return cannot carry: `clibuilder` answers an unknown option or an unknown
+ * command by printing help and writing `process.exitCode` itself, returning nothing. `run` reports
+ * `0` there, which is why `bin` and the launchers apply the returned code only when it is non-zero.
+ */
+export async function run(argv: string[]): Promise<number> {
 	try {
-		await app.command(initCommand).command(doctorCommand).parse(process.argv)
+		const code = await app().parse<number | undefined>(argv)
+		return typeof code === 'number' ? code : exitCodes.success
 	} catch (error) {
-		process.stdout.write(`error: ${error instanceof Error ? error.message : 'Invalid command.'}\n`)
-		process.exitCode = 2
+		// stderr, not stdout: `doctor`'s default output is TOON that an agent parses, and an error
+		// line on that stream lands in the middle of what it is parsing.
+		process.stderr.write(`error: ${error instanceof Error ? error.message : 'Invalid command.'}\n`)
+		return exitCodes.usage
 	}
 }

package/src/command-output/command-output.ts

@@ -1,5 +1,6 @@
 import { sep } from 'node:path'
 import { encode } from '@toon-format/toon'
+import { isRecord } from '../is-record/is-record.ts'
 
 export type OutputFormat = 'json' | 'toon' | 'text'
 
@@ -21,10 +22,6 @@ function encodeResult(value: object, format: OutputFormat): string {
 	return format === 'text' ? renderText(value) : encode(value)
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
 function cell(value: unknown): string {
 	return value === undefined ? '' : String(value)
 }

package/src/diagnose-bridges/diagnose-bridges.ts

@@ -1,9 +1,10 @@
-import { lstatSync, readFileSync, readlinkSync, statSync } from 'node:fs'
-import { dirname, join, relative } from 'node:path'
+import { lstatSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
 import { type HarnessName, selectHarnesses } from '../harness-registry/harness-registry.ts'
+import { linksTo } from '../skill-projection/skill-projection.ts'
 import { diagnoseInstructions, type InstructionReport } from './diagnose-instructions.ts'
 import { filesUnder } from './directory-files.ts'
-import { type BridgeProblem, repairFor } from './doctor-guidance.ts'
+import { type BridgeProblem, type DoctorProblem, type RepairAction, repairFor } from './doctor-guidance.ts'
 import { type DivergenceDirection, GitBridgeState } from './git-bridge-state.ts'
 
 export type BridgeKind = 'symlink' | 'copy' | 'file' | 'none'
@@ -19,9 +20,14 @@ export type BridgeReport = {
 
 export 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
 }
 
 export type DivergenceReport = {
@@ -67,11 +73,6 @@ function isDirectory(path: string): boolean {
 	}
 }
 
-/** The same test `init` uses to decide a projection is already correct, plus that it still resolves. */
-function resolvesToCanonical(target: string, canonical: string): boolean {
-	return readlinkSync(target) === relative(dirname(target), canonical) && isDirectory(target)
-}
-
 function sameContent(left: string, right: string): boolean {
 	const leftFiles = filesUnder(left)
 	const rightFiles = filesUnder(right)
@@ -99,8 +100,10 @@ function inspect(target: string, path: string, canonical: string, git: GitBridge
 		// regular file holding the target path, and the harness silently loads nothing.
 		case 'file':
 			return { kind: 'file', status: 'degraded', problem: 'degraded' }
+		// The very test `init` uses to decide a projection is already correct, so a bridge `init` would
+		// leave alone never reports as one `doctor` wants rebuilt.
 		case 'symlink':
-			return resolvesToCanonical(target, canonical)
+			return linksTo(target, canonical)
 				? { kind: 'symlink', status: 'ok' }
 				: { kind: 'symlink', status: 'stale', problem: 'stale' }
 		default: {
@@ -136,7 +139,12 @@ export function diagnoseBridges({ root, harnesses: preferred = [], cli }: Diagno
 
 	if (!isDirectory(canonical)) {
 		const { detail, repair } = repairFor('no-canonical')
-		findings.push({ path: canonicalPath, detail, repair: repair(canonicalPath, cli) })
+		findings.push({
+			path: canonicalPath,
+			problem: 'no-canonical',
+			detail,
+			repair: repair({ file: canonicalPath }, cli),
+		})
 	}
 
 	for (const harness of bridged) {
@@ -146,7 +154,7 @@ export function diagnoseBridges({ root, harnesses: preferred = [], cli }: Diagno
 		if (inspection.direction) divergence.push({ path, direction: inspection.direction })
 		if (inspection.problem) {
 			const { detail, repair } = repairFor(inspection.problem)
-			findings.push({ path, detail, repair: repair(path, cli) })
+			findings.push({ path, problem: inspection.problem, detail, repair: repair({ file: path }, cli) })
 		}
 	}
 

package/src/diagnose-bridges/diagnose-instructions.ts

@@ -122,7 +122,12 @@ export function diagnoseInstructions(
 	// lies, so its absence is a repository that has not run `init` rather than a broken bridge.
 	if (!agentsFileDirectories(root).includes('')) {
 		const { detail, repair } = repairFor('no-instructions')
-		findings.push({ path: canonicalInstructions, detail, repair: repair(canonicalInstructions, cli) })
+		findings.push({
+			path: canonicalInstructions,
+			problem: 'no-instructions',
+			detail,
+			repair: repair({ file: canonicalInstructions }, cli),
+		})
 	}
 
 	for (const { name, bridge } of bridged) {
@@ -131,7 +136,7 @@ export function diagnoseInstructions(
 			instructions.push({ harness: name, path, kind: inspection.kind, status: inspection.status })
 			if (inspection.problem) {
 				const { detail, repair } = repairFor(inspection.problem)
-				findings.push({ path, detail, repair: repair(path, cli) })
+				findings.push({ path, problem: inspection.problem, detail, repair: repair({ file: path }, cli) })
 			}
 		}
 	}