buddy-agent-harness 0.13.1 → 0.15.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "buddy-agent-harness",
-	"version": "0.13.1",
+	"version": "0.15.0",
 	"description": "Initialize standards-based agent configuration across agent harnesses",
 	"author": {
 		"name": "repobuddy"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "buddy-agent-harness",
-	"version": "0.13.1",
+	"version": "0.15.0",
 	"description": "Initialize standards-based agent configuration across agent harnesses",
 	"author": {
 		"name": "repobuddy"

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "buddy-agent-harness",
-	"version": "0.13.1",
+	"version": "0.15.0",
 	"description": "Initialize standards-based agent configuration across agent harnesses",
 	"author": {
 		"name": "repobuddy"

package/dist/cli.mjs

@@ -27118,6 +27118,7 @@ function pluginLabel(layer) {
 function layerName(layer) {
 	return layer.tier === "plugin" ? `plugin ${pluginLabel(layer)}` : layer.tier;
 }
+/** The layers a name is resolved through, in the order `resolveReference` traces them. */
 function layersFor$2(ref, layers) {
 	const plugin = ref.plugin;
 	if (plugin === void 0) return [...layers];
@@ -28551,70 +28552,160 @@ const listFormatOption = {
 	type: optionalType(stringType()),
 	default: "toon"
 };
+const referenceListCommand = command({
+	name: "list",
+	description: "List every layer, and every reference at every layer that holds it, marked used or shadowed.",
+	options: {
+		root: rootOption,
+		format: listFormatOption
+	},
+	async run(args) {
+		try {
+			const format = parseFormat(args.format);
+			const home = homedir();
+			const layers = await layersFor(args, home);
+			const { rows, warnings } = listReferences(layers, { display: (path) => collapseHome(home, path) });
+			const report = {
+				layers: layers.map(({ tier, plugins, dir, status }) => ({
+					tier,
+					plugin: plugins[0] ?? "",
+					path: collapseHome(home, dir),
+					status
+				})),
+				references: rows.length ? rows.map((row) => ({
+					...row,
+					path: collapseHome(home, row.path)
+				})) : "0 references — no layer holds one"
+			};
+			if (warnings.length) report.warnings = warnings;
+			writeResult(report, format);
+			return exitCodes.success;
+		} catch (error) {
+			return fail(error, "Reference listing failed.");
+		}
+	}
+});
+const referenceSearchCommand = command({
+	name: "search",
+	description: "Find references by name, description, tags, headings, or body, best match first.",
+	arguments: [{
+		name: "query",
+		description: "What the reference is about.",
+		type: stringType()
+	}],
+	options: {
+		root: rootOption,
+		format: listFormatOption
+	},
+	async run(args) {
+		try {
+			const format = parseFormat(args.format);
+			const query = args.query.trim();
+			if (!query) throw new Error("Search needs a query.");
+			const home = homedir();
+			const matches = searchReferences(query, await layersFor(args, home), { display: (path) => collapseHome(home, path) });
+			writeResult({
+				query,
+				references: matches.length ? matches : `0 references match "${query}"`
+			}, format);
+			return exitCodes.success;
+		} catch (error) {
+			return fail(error, "Reference search failed.");
+		}
+	}
+});
+/** Managed is left out: writing there needs an admin, and most of it cannot be read locally. */
+const slotScopes = {
+	project: "everyone working in this repository",
+	user: "only you, in every repository",
+	plugin: "read-only; override it with the project or user file"
+};
+const callerScope = "read-only; the calling skill's own copy, read only when no layer holds the name";
+const mergeNote = "The default, first-wins, makes the override replace the whole document. Set `merge: merge-sections` in its frontmatter to keep the sections it does not redefine.";
+function slotStatus(outcome) {
+	if (outcome === "missing") return "empty";
+	return outcome.startsWith("shadowed") ? "shadowed" : outcome;
+}
+/** Where Load reads the caller's copy when no layer holds the name, in the order it tries them. */
+function callerCopy(caller, name) {
+	return [join(caller, "references", `${name}.md`), join(caller, "references", "governances", `${name}.md`)].find((path) => existsSync(path));
+}
+function callerStatus(resolved) {
+	if (resolved.status === "missing") return "used";
+	return resolved.status === "ambiguous" ? "not read — the name is ambiguous" : "shadowed";
+}
 const referenceCommand = command({
 	name: "reference",
 	description: "Read on-demand reference documents by name, layered across the managed, project, user, and plugin tiers. Read-only.",
 	commands: [
 		referenceShowCommand,
+		referenceListCommand,
+		referenceSearchCommand,
 		command({
-			name: "list",
-			description: "List every layer, and every reference at every layer that holds it, marked used or shadowed.",
+			name: "where",
+			description: "List the project and user files an override of a reference can be written to, highest precedence first, with the copy each overrides and who it applies to.",
+			arguments: [{
+				name: "name",
+				description: "Reference name, without the `.md` extension; `<plugin>/<name>` picks one plugin.",
+				type: stringType()
+			}],
 			options: {
 				root: rootOption,
+				caller: {
+					description: "Folder of the skill that loads the reference, so its own copy is reported as the reference skill's Load mode reads it.",
+					type: optionalType(stringType())
+				},
 				format: listFormatOption
 			},
 			async run(args) {
 				try {
 					const format = parseFormat(args.format);
+					const name = parseReferenceName(args.name);
 					const home = homedir();
 					const layers = await layersFor(args, home);
-					const { rows, warnings } = listReferences(layers, { display: (path) => collapseHome(home, path) });
+					const root = resolve(args.root ?? process.cwd());
+					const display = (path) => collapseHome(home, path);
+					const resolved = resolveReference(name, layers, { display });
+					const traced = layersFor$2(name, layers);
+					const slots = [];
+					for (const [index, step] of resolved.trace.entries()) {
+						const layer = traced[index];
+						const scope = slotScopes[step.tier];
+						if (!scope || (layer.status || step.tier === "plugin") && !step.found) continue;
+						const path = step.found ? step.path : join(layer.dir, `${name.name}.md`);
+						slots.push({
+							layer: step.tier === "plugin" ? `plugin ${step.plugin}` : step.tier,
+							path: step.tier === "project" ? relative(root, path) : display(path),
+							status: slotStatus(step.outcome),
+							scope
+						});
+					}
+					const copy = args.caller === void 0 ? void 0 : callerCopy(resolve(args.caller), name.name);
+					if (copy) slots.push({
+						layer: "caller",
+						path: display(copy),
+						status: callerStatus(resolved),
+						scope: callerScope
+					});
 					const report = {
-						layers: layers.map(({ tier, plugins, dir, status }) => ({
-							tier,
-							plugin: plugins[0] ?? "",
-							path: collapseHome(home, dir),
-							status
-						})),
-						references: rows.length ? rows.map((row) => ({
-							...row,
-							path: collapseHome(home, row.path)
-						})) : "0 references — no layer holds one"
+						name: name.name,
+						root: display(root),
+						slots,
+						merge: mergeNote
 					};
-					if (warnings.length) report.warnings = warnings;
+					if (resolved.status === "ambiguous") report.plugins = resolved.plugins;
+					if (resolved.warnings.length) report.warnings = resolved.warnings;
 					writeResult(report, format);
-					return exitCodes.success;
-				} catch (error) {
-					return fail(error, "Reference listing failed.");
-				}
-			}
-		}),
-		command({
-			name: "search",
-			description: "Find references by name, description, tags, headings, or body, best match first.",
-			arguments: [{
-				name: "query",
-				description: "What the reference is about.",
-				type: stringType()
-			}],
-			options: {
-				root: rootOption,
-				format: listFormatOption
-			},
-			async run(args) {
-				try {
-					const format = parseFormat(args.format);
-					const query = args.query.trim();
-					if (!query) throw new Error("Search needs a query.");
-					const home = homedir();
-					const matches = searchReferences(query, await layersFor(args, home), { display: (path) => collapseHome(home, path) });
-					writeResult({
-						query,
-						references: matches.length ? matches : `0 references match "${query}"`
-					}, format);
-					return exitCodes.success;
+					if (resolved.status !== "ambiguous") return exitCodes.success;
+					process.stderr.write(`error: ${missReason({
+						name: name.raw,
+						status: "ambiguous",
+						plugins: resolved.plugins,
+						warnings: []
+					})}\n`);
+					return exitCodes.error;
 				} catch (error) {
-					return fail(error, "Reference search failed.");
+					return fail(error, "Reference placement lookup failed.");
 				}
 			}
 		})
@@ -31605,12 +31696,26 @@ const mcpCommand = command({
 //#endregion
 //#region src/cli.ts
 const version = typeof __PACKAGE_VERSION__ !== "undefined" ? __PACKAGE_VERSION__ : JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+/** Exported for `scripts/generate-llms-txt.ts`, which lists the CLI from it; `app()` must stay built from it. */
+const rootCommand = {
+	name: "buddy-agent-harness",
+	description: "Initialize agent harness skill compatibility in consumer repositories.",
+	commands: [
+		initCommand,
+		doctorCommand,
+		mcpCommand,
+		depPluginsCommand,
+		referenceCommand,
+		governanceCommand
+	]
+};
 function app() {
-	return cli({
-		name: "buddy-agent-harness",
+	const [first, ...rest] = rootCommand.commands;
+	return rest.reduce((builder, command) => builder.command(command), cli({
+		name: rootCommand.name,
 		version,
-		description: "Initialize agent harness skill compatibility in consumer repositories."
-	}).command(initCommand).command(doctorCommand).command(mcpCommand).command(depPluginsCommand).command(referenceCommand).command(governanceCommand);
+		description: rootCommand.description
+	}).command(first));
 }
 /**
 * The application boundary: argv in, exit code out — returned rather than written, so a caller that
@@ -31626,4 +31731,4 @@ async function run(argv) {
 	}
 }
 //#endregion
-export { run };
+export { rootCommand, run };

package/dist/index.d.mts

@@ -651,7 +651,7 @@ type ListMcpServersOptions = {
 export declare function listMcpServers(options: ListMcpServersOptions): McpServerEntry[];
 //#endregion
 //#region src/references/reference.command.d.ts
-/** One per name asked, in the order asked — the contract the `load-reference` skill builds on. */
+/** One per name asked, in the order asked — the contract the `reference` skill's Load mode builds on. */
 type ReferenceShowEntry = {
   name: string;
   status: ResolvedReference["status"];

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/cli.ts","../src/harness-registry/instruction-bridge.ts","../src/diagnose-mcp/mcp-model.ts","../src/mcp-dialects/mcp-dialects.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/references/reference-layers.ts","../src/references/reference-document.ts","../src/references/resolve-reference.ts","../src/references/reference-catalog.ts","../src/diagnose-bridges/doctor.command.ts","../src/diagnose-mcp/diagnose-mcp.ts","../src/diagnose-mcp/mcp-baseline.ts","../src/diagnose-mcp/mcp-sources.ts","../src/governance-overrides/governance-overrides.ts","../src/governance-overrides/governance.command.ts","../src/initialize-harnesses/init.command.ts","../src/skill-projection/skill-projection.ts","../src/initialize-harnesses/initialize-harnesses.ts","../src/mcp-inventory/mcp-inventory.ts","../src/references/reference.command.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/cli.ts","../src/harness-registry/instruction-bridge.ts","../src/diagnose-mcp/mcp-model.ts","../src/mcp-dialects/mcp-dialects.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/references/reference-layers.ts","../src/references/reference-document.ts","../src/references/resolve-reference.ts","../src/references/reference-catalog.ts","../src/diagnose-bridges/doctor.command.ts","../src/diagnose-mcp/diagnose-mcp.ts","../src/diagnose-mcp/mcp-baseline.ts","../src/diagnose-mcp/mcp-sources.ts","../src/governance-overrides/governance-overrides.ts","../src/governance-overrides/governance.command.ts","../src/initialize-harnesses/init.command.ts","../src/skill-projection/skill-projection.ts","../src/initialize-harnesses/initialize-harnesses.ts","../src/mcp-inventory/mcp-inventory.ts","../src/references/reference.command.ts"],"mappings":"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"}

package/dist/index.mjs

@@ -2264,6 +2264,7 @@ function pluginLabel(layer) {
 function layerName(layer) {
 	return layer.tier === "plugin" ? `plugin ${pluginLabel(layer)}` : layer.tier;
 }
+/** The layers a name is resolved through, in the order `resolveReference` traces them. */
 function layersFor$2(ref, layers) {
 	const plugin = ref.plugin;
 	if (plugin === void 0) return [...layers];
@@ -3761,13 +3762,102 @@ const referenceSearchCommand = command({
 		}
 	}
 });
+/** Managed is left out: writing there needs an admin, and most of it cannot be read locally. */
+const slotScopes = {
+	project: "everyone working in this repository",
+	user: "only you, in every repository",
+	plugin: "read-only; override it with the project or user file"
+};
+const callerScope = "read-only; the calling skill's own copy, read only when no layer holds the name";
+const mergeNote = "The default, first-wins, makes the override replace the whole document. Set `merge: merge-sections` in its frontmatter to keep the sections it does not redefine.";
+function slotStatus(outcome) {
+	if (outcome === "missing") return "empty";
+	return outcome.startsWith("shadowed") ? "shadowed" : outcome;
+}
+/** Where Load reads the caller's copy when no layer holds the name, in the order it tries them. */
+function callerCopy(caller, name) {
+	return [join(caller, "references", `${name}.md`), join(caller, "references", "governances", `${name}.md`)].find((path) => existsSync(path));
+}
+function callerStatus(resolved) {
+	if (resolved.status === "missing") return "used";
+	return resolved.status === "ambiguous" ? "not read — the name is ambiguous" : "shadowed";
+}
+const referenceWhereCommand = command({
+	name: "where",
+	description: "List the project and user files an override of a reference can be written to, highest precedence first, with the copy each overrides and who it applies to.",
+	arguments: [{
+		name: "name",
+		description: "Reference name, without the `.md` extension; `<plugin>/<name>` picks one plugin.",
+		type: z.string()
+	}],
+	options: {
+		root: rootOption,
+		caller: {
+			description: "Folder of the skill that loads the reference, so its own copy is reported as the reference skill's Load mode reads it.",
+			type: z.optional(z.string())
+		},
+		format: listFormatOption
+	},
+	async run(args) {
+		try {
+			const format = parseFormat(args.format);
+			const name = parseReferenceName(args.name);
+			const home = homedir();
+			const layers = await layersFor(args, home);
+			const root = resolve(args.root ?? process.cwd());
+			const display = (path) => collapseHome(home, path);
+			const resolved = resolveReference(name, layers, { display });
+			const traced = layersFor$2(name, layers);
+			const slots = [];
+			for (const [index, step] of resolved.trace.entries()) {
+				const layer = traced[index];
+				const scope = slotScopes[step.tier];
+				if (!scope || (layer.status || step.tier === "plugin") && !step.found) continue;
+				const path = step.found ? step.path : join(layer.dir, `${name.name}.md`);
+				slots.push({
+					layer: step.tier === "plugin" ? `plugin ${step.plugin}` : step.tier,
+					path: step.tier === "project" ? relative(root, path) : display(path),
+					status: slotStatus(step.outcome),
+					scope
+				});
+			}
+			const copy = args.caller === void 0 ? void 0 : callerCopy(resolve(args.caller), name.name);
+			if (copy) slots.push({
+				layer: "caller",
+				path: display(copy),
+				status: callerStatus(resolved),
+				scope: callerScope
+			});
+			const report = {
+				name: name.name,
+				root: display(root),
+				slots,
+				merge: mergeNote
+			};
+			if (resolved.status === "ambiguous") report.plugins = resolved.plugins;
+			if (resolved.warnings.length) report.warnings = resolved.warnings;
+			writeResult(report, format);
+			if (resolved.status !== "ambiguous") return exitCodes.success;
+			process.stderr.write(`error: ${missReason({
+				name: name.raw,
+				status: "ambiguous",
+				plugins: resolved.plugins,
+				warnings: []
+			})}\n`);
+			return exitCodes.error;
+		} catch (error) {
+			return fail(error, "Reference placement lookup failed.");
+		}
+	}
+});
 const referenceCommand = command({
 	name: "reference",
 	description: "Read on-demand reference documents by name, layered across the managed, project, user, and plugin tiers. Read-only.",
 	commands: [
 		referenceShowCommand,
 		referenceListCommand,
-		referenceSearchCommand
+		referenceSearchCommand,
+		referenceWhereCommand
 	]
 });
 //#endregion
@@ -4638,12 +4728,26 @@ const mcpCommand = command({
 //#endregion
 //#region src/cli.ts
 const version = typeof __PACKAGE_VERSION__ !== "undefined" ? __PACKAGE_VERSION__ : JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+/** Exported for `scripts/generate-llms-txt.ts`, which lists the CLI from it; `app()` must stay built from it. */
+const rootCommand = {
+	name: "buddy-agent-harness",
+	description: "Initialize agent harness skill compatibility in consumer repositories.",
+	commands: [
+		initCommand,
+		doctorCommand,
+		mcpCommand,
+		depPluginsCommand,
+		referenceCommand,
+		governanceCommand
+	]
+};
 function app() {
-	return cli({
-		name: "buddy-agent-harness",
+	const [first, ...rest] = rootCommand.commands;
+	return rest.reduce((builder, command) => builder.command(command), cli({
+		name: rootCommand.name,
 		version,
-		description: "Initialize agent harness skill compatibility in consumer repositories."
-	}).command(initCommand).command(doctorCommand).command(mcpCommand).command(depPluginsCommand).command(referenceCommand).command(governanceCommand);
+		description: rootCommand.description
+	}).command(first));
 }
 /**
 * The application boundary: argv in, exit code out — returned rather than written, so a caller that