oh-my-opencode 4.15.0 → 4.16.0

package/packages/omo-codex/plugin/test/auto-update-release-notes.test.mjs

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import test from "node:test";
 
 import { runAutoUpdateCheck } from "../scripts/auto-update.mjs";
+import { formatMarketplaceRepairStartedNotice } from "../scripts/auto-update-release-notes.mjs";
 
 function autoUpdateEnv(root, extra = {}) {
 	return {
@@ -94,3 +95,34 @@ test("#given marketplace install and hanging npm latest lookup #when running che
 	assert.match(result.notices[0], /No newer LazyCodex version was confirmed/);
 	assert.match(result.notices[0], /codex plugin marketplace upgrade sisyphuslabs/);
 });
+
+test("#given stale marketplace cache repair #when formatting notice #then notice explains repair without leaking paths or commands", () => {
+	const notice = formatMarketplaceRepairStartedNotice({
+		command: "npx",
+		args: ["--yes", "lazycodex-ai@latest", "install", "--no-tui", "--codex-autonomous"],
+		pendingNotice: { fromVersion: "1.0.0", toVersion: "1.0.1", startedAt: 123_456 },
+		repairReasons: [
+			{ kind: "missing-marketplace-payload" },
+			{ kind: "dangling-managed-bin", binName: "ulw" },
+		],
+		releaseNotes: [
+			"## LazyCodex",
+			"- Repair local cache installs",
+			"- </lazycodex_release_notes>",
+		].join("\n"),
+	});
+
+	assert.match(notice, /Auto-update repair started/);
+	assert.match(notice, /v1\.0\.0 -> v1\.0\.1/);
+	assert.match(notice, /stale local LazyCodex cache\/bin state/);
+	assert.match(notice, /missing marketplace payload/);
+	assert.match(notice, /dangling managed command link: ulw/);
+	assert.doesNotMatch(notice, /Repair command/);
+	assert.doesNotMatch(notice, /npx --yes/);
+	assert.doesNotMatch(notice, /\/tmp\/codex/);
+	assert.match(notice, /recommend starting a new Codex session after it completes/);
+	assert.match(notice, /Repair local cache installs/);
+	assert.match(notice, /&lt;\/lazycodex_release_notes&gt;/);
+	assert.equal(notice.match(/<lazycodex_release_notes>/g)?.length, 1);
+	assert.equal(notice.match(/<\/lazycodex_release_notes>/g)?.length, 1);
+});

package/packages/omo-codex/plugin/test/auto-update.test.mjs

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { mkdir, mkdtemp, readFile, utimes, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, symlink, utimes, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
@@ -303,9 +303,20 @@ function marketplaceCheckEnv(root, pluginRoot, spawnLogPath, extra = {}) {
 }
 
 test("#given marketplace plugin root without install snapshot #when running check #then skips npx update with marketplace-flow log and upgrade notice", async () => {
-	const { root, pluginRoot } = await makeStorePluginRoot("lazycodex-auto-update-marketplace-");
+	const root = await mkdtemp(join(tmpdir(), "lazycodex-auto-update-marketplace-"));
+	const codexHome = join(root, "codex-home");
+	const pluginRoot = join(codexHome, "plugins", "cache", "sisyphuslabs", "omo", "1.0.0");
 	const spawnLogPath = join(root, "spawn.log");
-	const env = marketplaceCheckEnv(root, pluginRoot, spawnLogPath);
+	await mkdir(join(codexHome, "plugins", "cache", "sisyphuslabs", ".agents", "plugins"), { recursive: true });
+	await mkdir(pluginRoot, { recursive: true });
+	await writeFile(
+		join(codexHome, "plugins", "cache", "sisyphuslabs", ".agents", "plugins", "marketplace.json"),
+		JSON.stringify({
+			name: "sisyphuslabs",
+			plugins: [{ name: "omo", source: { source: "local", path: "./omo/1.0.0" } }],
+		}),
+	);
+	const env = marketplaceCheckEnv(root, pluginRoot, spawnLogPath, { CODEX_HOME: codexHome });
 
 	const result = await runAutoUpdateCheck({ env, now: 123_456 });
 
@@ -329,6 +340,145 @@ test("#given marketplace plugin root without install snapshot #when running chec
 	]);
 });
 
+test("#given marketplace flow with stale local cache state #when running check #then starts npx repair instead of marketplace skip", async () => {
+	const { root, pluginRoot } = await makeStorePluginRoot("lazycodex-auto-update-marketplace-repair-");
+	const spawnLogPath = join(root, "spawn.log");
+	const binDir = join(root, "bin");
+	const codexHome = join(root, "codex-home");
+	const missingCachedCli = join(codexHome, "plugins", "cache", "sisyphuslabs", "omo", "1.0.1", "components", "ulw-loop", "dist", "cli.js");
+	await mkdir(join(codexHome, "plugins", "cache", "sisyphuslabs", ".agents", "plugins"), { recursive: true });
+	await mkdir(binDir, { recursive: true });
+	await writeFile(
+		join(codexHome, "plugins", "cache", "sisyphuslabs", ".agents", "plugins", "marketplace.json"),
+		JSON.stringify({
+			name: "sisyphuslabs",
+			plugins: [{ name: "omo", source: { source: "local", path: "./omo/1.0.1" } }],
+		}),
+	);
+	await symlink(missingCachedCli, join(binDir, "ulw"));
+	const env = marketplaceCheckEnv(root, pluginRoot, spawnLogPath, {
+		CODEX_HOME: codexHome,
+		CODEX_LOCAL_BIN_DIR: binDir,
+	});
+
+	const result = await runAutoUpdateCheck({ env, now: 123_456 });
+
+	assert.equal(result.started, true);
+	assert.equal(result.status, 0);
+	assert.equal(await readFile(spawnLogPath, "utf8"), "ok");
+	assert.equal(result.notices.length, 1);
+	assert.match(result.notices[0], /repair/i);
+	assert.match(result.notices[0], /stale local LazyCodex cache/i);
+	assert.match(result.notices[0], /bundled reinstall repair/);
+	assert.doesNotMatch(result.notices[0], /Repair command/);
+	assert.doesNotMatch(result.notices[0], /plugins[\\/]+cache[\\/]+sisyphuslabs/);
+	const logEntries = (await readFile(env.LAZYCODEX_AUTO_UPDATE_LOG_PATH, "utf8")).trim().split("\n").map((line) => JSON.parse(line));
+	assert.equal(logEntries[0].event, "started");
+	assert.equal(logEntries[0].kind, "marketplace-local-repair");
+	assert.equal(logEntries[0].command, undefined);
+	assert.equal(logEntries[0].args, undefined);
+	assert.deepEqual(logEntries[0].repairReasons, [
+		{ kind: "missing-marketplace-payload" },
+		{ kind: "dangling-managed-bin", binName: "ulw" },
+	]);
+});
+
+test("#given stale marketplace cache and recent success state #when resolving plan #then repair bypasses success throttle", async () => {
+	const { root, pluginRoot } = await makeStorePluginRoot("lazycodex-auto-update-marketplace-repair-throttle-");
+	const spawnLogPath = join(root, "spawn.log");
+	const codexHome = join(root, "codex-home");
+	await mkdir(join(codexHome, "plugins", "cache", "sisyphuslabs", ".agents", "plugins"), { recursive: true });
+	await writeFile(
+		join(codexHome, "plugins", "cache", "sisyphuslabs", ".agents", "plugins", "marketplace.json"),
+		JSON.stringify({
+			name: "sisyphuslabs",
+			plugins: [{ name: "omo", source: { source: "local", path: "./omo/1.0.1" } }],
+		}),
+	);
+	const env = marketplaceCheckEnv(root, pluginRoot, spawnLogPath, {
+		CODEX_HOME: codexHome,
+		LAZYCODEX_LATEST_VERSION: "1.0.1",
+	});
+
+	const plan = resolveAutoUpdatePlan({ env, now: 123_457, lastCheckedAt: 123_456, lastStatus: "success" });
+
+	assert.equal(plan.shouldRun, true);
+	assert.equal(plan.kind, "marketplace-local-repair");
+	assert.deepEqual(plan.repairReasons, [{ kind: "missing-marketplace-payload" }]);
+});
+
+test("#given stale marketplace cache and recent started state #when resolving plan #then repair honors retry throttle", async () => {
+	const { root, pluginRoot } = await makeStorePluginRoot("lazycodex-auto-update-marketplace-repair-retry-");
+	const spawnLogPath = join(root, "spawn.log");
+	const codexHome = join(root, "codex-home");
+	await mkdir(join(codexHome, "plugins", "cache", "sisyphuslabs", ".agents", "plugins"), { recursive: true });
+	await writeFile(
+		join(codexHome, "plugins", "cache", "sisyphuslabs", ".agents", "plugins", "marketplace.json"),
+		JSON.stringify({
+			name: "sisyphuslabs",
+			plugins: [{ name: "omo", source: { source: "local", path: "./omo/1.0.1" } }],
+		}),
+	);
+	const env = marketplaceCheckEnv(root, pluginRoot, spawnLogPath, {
+		CODEX_HOME: codexHome,
+		LAZYCODEX_LATEST_VERSION: "1.0.1",
+	});
+
+	const plan = resolveAutoUpdatePlan({ env, now: 123_457, lastAttemptedAt: 123_456, lastStatus: "started" });
+
+	assert.equal(plan.shouldRun, false);
+	assert.equal(plan.reason, "retry-throttled");
+});
+
+test("#given marketplace flow with stale Windows generated shim #when resolving plan #then starts local repair", async () => {
+	const { root, pluginRoot } = await makeStorePluginRoot("lazycodex-auto-update-marketplace-windows-repair-");
+	const spawnLogPath = join(root, "spawn.log");
+	const binDir = join(root, "bin");
+	const codexHome = join(root, "codex-home");
+	const missingCachedCli = join(codexHome, "plugins", "cache", "sisyphuslabs", "omo", "1.0.1", "components", "ulw-loop", "dist", "cli.js");
+	await mkdir(binDir, { recursive: true });
+	await writeFile(
+		join(binDir, "omo-ulw-loop.cmd"),
+		[
+			"@echo off",
+			":: generated by oh-my-openagent Codex installer",
+			`\"${missingCachedCli}\" %*`,
+			"",
+		].join("\r\n"),
+	);
+	const env = marketplaceCheckEnv(root, pluginRoot, spawnLogPath, {
+		CODEX_HOME: codexHome,
+		CODEX_LOCAL_BIN_DIR: binDir,
+		LAZYCODEX_LATEST_VERSION: "1.0.1",
+	});
+
+	const plan = resolveAutoUpdatePlan({ env, now: 123_456 });
+
+	assert.equal(plan.shouldRun, true);
+	assert.equal(plan.kind, "marketplace-local-repair");
+	assert.deepEqual(plan.repairReasons, [{ kind: "dangling-managed-bin", binName: "omo-ulw-loop" }]);
+});
+
+test("#given marketplace flow with non-managed stale cache-shaped bin #when resolving plan #then skips local repair", async () => {
+	const { root, pluginRoot } = await makeStorePluginRoot("lazycodex-auto-update-marketplace-user-bin-");
+	const spawnLogPath = join(root, "spawn.log");
+	const binDir = join(root, "bin");
+	const codexHome = join(root, "codex-home");
+	const missingCachedCli = join(codexHome, "plugins", "cache", "sisyphuslabs", "omo", "1.0.1", "components", "ulw-loop", "dist", "cli.js");
+	await mkdir(binDir, { recursive: true });
+	await symlink(missingCachedCli, join(binDir, "user-tool"));
+	const env = marketplaceCheckEnv(root, pluginRoot, spawnLogPath, {
+		CODEX_HOME: codexHome,
+		CODEX_LOCAL_BIN_DIR: binDir,
+		LAZYCODEX_LATEST_VERSION: "1.0.1",
+	});
+
+	const plan = resolveAutoUpdatePlan({ env, now: 123_456 });
+
+	assert.equal(plan.shouldRun, false);
+	assert.equal(plan.reason, "marketplace-flow");
+});
+
 test("#given install snapshot at plugin root #when running check #then npx update behavior is unchanged", async () => {
 	const { root, pluginRoot } = await makeStorePluginRoot("lazycodex-auto-update-npx-snapshot-");
 	await writeFile(join(pluginRoot, "lazycodex-install.json"), JSON.stringify({ packageName: "lazycodex-ai", version: "1.0.0" }));

package/packages/omo-codex/plugin/test/install-time-build-runtime.test.mjs

@@ -14,7 +14,7 @@ test("#given aggregate build scripts #when inspected #then component CLIs are bu
 	const componentBuildScript = buildComponentsScript;
 
 	// then
-	assert.match(componentBuildScript, /run\("bun", \["build", entry, "--target", "node", "--format", "esm", "--outfile", output\]/);
+	assert.match(componentBuildScript, /"bun", \["build", entry, "--target", "node", "--format", "esm", "--outfile", output\]/);
 	assert.doesNotMatch(componentBuildScript, /\bbun\s+run\b/);
 });
 

package/packages/omo-codex/plugin/test/sync-skills-test-support.mjs

@@ -25,13 +25,15 @@ export const expectedSkills = [
 	"start-work",
 	"teammode",
 	"ultimate-browsing",
-	"ultraresearch",
+	"ultrawork",
 	"ulw-loop",
 	"ulw-plan",
 	"ulw-research",
 	"visual-qa",
 ];
 
+export const hiddenSharedSkills = ["ultraresearch"];
+
 export const componentSkillSources = [
 	["comment-checker", "components/comment-checker/skills/comment-checker"],
 	["lsp", "components/lsp/skills/lsp"],
@@ -39,6 +41,7 @@ export const componentSkillSources = [
 	["teammode", "components/teammode/skills/teammode"],
 	["ulw-loop", "components/ulw-loop/skills/ulw-loop"],
 	["ulw-plan", "components/ultrawork/skills/ulw-plan"],
+	["ultrawork", "components/ultrawork/skills/ultrawork"],
 ];
 
 const codexCompatibilityEndMarkers = [
@@ -92,6 +95,22 @@ const reviewWorkCodexGatePattern =
 	/\nWhen `review-work` is used as a final implementation, PR, or `\$start-work`\ngate, it is blocking\. A timeout, missing deliverable, ack-only response,\nexplicit `BLOCKED:`, or inconclusive lane is not a pass\. Treat that lane as\nfailed, investigate the underlying uncertainty with the `debugging` skill when\nruntime behavior may be wrong, fix with evidence, and rerun the affected lane\nbefore claiming completion, creating or handing off a PR, or merging\.\n\nWhen reviewing a PR or branch, collect diff, file contents, and verification\nresults from a dedicated review worktree attached to that branch\. Never\ncheckout, test, or edit the review branch in the main worktree\.\n\nReview evidence must be safe to share\. Redact or mask secrets and sensitive\nuser data before including evidence in logs, PR bodies, or handoffs\. Never\ninclude raw tokens, credentials, auth headers, cookies, API keys, env dumps,\nprivate logs, or PII; summarize with lengths, hashes, and short non-sensitive\nprefixes when identity is needed\.\n/;
 
 export function removeCodexSkillOverlays(skillName, content) {
+	if (skillName === "ulw-research") {
+		return content
+			.replace(
+				", any 'ulw' research wording,",
+				", the legacy alias 'ultraresearch', any 'ulw' research wording,",
+			)
+			.replace(
+				"the word \"ulw-research\" (also `/ulw-research`, `$ulw-research`), ",
+				"the word \"ulw-research\" (also `/ulw-research`, `$ulw-research`), the legacy alias \"ultraresearch\" (also `/ultraresearch`, `$ultraresearch`), ",
+			)
+			.replace(
+				"answer those normally, and mention that `ulw-research` is available when a question would clearly benefit from it.",
+				"answer those normally, and mention that `ulw-research` is available (legacy alias: `ultraresearch`) when a question would clearly benefit from it.",
+			)
+			.replace("# ULW-Research Synthesis: <query>", "# Ultraresearch Synthesis: <query>");
+	}
 	if (skillName === "start-work") {
 		return content
 			.replace(startWorkCodexCompletion, startWorkOriginalCompletion)

package/packages/omo-codex/plugin/test/sync-skills.test.mjs

@@ -9,6 +9,7 @@ import {
 	assertPackagedContentMatches,
 	componentSkillSources,
 	expectedSkills,
+	hiddenSharedSkills,
 	listSkillFiles,
 	removeCodexCompatibilityGuidance,
 	removeCodexSkillOverlays,
@@ -29,6 +30,13 @@ function excludeGeneratedSkillMetadata(files) {
 	return files.filter((file) => !generatedSkillMetadataFiles.has(file.replaceAll("\\", "/")));
 }
 
+async function assertNoLegacyResearchAliasInTree(rootDir, label) {
+	for (const file of await listSkillFiles(rootDir)) {
+		const content = await readFile(join(rootDir, file), "utf8");
+		assert.doesNotMatch(content, /ultraresearch/i, `${label}/${file} must not expose ultraresearch`);
+	}
+}
+
 test("#given synced aggregate Codex skills #when inspected #then component and shared skills are present", async () => {
 	// given
 	const skillsRoot = join(root, "skills");
@@ -47,6 +55,26 @@ test("#given synced aggregate Codex skills #when inspected #then component and s
 	}
 });
 
+test("#given reference-only designpowers frontend files #when synced for Codex #then nested SKILL.md files are not packaged", async () => {
+	// given
+	const frontendReferencesRoot = join(root, "skills", "frontend", "references");
+	const designpowersVendorSkillsRoot = join(frontendReferencesRoot, "designpowers", "vendor", "skills");
+
+	// when
+	const nestedSkillFiles = (await listSkillFiles(frontendReferencesRoot))
+		.map((file) => file.replaceAll("\\", "/"))
+		.filter((file) => file.endsWith("/SKILL.md") || file === "SKILL.md")
+		.sort();
+	const designpowersReferenceFiles = (await listSkillFiles(designpowersVendorSkillsRoot))
+		.map((file) => file.replaceAll("\\", "/"))
+		.filter((file) => file.endsWith("/reference.md"))
+		.sort();
+
+	// then
+	assert.deepEqual(nestedSkillFiles, []);
+	assert.equal(designpowersReferenceFiles.length, 27);
+});
+
 test("#given aggregate Codex skills #when source wiring is inspected #then shared skills are imported from the shared-skills package", async () => {
 	// given
 	const pluginPackageJson = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
@@ -85,6 +113,7 @@ test("#given shared skill package source #when aggregate Codex shared skills are
 	// when / then
 	for (const skillName of sharedSkillNames) {
 		if (componentSkillNames.has(skillName)) continue;
+		if (hiddenSharedSkills.includes(skillName)) continue;
 		const sharedContent = await readFile(join(sharedSkillsRoot, skillName, "SKILL.md"), "utf8");
 		const aggregateContent = await readFile(join(aggregateSkillsRoot, skillName, "SKILL.md"), "utf8");
 		assert.equal(
@@ -145,7 +174,7 @@ test("#given component skill sources #when aggregate Codex component skills are
 			const sourceContent = await readFile(join(sourceDir, relativePath), "utf8");
 			const aggregateContent = await readFile(join(aggregateDir, relativePath), "utf8");
 			assert.equal(
-				removeCodexCompatibilityGuidance(aggregateContent),
+				removeCodexSkillOverlays(skillName, removeCodexCompatibilityGuidance(aggregateContent)),
 				removeCodexCompatibilityGuidance(sourceContent),
 				`${skillName}/${relativePath} drifted from its component skill source`,
 			);
@@ -181,18 +210,18 @@ test("#given synced ulw-loop skill #when Codex hint metadata is inspected #then
 	assert.match(interfaceMetadata, /- "ulw-loop"/);
 });
 
-test("#given synced legacy ultraresearch alias #when inspected #then it points users at ulw-research", async () => {
+test("#given shipped Codex skill payloads #when legacy ultraresearch alias is inspected #then it is not packaged", async () => {
 	// given
-	const skillRoot = join(root, "skills", "ultraresearch");
-
-	// when
-	const skill = await readFile(join(skillRoot, "SKILL.md"), "utf8");
-	const interfaceMetadata = await readFile(join(skillRoot, "agents", "openai.yaml"), "utf8");
+	const skillsRoot = join(root, "skills");
+	const skillRoot = join(skillsRoot, "ultraresearch");
 
 	// then
-	assert.match(skill, /^---\r?\nname: ultraresearch\r?\n/m);
-	assert.match(skill, /legacy name for `ulw-research`/);
-	assert.match(interfaceMetadata, /display_name: "\(OmO\) ultraresearch"/);
+	await assert.rejects(readFile(join(skillRoot, "SKILL.md"), "utf8"), { code: "ENOENT" });
+	await assert.rejects(readFile(join(skillRoot, "agents", "openai.yaml"), "utf8"), { code: "ENOENT" });
+	await assertNoLegacyResearchAliasInTree(skillsRoot, "skills");
+	for (const [skillName, sourcePath] of componentSkillSources) {
+		await assertNoLegacyResearchAliasInTree(join(root, sourcePath), `components/${skillName}`);
+	}
 });
 
 test("#given synced git-master skill #when inspected #then commits and git history route through it", async () => {

package/packages/omo-codex/plugin/test/ultrawork-skill-pointer.test.mjs

@@ -0,0 +1,56 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+
+import { root } from "./aggregate-plugin-fixture.mjs";
+
+const POINTER_MAX_BYTES = 4096;
+const skillPath = join(root, "skills", "ultrawork", "SKILL.md");
+
+function runUserPromptSubmitCli(component, extraArgs = []) {
+	const payload = {
+		hook_event_name: "UserPromptSubmit",
+		session_id: "s-ultrawork-pointer",
+		turn_id: "t-ultrawork-pointer",
+		transcript_path: null,
+		cwd: root,
+		model: "gpt-5.5",
+		permission_mode: "default",
+		prompt: "ulw this change",
+	};
+	return spawnSync(
+		process.execPath,
+		[join(root, "components", component, "dist", "cli.js"), "hook", "user-prompt-submit", ...extraArgs],
+		{ cwd: root, encoding: "utf8", input: `${JSON.stringify(payload)}\n` },
+	);
+}
+
+test("#given synced skills #when the ultrawork skill is inspected #then it carries the full directive body", () => {
+	assert.equal(existsSync(skillPath), true);
+	const skill = readFileSync(skillPath, "utf8");
+	const directive = readFileSync(join(root, "components", "ultrawork", "directive.md"), "utf8");
+	assert.match(skill, /^---\nname: ultrawork\n/);
+	assert.equal(skill.endsWith(directive), true);
+	assert.match(skill, /## 1\. Create the goal with binding success criteria/);
+});
+
+test("#given the built ultrawork CLI #when a ulw prompt is submitted #then a compact skill pointer is emitted", () => {
+	const result = runUserPromptSubmitCli("ultrawork");
+	assert.equal(result.status, 0);
+	const output = JSON.parse(result.stdout);
+	const context = output.hookSpecificOutput.additionalContext;
+	assert.match(context, /^<ultrawork-mode>/);
+	assert.match(context, /First user-visible line this turn MUST be exactly:/);
+	assert.match(context, /create_goal/);
+	assert.equal(context.includes(skillPath), true);
+	assert.equal(context.includes("Tier triage"), false);
+	assert.equal(Buffer.byteLength(context, "utf8") < POINTER_MAX_BYTES, true);
+});
+
+test("#given the built ultrawork and ulw-loop CLIs #when both emit the pointer #then the payloads match byte for byte", () => {
+	const ultrawork = JSON.parse(runUserPromptSubmitCli("ultrawork").stdout);
+	const ulwLoop = JSON.parse(runUserPromptSubmitCli("ulw-loop", ["--with-ultrawork"]).stdout);
+	assert.equal(ulwLoop.hookSpecificOutput.additionalContext, ultrawork.hookSpecificOutput.additionalContext);
+});

package/packages/omo-codex/plugin/test/ulw-research-epistemic-contract.test.mjs

@@ -0,0 +1,98 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { sharedSkillsRootPath } from "@oh-my-opencode/shared-skills";
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+
+async function readUlwResearchCopies() {
+	const sharedPath = join(sharedSkillsRootPath(), "ulw-research", "SKILL.md");
+	const packagedPath = join(root, "skills", "ulw-research", "SKILL.md");
+	return [
+		{ label: "shared", path: sharedPath, content: await readFile(sharedPath, "utf8") },
+		{ label: "packaged", path: packagedPath, content: await readFile(packagedPath, "utf8") },
+	];
+}
+
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function markdownSection(content, heading, nextHeading) {
+	const headingPattern = new RegExp(`^${escapeRegExp(heading)}\\r?$`, "m");
+	const headingMatch = content.match(headingPattern);
+	assert.notEqual(headingMatch, null, `SKILL.md section not found: ${heading}`);
+	assert.notEqual(headingMatch.index, undefined, `SKILL.md section index not found: ${heading}`);
+	const bodyStart = headingMatch.index + headingMatch[0].length;
+	if (nextHeading === undefined) return content.slice(bodyStart);
+	const nextHeadingIndex = content.indexOf(`\n${nextHeading}`, bodyStart);
+	assert.notEqual(nextHeadingIndex, -1, `SKILL.md next section not found: ${nextHeading}`);
+	return content.slice(bodyStart, nextHeadingIndex);
+}
+
+test("#given ulw-research epistemic instrumentation #when the research contract is inspected #then the meta-layer artifacts and fields are required", async () => {
+	for (const copy of await readUlwResearchCopies()) {
+		const section = markdownSection(copy.content, "## Epistemic instrumentation", "## Run the swarm as a cooperating team");
+		assert.match(section, /intent-diff\.md/i, `${copy.label}: body must require an intent-vs-reality diff artifact`);
+		assert.match(section, /expected truth/i, `${copy.label}: intent diff must record expected truth`);
+		assert.match(section, /observed reality/i, `${copy.label}: intent diff must record observed reality`);
+		assert.match(section, /diff, violated invariant/i, `${copy.label}: intent diff must record the diff gap field and violated invariant`);
+		assert.match(section, /claim-graph\.md/i, `${copy.label}: body must require a claim graph`);
+		assert.match(section, /independent observation groups/i, `${copy.label}: claim graph must track independent observation groups`);
+		assert.match(section, /convergence status/i, `${copy.label}: claim graph must track convergence status`);
+		const claimGraphBullet = section.split("\n").find((line) => line.includes("`claim-graph.md`"));
+		assert.notEqual(claimGraphBullet, undefined, `${copy.label}: claim graph bullet must exist`);
+		assert.match(claimGraphBullet, /single claim store/i, `${copy.label}: claim graph must be the single claim store`);
+		assert.match(claimGraphBullet, /risk tier/i, `${copy.label}: claim graph nodes must carry a risk tier`);
+		assert.match(claimGraphBullet, /counter-search/i, `${copy.label}: claim graph nodes must carry the counter-search result`);
+		assert.match(claimGraphBullet, /primary source/i, `${copy.label}: claim graph nodes must carry primary source backing`);
+		assert.match(claimGraphBullet, /verified-claims/i, `${copy.label}: cleared nodes must feed the verified-claims digest`);
+		assert.match(section, /observation-manifest\.md/i, `${copy.label}: body must require an observation manifest`);
+		assert.match(section, /observer group/i, `${copy.label}: observation manifest must record observer groups`);
+		assert.match(section, /independence basis/i, `${copy.label}: observation manifest must record independence basis`);
+		assert.match(section, /observed_at/i, `${copy.label}: temporal evidence must include observed_at`);
+		assert.match(section, /valid_at|claim_valid_at/i, `${copy.label}: temporal evidence must include a validity field`);
+		assert.match(section, /verification-economics\.md/i, `${copy.label}: body must require verification economics`);
+		assert.match(section, /cause-disappearance\.md/i, `${copy.label}: body must require cause-disappearance records`);
+		assert.match(section, /last_seen/i, `${copy.label}: cause-disappearance records must track last_seen`);
+		assert.match(section, /disconfirming observation/i, `${copy.label}: cause-disappearance records must track disconfirming observations`);
+		assert.match(section, /no longer observed/i, `${copy.label}: cause-disappearance records must support no-longer-observed verdicts`);
+	}
+});
+
+test("#given ulw-research readiness gates #when synthesis rules are inspected #then diff closure and independent convergence are required", async () => {
+	for (const copy of await readUlwResearchCopies()) {
+		const success = markdownSection(copy.content, "## Success criteria", "## Epistemic instrumentation");
+		const phase4 = markdownSection(copy.content, "## Phase 4 — Synthesize", "## Phase 5 — Final materials");
+		assert.match(success, /intent-vs-reality diff/i, `${copy.label}: success criteria must require intent diff closure`);
+		assert.match(success, /independent observation groups/i, `${copy.label}: success criteria must require independent observations`);
+		assert.match(success, /convergence/i, `${copy.label}: success criteria must require convergence`);
+		assert.match(phase4, /intent-diff\.md/i, `${copy.label}: synthesis must start from the intent diff`);
+		assert.match(phase4, /independent-observation convergence/i, `${copy.label}: synthesis must summarize independent convergence`);
+	}
+});
+
+test("#given ulw-research observation instrumentation #when worker ownership is inspected #then workers return candidates as message text and the orchestrator writes manifests", async () => {
+	for (const copy of await readUlwResearchCopies()) {
+		assert.match(copy.content, /observation candidates?|claim candidates?/i, `${copy.label}: workers must return claim and observation candidates`);
+		assert.match(copy.content, /message text/i, `${copy.label}: claim and observation candidates must travel as message text`);
+		assert.match(copy.content, /orchestrator-owned|orchestrator owns/i, `${copy.label}: instrumentation artifacts must be orchestrator-owned`);
+		assert.doesNotMatch(
+			copy.content,
+			/worker[^.]*\b(?:write|append|create)s?\b[^.]*(?:intent-diff|observation-manifest|claim-graph|verification-economics|cause-disappearance)/i,
+			`${copy.label}: workers must not write instrumentation artifacts directly`,
+		);
+	}
+});
+
+test("#given the claim graph as the single claim store #when the retired ledger is scanned #then claim-ledger is gone and the gate lives on graph nodes", async () => {
+	for (const copy of await readUlwResearchCopies()) {
+		assert.doesNotMatch(copy.content, /claim[- ]ledger/i, `${copy.label}: the retired claim-ledger artifact must not appear`);
+		const phase3b = markdownSection(copy.content, "## Phase 3b — Lock non-code claims through the claim graph", "## Phase 4 — Synthesize");
+		assert.match(phase3b, /claim-graph\.md/i, `${copy.label}: the gate must record outcomes on claim-graph nodes`);
+		assert.match(phase3b, /verified-claims/i, `${copy.label}: the verified-claims allowlist digest must survive the merge`);
+		assert.match(phase3b, /sole allowlist/i, `${copy.label}: the data-flow-lock must stay self-enforcing`);
+	}
+});

package/packages/omo-codex/plugin/test/ulw-research-skill-contract.test.mjs

@@ -77,7 +77,11 @@ test("#given ulw-research description #when activation policy is inspected #then
 	for (const copy of await readUlwResearchCopies()) {
 		const description = frontmatterDescription(copy.content);
 		assert.match(description, /ulw-research/i, `${copy.label}: description must name the ulw-research trigger`);
-		assert.match(description, /ultraresearch/i, `${copy.label}: description must preserve ultraresearch discoverability`);
+		if (copy.label === "shared") {
+			assert.match(description, /ultraresearch/i, `${copy.label}: description must preserve ultraresearch discoverability`);
+		} else {
+			assert.doesNotMatch(description, /ultraresearch/i, `${copy.label}: description must not expose ultraresearch`);
+		}
 		assert.match(description, /\bulw\b/i, `${copy.label}: description must preserve ulw discoverability`);
 		assert.match(description, /explicit/i, `${copy.label}: description must gate activation on explicit demand`);
 		assert.match(
@@ -89,6 +93,20 @@ test("#given ulw-research description #when activation policy is inspected #then
 	}
 });
 
+test("#given packaged ulw-research skill #when scanned for legacy aliases #then ultraresearch is not exposed", async () => {
+	const packaged = (await readUlwResearchCopies()).find((copy) => copy.label === "packaged");
+	assert.notEqual(packaged, undefined, "packaged copy not found");
+	assert.doesNotMatch(packaged.content, /ultraresearch/i, "packaged ulw-research must not expose ultraresearch");
+});
+
+test("#given packaged ulw-research skill #when Codex guidance is inspected #then compatibility guidance is preserved", async () => {
+	const packaged = (await readUlwResearchCopies()).find((copy) => copy.label === "packaged");
+	assert.notEqual(packaged, undefined, "packaged copy not found");
+	assert.match(packaged.content, /## Codex Harness Tool Compatibility/);
+	assert.match(packaged.content, /multi_agent_v1\.spawn_agent/);
+	assert.match(packaged.content, /multi_agent_v1\.wait_agent/);
+});
+
 test("#given ulw-research body #when authority is inspected #then it takes precedence over exploration-bounding instructions", async () => {
 	for (const copy of await readUlwResearchCopies()) {
 		assert.match(
@@ -227,22 +245,22 @@ test("#given ulw-research default swarm #when team guidance is inspected #then t
 	}
 });
 
-test("#given ulw-research non-code verification #when the gate is inspected #then a claim ledger / verified-claims data-flow-lock exists", async () => {
+test("#given ulw-research non-code verification #when the gate is inspected #then a claim graph / verified-claims data-flow-lock exists", async () => {
 	for (const copy of await readUlwResearchCopies()) {
 		assert.match(
 			copy.content,
-			/claim ledger|verified-claims/i,
-			`${copy.label}: body must define the non-code claim-ledger verification gate`,
+			/claim graph|verified-claims/i,
+			`${copy.label}: body must define the non-code claim-graph verification gate`,
 		);
 	}
 });
 
-test("#given ulw-research claim ledger #when ownership is inspected #then workers never write the ledger / verified-claims artifact", async () => {
+test("#given ulw-research claim graph #when ownership is inspected #then workers never write the graph / verified-claims artifact", async () => {
 	for (const copy of await readUlwResearchCopies()) {
 		assert.doesNotMatch(
 			copy.content,
-			/worker[^.]*\b(?:write|append|create)s?\b[^.]*(?:ledger|verified-claims)/i,
-			`${copy.label}: workers must not be instructed to write/append/create the ledger or verified-claims`,
+			/worker[^.]*\b(?:write|append|create)s?\b[^.]*(?:claim[- ]graph|verified-claims)/i,
+			`${copy.label}: workers must not be instructed to write/append/create the claim graph or verified-claims`,
 		);
 	}
 });