buddy-agent-harness 0.17.0 → 0.19.0

package/dist/index.mjs

@@ -574,6 +574,12 @@ function skillsProjection(harness, scope, directories = skillsDirectories(harnes
 	return listed.includes(".agents/skills") ? {} : { skillsDirectory: first };
 }
 /**
+* The user-scope counterpart of the root `AGENTS.md`, relative to the home directory. No harness
+* reads it natively; each loads it only through a user-scope `instructionBridge` (E-CC-18, E-CODEX-05,
+* E-GEM-03, E-COPILOT-04, E-CUR-08).
+*/
+const globalInstructions = ".agents/AGENTS.md";
+/**
 * Skills directories come from `@cyberuni/agent-harness`, except for the harnesses it does not know
 * (`devin-desktop`, `windsurf`); see `.research/agentic-configuration-standards/` for the rest.
 */
@@ -614,7 +620,14 @@ const harnessRegistry = [
 		},
 		user: {
 			detect: ".claude",
-			...skillsProjection("claude-code", "user")
+			...skillsProjection("claude-code", "user"),
+			relocatedBy: "CLAUDE_CONFIG_DIR",
+			emptyRelocatesToStart: true,
+			instructionBridge: {
+				kind: "import",
+				path: ".claude/CLAUDE.md",
+				line: `@~/${globalInstructions}`
+			}
 		}
 	},
 	{
@@ -676,7 +689,13 @@ const harnessRegistry = [
 		},
 		user: {
 			detect: ".codex",
-			...skillsProjection("codex", "user")
+			...skillsProjection("codex", "user"),
+			instructionBridge: {
+				kind: "symlink",
+				path: ".codex/AGENTS.md"
+			},
+			shadowedBy: [".codex/AGENTS.override.md"],
+			relocatedBy: "CODEX_HOME"
 		}
 	},
 	{
@@ -704,7 +723,12 @@ const harnessRegistry = [
 		},
 		user: {
 			detect: ".copilot",
-			...skillsProjection("copilot-cli", "user")
+			...skillsProjection("copilot-cli", "user"),
+			relocatedBy: "COPILOT_HOME",
+			instructionBridge: {
+				kind: "symlink",
+				path: ".copilot/copilot-instructions.md"
+			}
 		}
 	},
 	{
@@ -736,7 +760,11 @@ const harnessRegistry = [
 		},
 		user: {
 			detect: ".gemini",
-			...skillsProjection("gemini-cli", "user")
+			...skillsProjection("gemini-cli", "user"),
+			instructionBridge: {
+				kind: "symlink",
+				path: ".gemini/GEMINI.md"
+			}
 		}
 	},
 	{
@@ -952,6 +980,69 @@ const instructionTable = {
 	}
 };
 const instructionRepairs = repairsOf(instructionTable);
+const globalFile = `~/${globalInstructions}`;
+/**
+* The step that bridges one harness's user-scope file, in the words it is handed over in; `file` is
+* where it was found, which a variable such as `$CODEX_HOME` may have moved.
+*/
+function globalBridgeStep(bridge, file = `~/${bridge.path}`) {
+	return bridge.kind === "import" ? `add the line \`${bridge.line}\` to ${file}` : `run \`ln -s ${globalFile} ${file}\``;
+}
+/** Every spelling of a user-scope path a report can carry: from `~`, and from the variable that moves it. */
+function userSpellings(scope, path) {
+	const under = `${scope.detect}/`;
+	return scope.relocatedBy !== void 0 && path.startsWith(under) ? [`~/${path}`, `$${scope.relocatedBy}/${path.slice(under.length)}`] : [`~/${path}`];
+}
+/** The bridge for a reported path; undefined for a path no harness registers, such as a table's `<path>`. */
+function userBridgeAt(file) {
+	for (const { user } of harnessRegistry) {
+		const bridge = user?.instructionBridge;
+		if (user && bridge && userSpellings(user, bridge.path).includes(file)) return bridge;
+	}
+}
+/** The step for one reported file, or a pointer to where it is written when the path is not one. */
+function stepAt(file, keepContent) {
+	const bridge = userBridgeAt(file);
+	if (bridge === void 0) return `add the bridge the harness page names for ${file}`;
+	return `${keepContent && bridge.kind !== "import" ? `move what ${file} says into ${globalFile} and remove it, then ` : ""}${globalBridgeStep(bridge, file)}`;
+}
+/** Outside the repository, so never written: a repair is a step handed to the user. */
+const handOver = "hand the user this step, since nothing here writes outside the repository:";
+const globalInstructionTable = {
+	"global-instructions-missing": {
+		detail: `no user-scope instruction file at this path — the harness loads none of ${globalFile}`,
+		repair: ({ file }) => ({
+			command: "",
+			instruction: `${handOver} ${stepAt(file, false)}`
+		}),
+		skillRepair: () => "hand the user the step the harness page names for that file; write nothing yourself"
+	},
+	"global-instructions-unbridged": {
+		detail: `the file holds its own content and does not load ${globalFile} — text placed there reaches no session of this harness`,
+		repair: ({ file }) => ({
+			command: "",
+			instruction: `${handOver} ${stepAt(file, true)}`
+		}),
+		skillRepair: () => "hand the user the step the harness page names for that file, keeping what the file says; write nothing yourself"
+	},
+	"global-instructions-overridden": {
+		detail: `the harness reads this file in place of its own user-scope file, so whatever that file loads goes unread, and this one does not load ${globalFile}`,
+		repair: ({ file }) => ({
+			command: "",
+			instruction: `${handOver} move what ${file} says into ${globalFile} and remove it`
+		}),
+		skillRepair: () => "hand the user the move of what that file says into the global file, and its removal; write nothing yourself"
+	},
+	"global-instructions-emptied": {
+		detail: "the variable is set but empty, which this harness reads as the directory it starts in rather than as unset — its user-scope file is whichever one sits there, not the one in its own folder",
+		repair: ({ file }) => ({
+			command: "",
+			instruction: `${handOver} unset ${file.slice(1)} where your shell sets it, or set it to the folder you meant`
+		}),
+		skillRepair: () => "hand the user the step of unsetting that variable; write nothing yourself"
+	}
+};
+const globalInstructionRepairs = repairsOf(globalInstructionTable);
 const configurationTable = {
 	"deprecated-harness": {
 		detail: "a projection under a harness name that has been superseded — the replacement reads .agents/skills natively and needs no projection at all",
@@ -1128,6 +1219,7 @@ repairsOf(nonstandardTable);
 const doctorTable = {
 	...bridgeTable,
 	...instructionTable,
+	...globalInstructionTable,
 	...configurationTable,
 	...mcpTable,
 	...nonstandardTable
@@ -1180,6 +1272,8 @@ The command is read-only. It never repairs anything, so it is safe to run at any
 
 \`instructions\` is everything standing between a harness and \`AGENTS.md\`, with a \`status\` of \`ok\`, \`missing\`, \`unbridged\`, \`unreadable\`, \`shadowing\`, or \`superseded\`. The last two are not bridges: they are files that suppress an \`AGENTS.md\` the harness would otherwise read by itself. A separate section because nothing about any of them is shared with \`bridges\`: a different \`kind\`, a different status vocabulary, and a repair that is never a command.
 
+\`globalInstructions\` is the same question one level up: whether each harness installed for this user loads \`${globalFile}\` through its own user-scope file, with a \`status\` of \`ok\`, \`missing\`, \`unbridged\`, or \`overridden\`. No harness reads that file by itself, so text placed there reaches only the harnesses whose row is \`ok\`. The rows are there whether or not the file exists; a finding is raised only when it exists and goes unread.
+
 \`findings\` explains each problem and carries more than the two sections above: the configuration, MCP, and non-standard findings have no section of their own, because they are about files rather than about bridges. \`help\` carries each repair, one row per distinct repair, with two columns:
 
 - \`command\` — a shell invocation that, run exactly as given, **completes** the repair.
@@ -1203,6 +1297,7 @@ Every \`problem\` name routes to exactly one page. Load the page for the finding
 | --- | --- |
 | \`references/bridges.md\` | any \`bridges\` row that is not \`ok\` |
 | \`references/instructions.md\` | any \`instructions\` row that is not \`ok\` |
+| \`references/global-instructions.md\` | any \`globalInstructions\` row that is not \`ok\` |
 | \`references/configuration.md\` | a finding about the configuration around the bridges rather than a bridge |
 | \`references/mcp.md\` | any finding whose path is an MCP locator — **always** before acting on a credential finding |
 | \`references/nonstandard.md\` | a finding about configuration only one harness can read |
@@ -1214,6 +1309,7 @@ Every \`problem\` name routes to exactly one page. Load the page for the finding
 - Edit skills at \`.agents/skills/<name>/SKILL.md\`. Editing through a bridge is only safe when that bridge is a symlink.
 - Do not add bridges to \`.gitignore\`. An untracked bridge swallows a real edit silently.
 - Never repeat a value from a file an \`mcp-literal-secret\` or \`mcp-committed-secret\` finding points at. The report withheld it on purpose, and quoting it back puts it in the transcript anyway.
+- Never write outside the repository. A \`globalInstructions\` repair is a step for the user to take in their own home directory; hand it over exactly as reported.
 - Write instructions in \`AGENTS.md\`, never in \`CLAUDE.md\`. Content written there reaches one harness, drifts from the canonical file, and — because Claude Code prefers it — takes \`AGENTS.md\` out of that harness's context entirely.
 `;
 }
@@ -2795,7 +2891,7 @@ function projectChain(root) {
 		dir = parent;
 	}
 }
-function isDirectory$1(path) {
+function isDirectory$2(path) {
 	try {
 		return statSync(path).isDirectory();
 	} catch {
@@ -2831,7 +2927,7 @@ function dependencyLayers(root, skip) {
 		const dir = packageDir(pkg, manifestPath);
 		if (!dir || skip.has(canonical(dir))) continue;
 		const references = join(dir, "references");
-		if (!isDirectory$1(references)) continue;
+		if (!isDirectory$2(references)) continue;
 		const manifest = readJson(join(dir, "plugin.json"));
 		const manifestName = isRecord(manifest) && typeof manifest["name"] === "string" ? manifest["name"] : void 0;
 		const plugins = manifestName && manifestName !== pkg ? [pkg, manifestName] : [pkg];
@@ -2881,7 +2977,7 @@ async function referenceLayers({ root, home, platform, programData, packageRoot
 			plugins: self,
 			status: LEGACY_STATUS
 		},
-		...enabled.filter(({ dir, skipped }) => skipped || isDirectory$1(dir) && canonical(dirname(dir)) !== ownRoot),
+		...enabled.filter(({ dir, skipped }) => skipped || isDirectory$2(dir) && canonical(dirname(dir)) !== ownRoot),
 		...dependencyLayers(root, /* @__PURE__ */ new Set([ownRoot]))
 	];
 	const seen = /* @__PURE__ */ new Set();
@@ -2978,6 +3074,165 @@ function projectSkills({ root, canonicalSkills, harnesses, copy, force }) {
 	};
 }
 //#endregion
+//#region src/diagnose-bridges/diagnose-global-instructions.ts
+function isDirectory$1(path) {
+	try {
+		return lstatSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}
+function exists$1(path) {
+	try {
+		lstatSync(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** The import a user wrote may spell the home directory either way; both load the same file. */
+function importsGlobal(body, bridge, home) {
+	const spellings = bridge.kind === "import" ? [bridge.line, `@${join(home, globalInstructions)}`] : [];
+	return body.split("\n").some((line) => spellings.includes(line.trim()));
+}
+/**
+* Follows `relocatedBy` the way each harness does. An empty value is no value to Codex and Copilot CLI
+* (E-CODEX-06, E-COPILOT-06), and the directory Claude Code starts in to Claude Code (E-CC-20).
+*/
+function base(scope, env, start) {
+	const variable = scope.relocatedBy;
+	const value = variable === void 0 ? void 0 : env[variable];
+	if (variable === void 0 || value === void 0) return {};
+	if (value !== "") return { moved: {
+		root: resolve(value),
+		display: `$${variable}`
+	} };
+	return scope.emptyRelocatesToStart ? {
+		moved: {
+			root: start,
+			display: "."
+		},
+		emptied: variable
+	} : {};
+}
+function locate(home, scope, { moved }, path) {
+	if (!moved || path !== scope.detect && !path.startsWith(`${scope.detect}/`)) return {
+		absolute: join(home, path),
+		display: `~/${path}`
+	};
+	const rest = path.slice(scope.detect.length);
+	return {
+		absolute: join(moved.root, rest),
+		display: `${moved.display}${rest}`
+	};
+}
+/** A shadow is read only where it is a file holding more than whitespace (E-CODEX-06). */
+function readsAsShadow(path) {
+	try {
+		return statSync(path).isFile() && readFileSync(path, "utf8").trim() !== "";
+	} catch {
+		return false;
+	}
+}
+function inspect$1(home, target, bridge) {
+	let stats;
+	try {
+		stats = lstatSync(target);
+	} catch {
+		return {
+			kind: "none",
+			status: "missing",
+			problem: "global-instructions-missing"
+		};
+	}
+	if (stats.isSymbolicLink()) return resolve(dirname(target), readlinkSync(target)) === join(home, ".agents/AGENTS.md") ? {
+		kind: "symlink",
+		status: "ok"
+	} : {
+		kind: "symlink",
+		status: "unbridged",
+		problem: "global-instructions-unbridged"
+	};
+	let body;
+	try {
+		body = readFileSync(target, "utf8");
+	} catch {
+		return {
+			kind: "file",
+			status: "unbridged",
+			problem: "global-instructions-unbridged"
+		};
+	}
+	return importsGlobal(body, bridge, home) ? {
+		kind: "import",
+		status: "ok"
+	} : {
+		kind: "file",
+		status: "unbridged",
+		problem: "global-instructions-unbridged"
+	};
+}
+function finding(path, problem, cli) {
+	const { detail, repair } = repairFor(problem);
+	return {
+		path,
+		problem,
+		detail,
+		repair: repair({ file: path }, cli)
+	};
+}
+/**
+* Whether each harness the user has installed loads `~/.agents/AGENTS.md` through its own user-scope
+* file, read from wherever `env` moves it — `start`, for a harness that reads an empty variable as
+* the directory it starts in. Read-only: the repair is handed to the user, since nothing here
+* writes outside the repository.
+*/
+function diagnoseGlobalInstructions(home, preferred, cli, env = {}, start = process.cwd()) {
+	const hasGlobal = exists$1(join(home, globalInstructions));
+	const rows = [];
+	const findings = [];
+	for (const harness of harnessRegistry) {
+		const user = harness.user;
+		const bridge = user?.instructionBridge;
+		if (!user || !bridge) continue;
+		const moved = base(user, env, start);
+		if (!preferred.includes(harness.name) && !isDirectory$1(locate(home, user, moved, user.detect).absolute)) continue;
+		const file = locate(home, user, moved, bridge.path);
+		const inspection = inspect$1(home, file.absolute, bridge);
+		const shadow = (user.shadowedBy ?? []).map((path) => locate(home, user, moved, path)).find(({ absolute }) => readsAsShadow(absolute));
+		if (shadow !== void 0) {
+			const read = inspect$1(home, shadow.absolute, bridge);
+			if (read.status === "ok") {
+				rows.push({
+					harness: harness.name,
+					path: shadow.display,
+					kind: read.kind,
+					status: "ok"
+				});
+				continue;
+			}
+			rows.push({
+				harness: harness.name,
+				path: file.display,
+				kind: inspection.kind,
+				status: "overridden"
+			});
+			if (hasGlobal) findings.push(finding(shadow.display, "global-instructions-overridden", cli));
+		} else rows.push({
+			harness: harness.name,
+			path: file.display,
+			kind: inspection.kind,
+			status: inspection.status
+		});
+		if (hasGlobal && moved.emptied) findings.push(finding(`$${moved.emptied}`, "global-instructions-emptied", cli));
+		else if (hasGlobal && inspection.problem) findings.push(finding(file.display, inspection.problem, cli));
+	}
+	return {
+		globalInstructions: rows,
+		findings
+	};
+}
+//#endregion
 //#region src/diagnose-bridges/agents-files.ts
 /** Directories that never hold instructions this repository is responsible for bridging. */
 const pruned = /* @__PURE__ */ new Set(["node_modules"]);
@@ -3092,7 +3347,7 @@ function diagnoseInstructions(root, harnesses, cli) {
 	const bridged = harnesses.map((harness) => ({
 		name: harness.name,
 		bridge: harness.project.instructionBridge
-	})).filter((harness) => Boolean(harness.bridge));
+	})).filter((harness) => harness.bridge?.kind === "settings-entry");
 	const instructions = [];
 	const findings = [];
 	const directories = agentsFileDirectories(root);
@@ -3348,7 +3603,7 @@ function inspect(target, path, canonical, git) {
 * Read-only: nothing is created, moved, or repaired — the caller decides what to run from the
 * repair each finding carries.
 */
-function diagnoseBridges({ root, harnesses: preferred = [], cli }) {
+function diagnoseBridges({ root, harnesses: preferred = [], cli, home, env }) {
 	const canonical = join(root, ".agents", "skills");
 	const git = new GitBridgeState(root);
 	const selected = selectHarnesses(root, preferred);
@@ -3393,9 +3648,15 @@ function diagnoseBridges({ root, harnesses: preferred = [], cli }) {
 	}
 	const instructions = diagnoseInstructions(root, selected, cli);
 	findings.push(...instructions.findings);
+	const global = home === void 0 ? {
+		globalInstructions: [],
+		findings: []
+	} : diagnoseGlobalInstructions(home, preferred, cli, env, root);
+	findings.push(...global.findings);
 	return {
 		bridges,
 		instructions: instructions.instructions,
+		globalInstructions: global.globalInstructions,
 		divergence,
 		findings
 	};
@@ -3416,6 +3677,7 @@ function buildDoctorReport(bin, result, configuration = [], held = []) {
 			bin,
 			bridges: result.bridges,
 			instructions: result.instructions,
+			globalInstructions: result.globalInstructions,
 			references,
 			findings: `0 problems found — ${bridges} and the configuration around them is current`
 		};
@@ -3424,6 +3686,7 @@ function buildDoctorReport(bin, result, configuration = [], held = []) {
 		bin,
 		bridges: result.bridges,
 		instructions: result.instructions,
+		globalInstructions: result.globalInstructions,
 		references,
 		...result.divergence.length ? { divergence: result.divergence } : {},
 		findings: findings.map(({ path, problem, detail }) => ({
@@ -3436,7 +3699,7 @@ function buildDoctorReport(bin, result, configuration = [], held = []) {
 }
 const doctorCommand = command({
 	name: "doctor",
-	description: "Report whether this repository's harness bridges still resolve — skills into .agents/skills, instructions into AGENTS.md. Read-only.",
+	description: "Report whether this repository's harness bridges still resolve — skills into .agents/skills, instructions into AGENTS.md — and whether each harness's user-scope file loads ~/.agents/AGENTS.md. Read-only.",
 	options: {
 		root: {
 			description: "Repository or package directory. Defaults to the current directory.",
@@ -3461,7 +3724,9 @@ const doctorCommand = command({
 			const result = diagnoseBridges({
 				root,
 				...harnesses.length ? { harnesses } : {},
-				cli: commandInvocation
+				cli: commandInvocation,
+				home,
+				env: process.env
 			});
 			const git = new GitBridgeState(root);
 			const configuration = [
@@ -5190,6 +5455,6 @@ function listMcpServers(options) {
 	return entries;
 }
 //#endregion
-export { activate, bridgeRepairs, buildDoctorReport, deprecatedManagedGovernancesDir, diagnoseBridges, diagnoseInstructions, diagnoseMcp, doctorCommand, doctorRepairs, doctorSkill, goldenSetPath, governanceCommand, governanceLayers, harnessCommand, harnessRegistry, initCommand, initializeHarnesses, instructionRepairs, listGovernances, listMcpServers, listReferences, managedGovernancesDir, managedReferencesDir, overrideLayers, parseGovernanceName, parseReferenceName, referenceCommand, referenceLayers, renderDoctorSkill, resolveGovernance, resolveReference, run, searchReferences };
+export { activate, bridgeRepairs, buildDoctorReport, deprecatedManagedGovernancesDir, diagnoseBridges, diagnoseGlobalInstructions, diagnoseInstructions, diagnoseMcp, doctorCommand, doctorRepairs, doctorSkill, globalInstructionRepairs, goldenSetPath, governanceCommand, governanceLayers, harnessCommand, harnessRegistry, initCommand, initializeHarnesses, instructionRepairs, listGovernances, listMcpServers, listReferences, managedGovernancesDir, managedReferencesDir, overrideLayers, parseGovernanceName, parseReferenceName, referenceCommand, referenceLayers, renderDoctorSkill, resolveGovernance, resolveReference, run, searchReferences };
 
 //# sourceMappingURL=index.mjs.map