universal-plugin 0.8.0 → 0.9.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "universal-plugin",
-	"version": "0.8.0",
+	"version": "0.9.0",
 	"description": "Research and design toolkit for building universal AI coding agent plugins that work across Claude Code, Cursor, Codex, and GitHub Copilot CLI.",
 	"author": {
 		"name": "unional"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "universal-plugin",
-	"version": "0.8.0",
+	"version": "0.9.0",
 	"description": "Research and design toolkit for building universal AI coding agent plugins that work across Claude Code, Cursor, Codex, and GitHub Copilot CLI.",
 	"author": {
 		"name": "unional"

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "universal-plugin",
-	"version": "0.8.0",
+	"version": "0.9.0",
 	"description": "Research and design toolkit for building universal AI coding agent plugins that work across Claude Code, Cursor, Codex, and GitHub Copilot CLI.",
 	"author": {
 		"name": "unional"

package/dist/cli.mjs

@@ -5247,6 +5247,274 @@ function discardedRangeWarning(index, entry, range) {
 	return `dependencies[${index}] "${entry}" carries a version range the runtime discards — declare ${marketplace ? `{ "name": "${name}", "marketplace": "${marketplace}", "version": "${range}" }` : `{ "name": "${name}", "version": "${range}" }`} for a range that is enforced`;
 }
 //#endregion
+//#region src/governance/copy.ts
+/** The governance copy step: a governance is copied into every skill that uses it at build time and
+*  read from disk at run time, so a skill never pays a registry lookup to read a rule set it was
+*  tested against (repobuddy/buddy-agent-harness#122).
+*
+*  The files already present in `<skill>/references/governances/` ARE the declaration of which
+*  governances that skill uses — nothing is declared in plugin.json. The build refreshes every file
+*  in that folder from its owning package, adds the governances those files reference, and fails
+*  when a file names no governance or when SKILL.md does not list a copy. */
+/** Where a skill's copies live, relative to the skill folder. Posix spelling: it is both a path
+*  segment and the text a SKILL.md References section has to carry. */
+const SKILL_GOVERNANCE_DIR = "references/governances";
+/** A retrieval pointer inside a governance body: `<runner> <package> governance show <name>`, or the
+*  bare `governance show <name>` in prose. Only the trailing two words carry meaning here — which
+*  package shipped the command is exactly what the copy step removes. */
+const POINTER = /governance show\s+([A-Za-z0-9][A-Za-z0-9._/-]*)/g;
+/** A fenced code block opener or closer, with any indentation and info string. */
+const FENCE = /^\s*(?:```|~~~)/;
+/** Indentation, plus a list marker when the pointer is a bullet. A pointer listed under References
+*  is usually one bullet among several, and an instruction that loses the bullet leaves the list. */
+const LINE_PREFIX = /^\s*(?:[-*+]\s+|\d+\.\s+)?/;
+/** The copy's name for a pointer token: a namespaced `<plugin>/<name>` lookup and a plain `<name>`
+*  resolve to the same document, so both land in the same file. */
+function governanceName(token) {
+	const slash = token.lastIndexOf("/");
+	const name = slash === -1 ? token : token.slice(slash + 1);
+	return name.endsWith(".md") ? name.slice(0, -3) : name;
+}
+/** The governances a governance body points at, in first-appearance order, deduplicated. */
+function referencedGovernances(content) {
+	const names = [];
+	for (const match of content.matchAll(POINTER)) {
+		const token = match[1];
+		if (!token) continue;
+		const name = governanceName(token);
+		if (!names.includes(name)) names.push(name);
+	}
+	return names;
+}
+/** The instruction a pointer becomes. Stated once so the rewriter and its tests cannot drift. */
+function loadInstruction(name) {
+	return `Load \`${SKILL_GOVERNANCE_DIR}/${name}.md\` if it is not already loaded.`;
+}
+/** Rewrites every retrieval pointer in a copy into an instruction to load the sibling copy. The
+*  Agent Skills specification asks that every file an agent needs is one level deep from SKILL.md,
+*  so a copy must never send the agent back to a command to reach the next document.
+*
+*  A fenced block whose every line was a pointer is unwrapped: prose in a bash fence reads as a
+*  command to run. A block that mixes pointers with real commands keeps its fence. */
+function rewriteGovernancePointers(content) {
+	const eol = content.includes("\r\n") ? "\r\n" : "\n";
+	const entries = content.split(/\r?\n/).map((line) => {
+		if (FENCE.test(line)) return {
+			lines: [line],
+			rewritten: false,
+			fence: true
+		};
+		const names = referencedGovernances(line);
+		if (names.length === 0) return {
+			lines: [line],
+			rewritten: false,
+			fence: false
+		};
+		const prefix = LINE_PREFIX.exec(line)?.[0] ?? "";
+		return {
+			lines: names.map((name) => `${prefix}${loadInstruction(name)}`),
+			rewritten: true,
+			fence: false
+		};
+	});
+	const out = [];
+	for (let i = 0; i < entries.length; i++) {
+		const entry = entries[i];
+		if (!entry.fence) {
+			out.push(...entry.lines);
+			continue;
+		}
+		const close = entries.findIndex((e, j) => j > i && e.fence);
+		const inner = close === -1 ? [] : entries.slice(i + 1, close);
+		if (!(close !== -1 && inner.some((e) => e.rewritten) && inner.every((e) => e.rewritten || e.lines.every((l) => l.trim() === "")))) {
+			out.push(...entry.lines);
+			continue;
+		}
+		for (const e of inner) out.push(...e.lines);
+		i = close;
+	}
+	return out.join(eol);
+}
+/** The copies a SKILL.md fails to list under References. The specification asks SKILL.md to
+*  reference every file directly, so a copy no References section names is a file the agent has no
+*  documented way to reach. */
+function unlistedGovernanceCopies(skillMd, names) {
+	const section = referencesSection(skillMd);
+	return names.filter((name) => !section.includes(`${SKILL_GOVERNANCE_DIR}/${name}.md`));
+}
+/** The body of the References section, or the empty string when the document has none. */
+function referencesSection(skillMd) {
+	const lines = skillMd.split(/\r?\n/);
+	const start = lines.findIndex((line) => /^(#{1,6})\s+references\b/i.test(line));
+	if (start === -1) return "";
+	const level = (/^(#{1,6})/.exec(lines[start])?.[1] ?? "#").length;
+	let end = lines.length;
+	for (let i = start + 1; i < lines.length; i++) {
+		const heading = /^(#{1,6})\s/.exec(lines[i]);
+		if (heading && heading[1].length <= level) {
+			end = i;
+			break;
+		}
+	}
+	return lines.slice(start + 1, end).join("\n");
+}
+//#endregion
+//#region src/governance/copy-sync.ts
+/** Where a package keeps the governances it owns. A governance ships in its owner's package as a
+*  plain Markdown file — the copy step needs nothing else from the owner. */
+const OWNER_DIR = "governances";
+/** Refreshes every skill's governance copies from their owning packages.
+*
+*  The files already in `<skill>/references/governances/` declare which governances the skill uses.
+*  Each is rewritten from its owner's current copy, every governance a copy references is copied
+*  too, and the retrieval pointers inside each copy are rewritten to name the sibling file. */
+function syncGovernanceCopies(root, skills, govFs, opts = {}) {
+	const entries = [];
+	const errors = [];
+	const owners = ownerDirs(root, govFs);
+	for (const skill of skills) {
+		const skillDir = path.dirname(skill.path);
+		const copyDir = path.join(skillDir, ...SKILL_GOVERNANCE_DIR.split("/"));
+		if (!govFs.isDirectory(copyDir)) continue;
+		const copied = [];
+		const declared = govFs.list(copyDir);
+		const queue = declared.map((name) => ({ name }));
+		const seen = new Set(declared);
+		while (queue.length > 0) {
+			const wanted = queue.shift();
+			const { name } = wanted;
+			const source = resolveSource(name, owners, govFs);
+			if (!source) {
+				errors.push(unresolvedMessage(skill.name, wanted, owners));
+				continue;
+			}
+			copied.push(name);
+			for (const referenced of referencedGovernances(source.content)) {
+				if (seen.has(referenced)) continue;
+				seen.add(referenced);
+				queue.push({
+					name: referenced,
+					via: name
+				});
+			}
+			const content = rewriteGovernancePointers(source.content);
+			const target = path.join(copyDir, `${name}.md`);
+			if ((govFs.exists(target) ? govFs.read(target) : null) === content) {
+				entries.push({
+					skill: skill.name,
+					name,
+					path: target,
+					owner: source.owner,
+					status: "unchanged"
+				});
+				continue;
+			}
+			if (opts.check || opts.dryRun) {
+				entries.push({
+					skill: skill.name,
+					name,
+					path: target,
+					owner: source.owner,
+					status: "stale"
+				});
+				continue;
+			}
+			govFs.write(target, content);
+			entries.push({
+				skill: skill.name,
+				name,
+				path: target,
+				owner: source.owner,
+				status: "written"
+			});
+		}
+		const unlisted = unlistedGovernanceCopies(govFs.read(skill.path), copied);
+		for (const name of unlisted) errors.push(`skill "${skill.name}": SKILL.md does not list \`${SKILL_GOVERNANCE_DIR}/${name}.md\` under References.`);
+	}
+	return {
+		entries,
+		errors
+	};
+}
+function unresolvedMessage(skill, wanted, owners) {
+	const checked = `No installed package owns it — checked ${owners.map((o) => o.name).join(", ")}.`;
+	return wanted.via ? `skill "${skill}": governance "${wanted.via}" references "${wanted.name}", which has no copy to point at. ${checked}` : `skill "${skill}": ${SKILL_GOVERNANCE_DIR}/${wanted.name}.md names no governance. ${checked}`;
+}
+function resolveSource(name, owners, govFs) {
+	for (const owner of owners) {
+		const filePath = path.join(owner.dir, `${name}.md`);
+		if (govFs.exists(filePath)) return {
+			owner: owner.name,
+			content: govFs.read(filePath)
+		};
+	}
+	return null;
+}
+/** The packages a governance may come from, in resolution order: the plugin being built, then its
+*  declared dependencies. The plugin wins — a plugin that ships a governance owns that name, and a
+*  build must not copy a stale published copy of a document its own tree holds. */
+function ownerDirs(root, govFs) {
+	const owners = [{
+		name: ".",
+		dir: path.join(root, OWNER_DIR)
+	}];
+	for (const pkg of declaredDependencies(root, govFs)) {
+		const dir = packageDir(root, pkg, govFs);
+		if (dir) owners.push({
+			name: pkg,
+			dir: path.join(dir, OWNER_DIR)
+		});
+	}
+	return owners;
+}
+/** Every package the plugin's own `package.json` declares. A governance owner is installed as a dev
+*  dependency of the repository being built; runtime dependencies are read too, because which of
+*  the two a plugin author picked is not this step's business. */
+function declaredDependencies(root, govFs) {
+	const manifestPath = path.join(root, "package.json");
+	if (!govFs.exists(manifestPath)) return [];
+	let parsed;
+	try {
+		parsed = JSON.parse(govFs.read(manifestPath));
+	} catch {
+		return [];
+	}
+	const names = /* @__PURE__ */ new Set();
+	for (const field of [parsed.devDependencies, parsed.dependencies]) if (field && typeof field === "object") for (const name of Object.keys(field)) names.add(name);
+	return [...names];
+}
+/** Walks up from the plugin root looking for the installed package, the way Node resolves one. A
+*  workspace hoists its dependencies to the repository root, so the first `node_modules` above the
+*  plugin is usually not the one holding them. */
+function packageDir(root, pkg, govFs) {
+	let dir = path.resolve(root);
+	for (;;) {
+		const candidate = path.join(dir, "node_modules", pkg);
+		if (govFs.exists(path.join(candidate, "package.json"))) return candidate;
+		const parent = path.dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+//#endregion
+//#region src/governance/fs.ts
+const realGovernanceFs = {
+	exists: (p) => fs.existsSync(p),
+	read: (p) => fs.readFileSync(p, "utf8"),
+	list: (dir) => {
+		if (!fs.existsSync(dir)) return [];
+		return fs.readdirSync(dir).filter((f) => f.endsWith(".md")).map((f) => f.slice(0, -3));
+	}
+};
+const realGovernanceCopyFs = {
+	...realGovernanceFs,
+	isDirectory: (dir) => fs.existsSync(dir) && fs.statSync(dir).isDirectory(),
+	write: (filePath, content) => {
+		fs.mkdirSync(path.dirname(filePath), { recursive: true });
+		fs.writeFileSync(filePath, content);
+	}
+};
+//#endregion
 //#region src/hooks/hooks.ts
 /** Per-vendor hook support. Source: `.research/hook-event-survey/conclusion.md`, re-verified against
 *  vendor documentation August 2026. A vendor fact decays — re-verify before trusting this table. */
@@ -6215,6 +6483,10 @@ function validateManifest(manifest, targets) {
 	return errors;
 }
 function buildPlugin(root, opts = {}) {
+	if (opts.check) opts = {
+		...opts,
+		dryRun: true
+	};
 	const manifestPath = path.join(root, "plugin.json");
 	if (!fs.existsSync(manifestPath)) throw new Error(`No plugin.json found at ${root}`);
 	const indent = detectIndent(fs.readFileSync(manifestPath, "utf8"));
@@ -6241,7 +6513,7 @@ function buildPlugin(root, opts = {}) {
 	}
 	if (vendors.length === 0) {
 		const signals = legacyLayoutSignals(manifest, fs.existsSync(path.join(root, SHADOWING_MANIFEST)));
-		if (signals.length > 0) throw new Error(`Nothing was derived, and this project is still on the pre-0.6 manifest layout:\n${signals.map((s) => `  - ${s}`).join("\n")}\nRun /universal-plugin:doctor for the full diagnosis and the skill that owns each repair.`);
+		if (signals.length > 0) throw new Error(`Nothing was derived, and this project is still on the pre-0.6 manifest layout:\n${signals.map((s) => `  - ${s}`).join("\n")}\nRun /universal-plugin:doctor-universal-plugin for the full diagnosis and the skill that owns each repair.`);
 		warnings.push("No vendors declared in harnesses — nothing to build");
 		return {
 			vendors: [],
@@ -6249,6 +6521,7 @@ function buildPlugin(root, opts = {}) {
 			warnings,
 			rows,
 			catalogs: [],
+			governances: [],
 			summary: summarize(rows)
 		};
 	}
@@ -6259,6 +6532,12 @@ function buildPlugin(root, opts = {}) {
 	const { vendors: _vendors, packagePath: _packagePath, harnesses: _harnesses, dependencies: declaredDependencies, ...componentConfig } = uext;
 	warnings.push(...validateDependencies(declaredDependencies).warnings);
 	const skills = readSkills(root, manifest, warnings);
+	const governances = syncGovernanceCopies(root, skills, realGovernanceCopyFs, {
+		check: opts.check,
+		dryRun: opts.dryRun
+	});
+	if (governances.errors.length > 0) throw new Error(`Governance copies are not buildable:\n${governances.errors.map((e) => `  - ${e}`).join("\n")}`);
+	written.push(...governances.entries.filter((e) => e.status === "written").map((e) => e.path));
 	const canonicalHooks = readCanonicalHooks(root, componentConfig["hooks"], warnings);
 	const declaredMcp = readCanonicalMcpServers(root, componentConfig["mcpServers"], warnings);
 	const mcp = declaredMcp ? pinMcpServers(declaredMcp.servers, manifest.version) : null;
@@ -6341,6 +6620,7 @@ function buildPlugin(root, opts = {}) {
 		rows,
 		catalogs,
 		catalogRoot,
+		governances: governances.entries,
 		summary: summarize(rows)
 	};
 }
@@ -6681,8 +6961,8 @@ function formatMcpNote(note) {
 }
 //#endregion
 //#region src/build/cli.ts
-const NEXT_STEP_NOTHING_BUILT = "→ /universal-plugin:doctor — diagnose why nothing is declared\n";
-const NEXT_STEP_BUILT = "→ /universal-plugin:doctor — check the built manifests against plugin.json\n";
+const NEXT_STEP_NOTHING_BUILT = "→ /universal-plugin:doctor-universal-plugin — diagnose why nothing is declared\n";
+const NEXT_STEP_BUILT = "→ /universal-plugin:doctor-universal-plugin — check the built manifests against plugin.json\n";
 /** Every hint names a command that exists today: an agent that follows a hint into
 *  `unknown command` is at a dead end (issue #80). A refreshed catalog is checked by
 *  `marketplace validate`, pointed at the repository the catalog lives in. */
@@ -6693,19 +6973,27 @@ function nextStep$1(result, cwd) {
 	const quoted = /\s/.test(relative) ? JSON.stringify(relative) : relative;
 	return `→ universal-plugin marketplace validate${relative === "" ? "" : ` --root ${quoted}`}\n`;
 }
+/** What repairs a stale copy: the same build, without `--check`. */
+function checkNextStep(root) {
+	return `\u2192 universal-plugin plugin build${root ? ` --root ${root}` : ""} \u2014 refresh the stale governance copies\n`;
+}
 function buildCommand() {
 	const cmd = new Command("build").description("Generate vendor manifests from plugin.json");
-	cmd.option("--vendor <id>", "Build only the named vendor").option("--dry-run", "Print what would be written without writing").option("--verbose", "Print field-by-field transformation decisions").option("--clean", "Delete generated manifests before building").option("--format <format>", "Output format: json or toon (default: toon)").addOption(new Option("--json").hideHelp()).addOption(ROOT_OPTION).addHelpText("after", "\nExample:\n  $ universal-plugin plugin build --vendor claude-code\n").action((opts) => {
+	cmd.option("--vendor <id>", "Build only the named vendor").option("--dry-run", "Print what would be written without writing").option("--verbose", "Print field-by-field transformation decisions").option("--clean", "Delete generated manifests before building").option("--check", "Write nothing; fail when a committed governance copy differs from its source").option("--format <format>", "Output format: json or toon (default: toon)").addOption(new Option("--json").hideHelp()).addOption(ROOT_OPTION).addHelpText("after", "\nExample:\n  $ universal-plugin plugin build --vendor claude-code\n").action((opts) => {
 		try {
 			const result = buildPlugin(resolveRoot(opts.root), {
 				vendor: opts.vendor,
 				dryRun: opts.dryRun,
 				verbose: opts.verbose,
-				clean: opts.clean
+				clean: opts.clean,
+				check: opts.check
 			});
 			for (const warning of result.warnings) process.stderr.write(`warn: ${warning}\n`);
+			const stale = result.governances.filter((g) => g.status === "stale");
+			if (opts.check) for (const copy of stale) process.stderr.write(`stale: ${path.relative(process.cwd(), copy.path)} (owner ${copy.owner})\n`);
 			const { built, skipped, failed, canonical } = result.summary;
 			const jsonResult = {
+				governances: result.governances,
 				built: result.rows.filter((r) => r.status === "built"),
 				skipped: result.rows.filter((r) => r.status === "skipped"),
 				failed: result.rows.filter((r) => r.status === "failed"),
@@ -6716,6 +7004,7 @@ function buildCommand() {
 			};
 			const counts = `built ${built}, skipped ${skipped}, failed ${failed}`;
 			const catalogSummary = result.catalogs.length > 0 ? `, catalogs ${result.catalogs.length}` : "";
+			const governanceSummary = result.governances.length > 0 ? `, governance copies ${result.governances.length}` : "";
 			output(jsonResult, {
 				vendors: result.rows.map((r) => ({
 					vendor: r.vendor,
@@ -6726,10 +7015,16 @@ function buildCommand() {
 					path: r.path,
 					status: r.status
 				})),
-				summary: (canonical > 0 ? `${counts}, served by plugin.json ${canonical}` : counts) + catalogSummary
+				...result.governances.length > 0 ? { governances: result.governances.map((g) => ({
+					skill: g.skill,
+					name: g.name,
+					status: g.status
+				})) } : {},
+				summary: (canonical > 0 ? `${counts}, served by plugin.json ${canonical}` : counts) + catalogSummary + governanceSummary
 			});
-			process.stderr.write(nextStep$1(result, process.cwd()));
+			process.stderr.write(opts.check && stale.length > 0 ? checkNextStep(opts.root) : nextStep$1(result, process.cwd()));
 			if (failed > 0) process.exitCode = 1;
+			if (opts.check && stale.length > 0) process.exitCode = 1;
 		} catch (err) {
 			process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
 			process.exit(1);
@@ -7156,16 +7451,6 @@ function configCommand(fs = realConfigFs) {
 	return new Command("config").description("Read and write plugin-registered config in .agents/universal-plugin.json").addCommand(addCommand(fs)).addCommand(getCommand(fs));
 }
 //#endregion
-//#region src/governance/fs.ts
-const realGovernanceFs = {
-	exists: (p) => fs.existsSync(p),
-	read: (p) => fs.readFileSync(p, "utf8"),
-	list: (dir) => {
-		if (!fs.existsSync(dir)) return [];
-		return fs.readdirSync(dir).filter((f) => f.endsWith(".md")).map((f) => f.slice(0, -3));
-	}
-};
-//#endregion
 //#region src/governance/governance.ts
 function getManagedDir() {
 	if (process.platform === "darwin") return "/Library/Application Support/UniPlugin/governances";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-plugin",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Universal AI agent plugin build tool",
   "keywords": [
     "agent-plugin",
@@ -63,12 +63,13 @@
   },
   "scripts": {
     "build": "tsdown",
+    "check:governances": "tsx src/cli.ts plugin build --check --root .",
     "dev": "tsx src/cli.ts",
     "knip": "knip",
     "lint": "biome check .",
     "test": "pnpm build && vitest run src",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
-    "verify": "pnpm typecheck && pnpm lint && pnpm test"
+    "verify": "pnpm typecheck && pnpm lint && pnpm test && pnpm check:governances"
   }
 }

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "universal-plugin",
-	"version": "0.8.0",
+	"version": "0.9.0",
 	"description": "Research and design toolkit for building universal AI coding agent plugins that work across Claude Code, Cursor, Codex, and GitHub Copilot CLI.",
 	"author": {
 		"name": "unional"

package/skills/{doctor → doctor-universal-plugin}/README.md

@@ -1,4 +1,4 @@
-# doctor skill
+# doctor-universal-plugin skill
 
 Diagnose a universal agent plugin: what the canonical `plugin.json` declares, and whether what is on
 disk still matches it for Claude Code, Cursor, Codex, and GitHub Copilot CLI.

package/skills/{doctor → doctor-universal-plugin}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: doctor
+name: doctor-universal-plugin
 description: Use this skill to diagnose a universal agent plugin — when `plugin build` reports "built 0" or "nothing to build", when it warns "No vendors declared in harnesses", when a repository still carries `.plugin/plugin.json` or a top-level `vendorExtensions` block after upgrading universal-plugin across a major, when a released version never reached the vendor manifests, when a runtime loads none of the plugin's skills, when a vendor manifest is missing or looks out of date after a pull, or when checking whether what the canonical plugin.json declares still matches what is on disk for Claude Code, Cursor, Codex, and GitHub Copilot CLI. Trigger on "is my plugin set up right", "why isn't my plugin loading", "the build says built 0", "why did nothing get built", "check the plugin", "are the vendor manifests current", or "what does this plugin declare".
 ---