oh-my-opencode 4.8.0 → 4.9.0

package/packages/omo-codex/plugin/test/migrate-codex-config.test.mjs

@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import test from "node:test";
 
+import { forceDisableMultiAgentV2 } from "../scripts/migrate-codex-config/multi-agent-v2-guard.mjs";
 import { ensureCodexReasoningConfig, migrateCodexConfig } from "../scripts/migrate-codex-config.mjs";
 
 test("#given stale root reasoning config #when ensuring config #then replaces stale values without duplicate keys", () => {
@@ -192,6 +193,9 @@ test("#given user-customized Codex model config #when migrating #then user value
 			'model_reasoning_effort = "medium"',
 			'plan_mode_reasoning_effort = "medium"',
 			"",
+			"[features.multi_agent_v2]",
+			"enabled = false",
+			"",
 		].join("\n"),
 	);
 
@@ -325,6 +329,9 @@ test("#given config already matches current catalog #when catalog version advanc
 			'model_reasoning_effort = "high"',
 			'plan_mode_reasoning_effort = "xhigh"',
 			"",
+			"[features.multi_agent_v2]",
+			"enabled = false",
+			"",
 		].join("\n"),
 	);
 	await writeFile(
@@ -361,6 +368,260 @@ test("#given config already matches current catalog #when catalog version advanc
 	assert.equal(state.files[configPath].catalogVersion, "test.role-only");
 });
 
+test("#given multi_agent_v2 enabled #when forcing disable #then flips the flag to false", () => {
+	const config = [
+		'model = "gpt-5.5"',
+		'model_reasoning_effort = "high"',
+		"",
+		"[features.multi_agent_v2]",
+		"enabled = true",
+		"max_concurrent_threads_per_session = 10000",
+		"",
+	].join("\n");
+
+	const result = forceDisableMultiAgentV2(config);
+
+	assert.match(result, /enabled = false/);
+	assert.doesNotMatch(result, /enabled = true/);
+	assert.match(result, /max_concurrent_threads_per_session = 10000/);
+});
+
+test("#given no multi_agent_v2 section #when forcing disable #then appends a disabled section", () => {
+	const config = [
+		'model = "gpt-5.5"',
+		'model_reasoning_effort = "high"',
+		"",
+		"[features]",
+		"plugins = true",
+		"",
+	].join("\n");
+
+	const result = forceDisableMultiAgentV2(config);
+
+	assert.match(result, /\[features\.multi_agent_v2\]\nenabled = false\n/);
+	assert.match(result, /plugins = true/);
+});
+
+test("#given multi_agent_v2 section without enabled key #when forcing disable #then inserts enabled = false", () => {
+	const config = [
+		'model = "gpt-5.5"',
+		"",
+		"[features.multi_agent_v2]",
+		"max_concurrent_threads_per_session = 10000",
+		"",
+	].join("\n");
+
+	const result = forceDisableMultiAgentV2(config);
+
+	assert.match(result, /\[features\.multi_agent_v2\]\nenabled = false\n/);
+	assert.match(result, /max_concurrent_threads_per_session = 10000/);
+});
+
+test("#given [features] boolean shorthand multi_agent_v2 = true #when forcing disable #then removes it and appends a disabled section", () => {
+	const config = [
+		'model = "gpt-5.5"',
+		"",
+		"[features]",
+		"plugins = true",
+		"multi_agent_v2 = true",
+		"",
+	].join("\n");
+
+	const result = forceDisableMultiAgentV2(config);
+
+	assert.doesNotMatch(result, /^multi_agent_v2\s*=/m);
+	assert.match(result, /\[features\.multi_agent_v2\]\nenabled = false\n/);
+	assert.match(result, /plugins = true/);
+});
+
+test("#given multi_agent_v2 enabled #when forcing disable #then annotates the managed section with the upstream issue and opt-out", () => {
+	const config = [
+		'model = "gpt-5.5"',
+		"",
+		"[features.multi_agent_v2]",
+		"enabled = true",
+		"",
+	].join("\n");
+
+	const result = forceDisableMultiAgentV2(config);
+
+	assert.match(result, /openai\/codex#26753/);
+	assert.match(result, /LAZYCODEX_CONFIG_MIGRATION_DISABLED=1/);
+	assert.match(result, /^#[^\n]*\n(?:#[^\n]*\n)*\[features\.multi_agent_v2\]/m);
+});
+
+test("#given no multi_agent_v2 section #when forcing disable #then annotates the appended section", () => {
+	const config = ['model = "gpt-5.5"', ""].join("\n");
+
+	const result = forceDisableMultiAgentV2(config);
+
+	assert.match(result, /openai\/codex#26753/);
+	assert.match(result, /^#[^\n]*\n(?:#[^\n]*\n)*\[features\.multi_agent_v2\]\nenabled = false\n/m);
+});
+
+test("#given an annotated managed section #when forcing disable runs again #then does not duplicate the comment", () => {
+	const config = ['model = "gpt-5.5"', "", "[features.multi_agent_v2]", "enabled = true", ""].join("\n");
+
+	const annotated = forceDisableMultiAgentV2(config);
+	const rerun = forceDisableMultiAgentV2(`${annotated.replace("enabled = false", "enabled = true")}`);
+
+	const markers = rerun.match(/openai\/codex#26753/g) ?? [];
+	assert.equal(markers.length, 1);
+	assert.match(rerun, /enabled = false/);
+});
+
+test("#given [features] boolean shorthand multi_agent_v2 = false #when forcing disable #then returns config unchanged", () => {
+	const config = [
+		'model = "gpt-5.5"',
+		"",
+		"[features]",
+		"multi_agent_v2 = false",
+		"",
+	].join("\n");
+
+	const result = forceDisableMultiAgentV2(config);
+
+	assert.equal(result, config);
+});
+
+test("#given multi_agent_v2 already disabled #when forcing disable #then returns config unchanged", () => {
+	const config = [
+		'model = "gpt-5.5"',
+		'model_reasoning_effort = "high"',
+		"",
+		"[features.multi_agent_v2]",
+		"enabled = false",
+		"max_concurrent_threads_per_session = 10000",
+		"",
+	].join("\n");
+
+	const result = forceDisableMultiAgentV2(config);
+
+	assert.equal(result, config);
+});
+
+test("#given global config without multi_agent_v2 section #when full migration runs #then writes a disabled section on disk", async () => {
+	const root = await mkdtemp(join(tmpdir(), "lazycodex-multi-agent-v2-guard-"));
+	const codexHome = join(root, "codex-home");
+	await mkdir(codexHome, { recursive: true });
+	const configPath = join(codexHome, "config.toml");
+	await writeFile(
+		configPath,
+		[
+			'model = "gpt-5.5"',
+			'model_reasoning_effort = "high"',
+			"",
+		].join("\n"),
+	);
+
+	const result = await migrateCodexConfig({
+		env: { CODEX_HOME: codexHome, LAZYCODEX_MODEL_CATALOG_STATE_PATH: join(root, "model-state.json") },
+		cwd: root,
+	});
+
+	assert.deepEqual(result.changed, [configPath]);
+	const content = await readFile(configPath, "utf8");
+	assert.match(content, /\[features\.multi_agent_v2\]\nenabled = false\n/);
+});
+
+test("#given global config with forced multi_agent_v2 #when full migration runs #then disables it on disk", async () => {
+	const root = await mkdtemp(join(tmpdir(), "lazycodex-multi-agent-v2-guard-"));
+	const codexHome = join(root, "codex-home");
+	await mkdir(codexHome, { recursive: true });
+	const configPath = join(codexHome, "config.toml");
+	await writeFile(
+		configPath,
+		[
+			'model = "gpt-5.5"',
+			'model_reasoning_effort = "high"',
+			"",
+			"[features.multi_agent_v2]",
+			"enabled = true",
+			"max_concurrent_threads_per_session = 10000",
+			"",
+		].join("\n"),
+	);
+
+	const result = await migrateCodexConfig({
+		env: { CODEX_HOME: codexHome, LAZYCODEX_MODEL_CATALOG_STATE_PATH: join(root, "model-state.json") },
+		cwd: root,
+	});
+
+	assert.deepEqual(result.changed, [configPath]);
+	const content = await readFile(configPath, "utf8");
+	assert.match(content, /enabled = false/);
+	assert.doesNotMatch(content, /enabled = true/);
+});
+
+test("#given enabled = true with an inline comment #when forcing disable #then flips to false and preserves the comment", () => {
+	const config = ["[features.multi_agent_v2]", "enabled = true # tuned by me", ""].join("\n");
+
+	const result = forceDisableMultiAgentV2(config);
+
+	assert.match(result, /^enabled = false # tuned by me$/m);
+	assert.doesNotMatch(result, /enabled = true/);
+	assert.equal((result.match(/^\s*enabled\s*=/gm) ?? []).length, 1);
+	assert.equal((result.match(/\[features\.multi_agent_v2\]/g) ?? []).length, 1);
+});
+
+test("#given a section header with an inline comment #when forcing disable #then patches in place without duplicating the table", () => {
+	const config = ["[features.multi_agent_v2] # pinned by me", "enabled = true", ""].join("\n");
+
+	const result = forceDisableMultiAgentV2(config);
+
+	assert.equal((result.match(/\[features\.multi_agent_v2\]/g) ?? []).length, 1);
+	assert.match(result, /enabled = false/);
+	assert.doesNotMatch(result, /enabled = true/);
+	assert.match(result, /# pinned by me/);
+});
+
+test("#given an already-guarded commented config #when re-running #then output is byte-identical", () => {
+	const configA = ["[features.multi_agent_v2]", "enabled = true # tuned by me", ""].join("\n");
+	const configB = ["[features.multi_agent_v2] # pinned by me", "enabled = true", ""].join("\n");
+
+	const firstA = forceDisableMultiAgentV2(configA);
+	const rerunA = forceDisableMultiAgentV2(firstA);
+	assert.equal(rerunA, firstA);
+
+	const firstB = forceDisableMultiAgentV2(configB);
+	const rerunB = forceDisableMultiAgentV2(firstB);
+	assert.equal(rerunB, firstB);
+});
+
+test("#given user-disabled with an inline comment #when forcing disable #then returns config unchanged", () => {
+	const config = ["[features.multi_agent_v2]", "enabled = false # I turned this off myself", ""].join("\n");
+
+	const result = forceDisableMultiAgentV2(config);
+
+	assert.equal(result, config);
+});
+
+test("#given [features] shorthand true with an inline comment #when forcing disable #then removes the shorthand and appends one disabled table", () => {
+	const config = ["[features]", "plugins = true", "multi_agent_v2 = true # legacy", ""].join("\n");
+
+	const result = forceDisableMultiAgentV2(config);
+
+	assert.doesNotMatch(result, /^\s*multi_agent_v2\s*=/m);
+	assert.equal((result.match(/\[features\.multi_agent_v2\]/g) ?? []).length, 1);
+	assert.match(result, /\[features\.multi_agent_v2\]\nenabled = false\n/);
+	assert.match(result, /plugins = true/);
+});
+
+test("#given a following section header with an inline comment #when inserting enabled=false #then does not leak into the next section", () => {
+	const config = [
+		"[features.multi_agent_v2]",
+		"max_concurrent_threads_per_session = 2",
+		"[mcp_servers.x] # note",
+		"enabled = true",
+		"",
+	].join("\n");
+
+	const result = forceDisableMultiAgentV2(config);
+
+	assert.match(result, /\[features\.multi_agent_v2\]\nenabled = false\n/);
+	assert.match(result, /\[mcp_servers\.x\][^\n]*\nenabled = true/);
+});
+
 async function canCreateSymlink(type) {
 	const root = await mkdtemp(join(tmpdir(), "lazycodex-symlink-capability-"));
 	const target = join(root, "target");

package/packages/omo-codex/plugin/test/start-work-skill.test.mjs

@@ -43,33 +43,6 @@ test("#given start-work skill without selectable plan #when inspected #then boot
 	assert.deepEqual(missing, []);
 });
 
-test("#given worker done claim #when start-work contract is inspected #then adversarial verification gates fully done", async () => {
-	// given
-	const missing = [];
-
-	// when
-	for (const skillPath of startWorkSkillPaths) {
-		const skill = await readFile(skillPath, "utf8");
-		if (
-			!/DoneClaim/i.test(skill) ||
-			!/worker done claim/i.test(skill) ||
-			!/stale_state/.test(skill) ||
-			!/misleading_success_output/.test(skill) ||
-			!/dirty_worktree/.test(skill) ||
-			!/Plan reread/i.test(skill) ||
-			!/Manual-QA/i.test(skill) ||
-			!/Adversarial QA/i.test(skill) ||
-			!/Cleanup/i.test(skill) ||
-			!/Only after verification passes/i.test(skill)
-		) {
-			missing.push(skillPath);
-		}
-	}
-
-	// then
-	assert.deepEqual(missing, []);
-});
-
 test("#given packaged start-work completion surfaces #when inspected #then global review and debugging gate blocks completion", async () => {
 	// given
 	const [startWorkSkill, reviewWorkSkill, hephaestusRule] = await Promise.all([
@@ -83,13 +56,18 @@ test("#given packaged start-work completion surfaces #when inspected #then globa
 	assert.match(startWorkSkill, /\breview-work\b/);
 	assert.match(startWorkSkill, /\bdebugging\b/);
 	assert.match(startWorkSkill, /inconclusive/i);
-	assert.match(startWorkSkill, /redact|mask/i);
-	assert.match(startWorkSkill, /raw (?:tokens|credentials|auth headers|cookies)/i);
-	assert.match(startWorkSkill, /ORCHESTRATION COMPLETE/);
 	assert.match(reviewWorkSkill, /debugging/i);
 	assert.match(reviewWorkSkill, /inconclusive/i);
 	assert.match(hephaestusRule, /Global Review and Debugging Gate/);
-	assert.match(hephaestusRule, /redact.*secrets.*PII/s);
+});
+
+test("#given start-work skill #when echo discipline is inspected #then the ultraqa class list is enumerated once and the budget holds", async () => {
+	// given
+	const skill = await readFile(startWorkSkillPaths[0], "utf8");
+
+	// then
+	assert.equal((skill.match(/malformed input/g) ?? []).length, 1);
+	assert.ok(skill.split(/\s+/).filter(Boolean).length <= 1924);
 });
 
 test("#given start-work continuation hook #when inspected #then it remains Boulder-only without planning bootstrap logic", async () => {

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

@@ -58,7 +58,7 @@ call_omo_agent(subagent_type="explore", prompt="inspect")
 
 Older variant guidance.
 
-When translating \`load_skills=[...]\`, name the skills inside the spawned agent's \`message\`.
+When translating \`load_skills=[...]\`, name the skills inside the spawned agent's \`message\`. If a code block below conflicts with this section, this section wins.
 
 ---
 
@@ -103,6 +103,71 @@ call_omo_agent(subagent_type="explore", prompt="inspect")
 	assert.equal(adapted, content);
 });
 
+test("#given early generated stale Codex compatibility guidance #when adapting a skill #then it is replaced", () => {
+	// given
+	const content = `---
+name: example
+---
+
+## Codex Harness Tool Compatibility
+
+This skill may include examples copied from the OpenCode harness. In Codex, do not call OpenCode-only tools such as \`call_omo_agent(...)\`, \`task(...)\`, \`background_output(...)\`, or \`team_*(...)\` literally. Translate those examples to Codex native tools:
+
+| OpenCode example | Codex tool to use |
+| --- | --- |
+| \`call_omo_agent(subagent_type="explore", ...)\` | \`spawn_agent({"task_name":"...","message":"TASK: act as an explorer. ...","fork_turns":"none"})\` |
+| \`background_output(task_id="...")\` | \`wait_agent(...)\` for mailbox signals; after a timeout, run one \`list_agents\` check for the named child if reassurance is needed |
+
+Codex full-history forks inherit parent context, so role-specific behavior must be described in a self-contained \`message\` and usually should use a non-full-history fork mode such as \`fork_turns="none"\`. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's \`message\`. If a code block below conflicts with this section, this section wins.
+
+For work likely to exceed one wait cycle, require the child to send \`WORKING: <task> - <current phase>\` before long passes and \`BLOCKED: <reason>\` only when progress stops. A \`wait_agent\` timeout only means no new mailbox update arrived. Treat a running child or latest \`WORKING:\` message as alive. Do not use \`list_agents\` as a polling loop. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly \`BLOCKED:\`, or no longer running.
+
+When translating \`load_skills=[...]\`, include the requested skill names in the spawned agent's \`message\`. If a code block below conflicts with this section, this section wins.
+
+# Example Skill
+
+call_omo_agent(subagent_type="explore", prompt="inspect")
+`;
+
+	// when
+	const adapted = insertCodexCompatibilityGuidance(content);
+
+	// then
+	assert.match(adapted, /multi_agent_v1\.spawn_agent/);
+	assert.match(adapted, /fork_context":false/);
+	assert.match(adapted, /"agent_type":"explorer"/);
+	assert.match(adapted, /multi_agent_v1\.wait_agent/);
+	assert.doesNotMatch(adapted, /fork_turns="none"/);
+	assert.doesNotMatch(adapted, /list_agents/);
+});
+
+test("#given generated guidance before a template export #when adapting a skill #then the export wrapper is preserved", () => {
+	// given
+	const content = `---
+name: refactor
+---
+
+## Codex Harness Tool Compatibility
+
+Older variant guidance.
+
+When translating \`load_skills=[...]\`, name the skills inside the spawned agent's \`message\`. If a code block below conflicts with this section, this section wins.
+
+export const REFACTOR_TEMPLATE = \`# Refactor
+
+call_omo_agent(subagent_type="explore", prompt="inspect")
+\`
+`;
+
+	// when
+	const adapted = insertCodexCompatibilityGuidance(content);
+
+	// then
+	assert.match(adapted, /export const REFACTOR_TEMPLATE = `# Refactor/);
+	assert.match(adapted, /multi_agent_v1\.spawn_agent/);
+	assert.doesNotMatch(adapted, /Older variant guidance/);
+});
+
 test("#given synced aggregate Codex skills #when they describe background orchestration #then liveness is framed as progress rather than timeout failure", async () => {
 	// given
 	const orchestrationPattern = /\b(?:run_in_background|background_output|wait_agent)\b/;
@@ -110,8 +175,7 @@ test("#given synced aggregate Codex skills #when they describe background orches
 		["working progress message", /WORKING:/],
 		["blocked progress message", /BLOCKED:/],
 		["mailbox timeout framing", /timeout only means no new mailbox update arrived/],
-		["single liveness check", /single `list_agents` check|one `list_agents` check/],
-		["polling-loop guard", /Do not use `list_agents` as a polling loop|Do NOT use `list_agents` as a polling loop/],
+		["multi_agent_v1.wait_agent ref", /multi_agent_v1\.wait_agent/],
 		["explicit fallback conditions", /Fallback only when|Mark a file for retry only when/],
 	];
 	const bannedPatterns = [
@@ -148,5 +212,5 @@ test("#given review-work skill #when some lanes do not finish #then aggregate re
 	assert.match(content, /Overall Verdict: PASSED \/ FAILED \/ INCONCLUSIVE/);
 	assert.match(content, /PASS\/FAIL\/INCONCLUSIVE \| HIGH\/MED\/LOW/);
 	assert.match(content, /Do not spin in repeated/);
-	assert.match(content, /Do not use `send_message` as an interrupt/);
+	assert.match(content, /Do not use `multi_agent_v1\.send_input` as an interrupt/);
 });

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

@@ -0,0 +1,119 @@
+import assert from "node:assert/strict";
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+
+export const CONTEXT_PRESSURE_SKILL_BUDGET_BYTES = 25_000;
+
+export const expectedSkills = [
+	"comment-checker",
+	"debugging",
+	"frontend-ui-ux",
+	"git-master",
+	"init-deep",
+	"lcx-contribute-bug-fix",
+	"lcx-doctor",
+	"lcx-report-bug",
+	"lsp",
+	"lsp-setup",
+	"programming",
+	"refactor",
+	"remove-ai-slops",
+	"review-work",
+	"rules",
+	"start-work",
+	"ultraresearch",
+	"ulw-loop",
+	"ulw-plan",
+	"visual-qa",
+];
+
+export const componentSkillSources = [
+	["comment-checker", "components/comment-checker/skills/comment-checker"],
+	["lsp", "components/lsp/skills/lsp"],
+	["rules", "components/rules/skills/rules"],
+	["ulw-loop", "components/ulw-loop/skills/ulw-loop"],
+	["ulw-plan", "components/ultrawork/skills/ulw-plan"],
+];
+
+const codexCompatibilityEndMarkers = [
+	"For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.\n\n",
+	"Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.\n\n",
+	"For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `wait_agent` timeout only means no new mailbox update arrived. Treat a running child or latest `WORKING:` message as alive. Do not use `list_agents` as a polling loop. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.\n\n",
+	"Codex full-history forks inherit parent context, so role-specific behavior must be described in a self-contained `message` and usually should use a non-full-history fork mode such as `fork_turns=\"none\"`. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.\n\n",
+	"When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.\n\n",
+	"When translating `load_skills=[...]`, name the skills inside the spawned agent's `message`. If a code block below conflicts with this section, this section wins.\n\n",
+];
+
+export function removeCodexCompatibilityGuidance(content) {
+	const start = content.indexOf("## Codex Harness Tool Compatibility\n\n");
+	if (start === -1) return content;
+	const structuralEndPattern = /\n(?:---|export\s+const\s+|#{1,6}\s)/g;
+	structuralEndPattern.lastIndex = start + "## Codex Harness Tool Compatibility\n\n".length;
+	const structuralEnd = structuralEndPattern.exec(content);
+	if (structuralEnd) return `${content.slice(0, start)}${content.slice(structuralEnd.index + 1)}`;
+
+	const endMarker = codexCompatibilityEndMarkers.find((marker) => content.indexOf(marker, start) !== -1);
+	assert.notEqual(endMarker, undefined, "Codex compatibility guidance block is missing its terminator");
+	const end = content.indexOf(endMarker, start);
+	assert.notEqual(end, -1, "Codex compatibility guidance block is missing its terminator");
+	return `${content.slice(0, start)}${content.slice(end + endMarker.length)}`;
+}
+
+const startWorkOriginalCompletion = `When all top-level checkboxes in \`## TODOs\` and \`## Final Verification Wave\` are complete:
+
+1. Run the plan's final verification commands.
+2. If worktree mode was used, sync \`.omo/\` state back to the main repo, merge or hand off exactly as requested, and remove the worktree only after successful merge or explicit handoff.
+3. Remove or mark the Boulder work as completed.
+4. Print an \`ORCHESTRATION COMPLETE\` block with the plan path, verification commands, artifacts, and cleanup receipts.`;
+
+const startWorkCodexCompletion = `When all top-level checkboxes in \`## TODOs\` and \`## Final Verification Wave\` are complete:
+
+1. Run the plan's final verification commands.
+2. Complete the **Global Review and Debugging Gate** before any completion claim, PR handoff, or branch handoff:
+   - Invoke the \`review-work\` skill with the final diff, changed files, user goal, constraints, run command, and verification evidence. All five review lanes must return PASS. A timeout, missing deliverable, ack-only child, \`BLOCKED:\`, or inconclusive lane is a gate failure, not approval.
+   - Run a debugging-oriented runtime audit even when the review passes: name at least three plausible failure hypotheses for the changed surface, run the distinguishing checks against the actual artifact, and append the ruled-out or confirmed result to \`.omo/start-work/ledger.jsonl\`.
+   - If any review lane or debugging hypothesis fails, invoke the \`debugging\` skill, confirm root cause with runtime evidence, add the minimal failing test or reproduction, fix it, rerun the affected verification, then rerun the Global Review and Debugging Gate.
+   - Evidence hygiene is mandatory: redact or mask secrets and sensitive user data before writing \`.omo/start-work/ledger.jsonl\`, a PR body, or a handoff. Never include raw tokens, credentials, auth headers, cookies, API keys, env dumps, private logs, or PII; use concise summaries, lengths, hashes, or short non-sensitive prefixes instead.
+   - If the work includes creating, updating, or handing off a PR, refresh \`git status\` and the PR/branch state after the gate, and include only redacted review/debugging evidence in the PR body or handoff.
+3. If worktree mode was used, sync \`.omo/\` state back to the main repo, merge or hand off exactly as requested, and remove the worktree only after successful merge or explicit handoff.
+4. Remove or mark the Boulder work as completed.
+5. Print an \`ORCHESTRATION COMPLETE\` block with the plan path, verification commands, Global Review and Debugging Gate verdict, artifacts, and cleanup receipts.`;
+
+const startWorkOriginalHardRule = "- No completion claim while an applicable ultraqa adversarial class was never probed. Each applicable class needs a captured observable result; each skipped class needs a one-line not-applicable reason in the ledger.\n- No unprefixed session ids in Boulder state. Codex sessions are always `codex:<session_id>`.";
+
+const startWorkCodexHardRule = "- No completion claim while an applicable ultraqa adversarial class was never probed. Each applicable class needs a captured observable result; each skipped class needs a one-line not-applicable reason in the ledger.\n- No `ORCHESTRATION COMPLETE`, final response, PR creation, or PR handoff before the Global Review and Debugging Gate passes with recorded evidence.\n- No unprefixed session ids in Boulder state. Codex sessions are always `codex:<session_id>`.";
+
+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 or handing off a PR\.\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 === "start-work") {
+		return content
+			.replace(startWorkCodexCompletion, startWorkOriginalCompletion)
+			.replace(startWorkCodexHardRule, startWorkOriginalHardRule);
+	}
+	if (skillName === "review-work") {
+		return content.replace(reviewWorkCodexGatePattern, "");
+	}
+	return content;
+}
+
+export async function listSkillFiles(dir) {
+	const entries = await readdir(dir, { withFileTypes: true });
+	const files = [];
+	for (const entry of entries) {
+		if (entry.isDirectory()) {
+			const nested = await listSkillFiles(join(dir, entry.name));
+			for (const nestedPath of nested) files.push(join(entry.name, nestedPath));
+		} else {
+			files.push(entry.name);
+		}
+	}
+	return files.sort();
+}
+
+export function assertPackagedContentMatches({ path, content }, requirements) {
+	for (const [label, pattern] of requirements) {
+		assert.match(content, pattern, `${path} missing packaged skill contract: ${label}`);
+	}
+}