oh-my-opencode 4.5.1 → 4.5.12

package/packages/omo-codex/plugin/package.json

@@ -0,0 +1,26 @@
+{
+	"name": "@sisyphuslabs/omo-codex-plugin",
+	"version": "0.1.0",
+	"description": "Aggregate Codex plugin root for OMO components.",
+	"type": "module",
+	"packageManager": "npm@11.12.1",
+	"private": true,
+	"workspaces": [
+		"components/comment-checker",
+		"components/rules",
+		"components/lsp",
+		"components/telemetry",
+		"components/start-work-continuation",
+		"components/ulw-loop",
+		"components/ultrawork"
+	],
+	"dependencies": {
+		"@oh-my-opencode/shared-skills": "file:../../shared-skills"
+	},
+	"scripts": {
+		"build": "node scripts/build-bundled-mcp-runtimes.mjs && node scripts/sync-skills.mjs && node ../scripts/sync-telemetry-component.mjs && node scripts/build-components.mjs",
+		"check": "npm run build && npm test",
+		"sync:skills": "node scripts/sync-skills.mjs",
+		"test": "node --test test/*.test.mjs"
+	}
+}

package/packages/omo-codex/plugin/scripts/build-bundled-mcp-runtimes.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const pluginRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const repoPackagesRoot = join(pluginRoot, "..", "..");
+
+const runtimes = [
+	{
+		label: "lsp-tools-mcp",
+		packageRoot: join(repoPackagesRoot, "lsp-tools-mcp"),
+		requiredOutputs: ["dist/cli.js", "dist/tools.js"],
+	},
+	{
+		label: "ast-grep-mcp",
+		packageRoot: join(repoPackagesRoot, "ast-grep-mcp"),
+		requiredOutputs: ["dist/cli.js"],
+	},
+];
+
+for (const runtime of runtimes) {
+	buildRuntime(runtime);
+}
+
+function buildRuntime(runtime) {
+	if (!existsSync(join(runtime.packageRoot, "package.json"))) {
+		assertBundledDist(runtime);
+		console.log(`Using bundled ${runtime.label} dist`);
+		return;
+	}
+
+	const result = spawnSync("bun", ["run", "build"], {
+		cwd: runtime.packageRoot,
+		stdio: "inherit",
+	});
+	if (result.error !== undefined) throw result.error;
+	if (result.status !== 0) process.exit(result.status ?? 1);
+}
+
+function assertBundledDist(runtime) {
+	const missingOutputs = runtime.requiredOutputs.filter((output) => !existsSync(join(runtime.packageRoot, output)));
+	if (missingOutputs.length === 0) return;
+	console.error(`Missing bundled ${runtime.label} outputs:`);
+	for (const output of missingOutputs) {
+		console.error(`  ${join(runtime.packageRoot, output)}`);
+	}
+	process.exit(1);
+}

package/packages/omo-codex/plugin/scripts/build-components.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const packageJson = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+const workspaces = Array.isArray(packageJson.workspaces) ? packageJson.workspaces : [];
+
+for (const workspace of workspaces) {
+	if (typeof workspace !== "string" || !workspace.startsWith("components/")) continue;
+	const workspacePackageJson = JSON.parse(await readFile(join(root, workspace, "package.json"), "utf8"));
+	if (typeof workspacePackageJson.scripts?.build !== "string") continue;
+
+	console.log(`Building ${workspace}`);
+	const result = spawnSync("bun", ["run", "--cwd", workspace, "build"], {
+		cwd: root,
+		stdio: "inherit",
+	});
+	if (result.error !== undefined) throw result.error;
+	if (result.status !== 0) process.exit(result.status ?? 1);
+}

package/packages/omo-codex/plugin/scripts/hook-status-message.mjs

@@ -0,0 +1,46 @@
+const PRODUCT_NAME = "LazyCodex";
+
+const WORD_OVERRIDES = new Map([
+	["lsp", "LSP"],
+	["ulw-loop", "Ulw-Loop"],
+]);
+
+export function formatLazyCodexHookStatusMessage(version, label) {
+	return `${PRODUCT_NAME}(${normalizeVersion(version)}): ${normalizeLazyCodexHookStatusLabel(label)}`;
+}
+
+export function normalizeLazyCodexHookStatusLabel(label) {
+	const parsed = parseLazyCodexHookStatusMessage(label);
+	const rawLabel = parsed === null ? label : parsed.label;
+	const normalized = rawLabel.replace(/\bOMO\b/gi, " ").replace(/\s+/g, " ").trim();
+	if (normalized.length === 0) return "";
+	return normalized
+		.split(" ")
+		.map(formatWord)
+		.join(" ");
+}
+
+export function parseLazyCodexHookStatusMessage(message) {
+	const match = /^LazyCodex\(([^)]+)\):\s+(.+)$/.exec(message.trim());
+	if (match === null) return null;
+	const [, version, label] = match;
+	return { version, label };
+}
+
+function normalizeVersion(version) {
+	const normalized = version.trim();
+	return normalized.length === 0 ? "local" : normalized;
+}
+
+function formatWord(word) {
+	const lower = word.toLowerCase();
+	const override = WORD_OVERRIDES.get(lower);
+	if (override !== undefined) return override;
+	if (word.includes("-")) {
+		return word
+			.split("-")
+			.map(formatWord)
+			.join("-");
+	}
+	return `${lower.slice(0, 1).toUpperCase()}${lower.slice(1)}`;
+}

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

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import { cp, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { sharedSkillsRootPath } from "@oh-my-opencode/shared-skills";
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const sharedSkillsRoot = sharedSkillsRootPath();
+const skillsRoot = join(root, "skills");
+const skillSources = [
+	["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"],
+];
+
+const opencodeOnlyOrchestrationPattern = /\b(?:call_omo_agent|background_output|team_[a-z_]+|task)\s*\(/;
+
+const codexHarnessToolCompatibility = `## 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(agent_type="explorer", task_name="...", message="...")\` |
+| \`call_omo_agent(subagent_type="librarian", ...)\` | \`spawn_agent(agent_type="librarian", task_name="...", message="...")\` |
+| \`task(subagent_type="plan", ...)\` | \`spawn_agent(agent_type="plan", task_name="...", message="...")\` |
+| \`task(subagent_type="oracle", ...)\` for final verification | \`spawn_agent(agent_type="codex-ultrawork-reviewer", task_name="...", message="...")\` |
+| \`task(category="...", ...)\` for implementation or QA | \`spawn_agent(agent_type="worker", task_name="...", message="...")\` |
+| \`background_output(task_id="...")\` | \`wait_agent(...)\` to wait for subagent completion and mailbox updates |
+| \`team_*(...)\` | Use Codex native subagents plus \`send_message\`, \`followup_task\`, \`wait_agent\`, and \`close_agent\` |
+
+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.
+
+`;
+
+function insertCodexCompatibilityGuidance(content) {
+	if (!opencodeOnlyOrchestrationPattern.test(content)) return content;
+	if (content.includes("## Codex Harness Tool Compatibility")) return content;
+
+	const frontmatterMatch = content.match(/^---\n[\s\S]*?\n---\n+/);
+	if (!frontmatterMatch) {
+		return `${codexHarnessToolCompatibility}${content}`;
+	}
+
+	return `${frontmatterMatch[0]}${codexHarnessToolCompatibility}${content.slice(frontmatterMatch[0].length)}`;
+}
+
+async function adaptSkillForCodex(skillName) {
+	const skillPath = join(skillsRoot, skillName, "SKILL.md");
+	const content = await readFile(skillPath, "utf8");
+	const adapted = insertCodexCompatibilityGuidance(content);
+	if (adapted !== content) {
+		await writeFile(skillPath, adapted, "utf8");
+	}
+}
+
+await rm(skillsRoot, { recursive: true, force: true });
+await mkdir(skillsRoot, { recursive: true });
+
+for (const [name, source] of skillSources) {
+	await cp(join(root, source), join(skillsRoot, name), { recursive: true });
+	await adaptSkillForCodex(name);
+}
+
+const sharedSkillEntries = await readdir(sharedSkillsRoot, { withFileTypes: true });
+const sharedSkillNames = sharedSkillEntries
+	.filter((entry) => entry.isDirectory())
+	.map((entry) => entry.name)
+	.sort();
+
+for (const skillName of sharedSkillNames) {
+	await cp(join(sharedSkillsRoot, skillName), join(skillsRoot, skillName), { recursive: true });
+	await adaptSkillForCodex(skillName);
+}

package/packages/omo-codex/plugin/skills/comment-checker/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: comment-checker
+description: Use when Codex needs to understand or respond to automatic comment-checker feedback emitted after an edit-like PostToolUse hook.
+---
+
+# Codex Comment Checker
+
+The plugin registers a `PostToolUse` hook for successful `apply_patch`, `write`, `edit`, `multi_edit`, and `multiedit` calls.
+
+When comment-checker reports a warning after a patch, Codex receives blocking feedback and should fix or explain the flagged comment before moving on.
+
+## Scope
+
+- No MCP tool is exposed.
+- Non-edit tools are ignored by this plugin.
+- Missing checker binaries emit no hook output so normal Codex work can continue.

package/packages/omo-codex/plugin/skills/debugging/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: debugging
+description: "MUST USE for any real runtime debugging across ANY language or binary — crashes, silent failures, wrong responses, stuck processes, memory leaks, async misbehavior, unexplained timing, reverse engineering. Runs a hypothesis-driven loop: form ≥3 hypotheses, investigate in parallel, after 2 failed rounds spawn Oracles from orthogonal angles, confirm root cause, lock with a failing test, fix minimally, QA by actually USING the system, scrub artifacts. The actual HOW lives in `references/` — READ THEM. Triggers: 'debug this', 'why is X not working', 'hanging', 'attach a debugger', 'reverse engineer', 'pwndbg', 'gdb', 'lldb', 'node inspect', 'tsx debug', 'pdb', 'dlv', 'delve', 'rust-gdb', 'set a breakpoint', 'context window exploded', 'why is the response empty', 'attach the debugger', 'debug it', 'why is this happening', 'trace this bug', 'reproduce and fix', 'silent failure', 'HTTP 200 but empty', 'why did it stop', 'inspect the binary', 'reverse engineering', 'playwright'."
+---
+
+# Debugging
+
+You are a hypothesis-driven debugger. Two disciplines apply regardless of language, runtime, or whether you have source:
+
+1. **Runtime truth beats code reading.** Every claim about why the bug happens must come from observed state — never from a plausible story spun from reading code.
+2. **Leave no trace.** Debugging creates artifacts. Every artifact is journaled and removed before you call the task done.
+
+The rest of this file is a map. **The knowledge is in `references/`.** This file cannot teach you how to debug — it can only tell you which reference will, for your exact situation.
+
+---
+
+# 🚨 READ THE REFERENCES. THIS IS NOT OPTIONAL.
+
+> **This skill is intentionally small.** Ninety percent of what you need to know lives in `references/`. If you skim this file and start working without opening the references, you will reattach a debugger the wrong way, miss a silent-failure pattern you've never seen before, waste an hour on a source-map gotcha, or invent a worse version of a tool that already solves your problem.
+>
+> **Every reference below is mandatory when its scenario applies.** "I know this language" is not an exemption. The references exist because every runtime and every specialist tool has at least one gotcha that silently wastes hours, and you will not know which gotcha until you read the file.
+>
+> **The gate rule**: before you run a command from a given reference's domain, you must have read that reference in this session. Re-reading across sessions is cheap. Guessing is expensive.
+
+---
+
+## Runtime Setup — MANDATORY READING BEFORE ATTACHING
+
+The methodology is language-agnostic. The commands to launch, attach, breakpoint, and inspect are not. **Open the matching reference before Phase 0. Not during. Not after.**
+
+| Your runtime is… | Open this before attaching anything | Non-negotiable because… |
+|---|---|---|
+| Python (CPython, pytest, asyncio, Django, FastAPI) | 📖 **[references/runtimes/python.md](references/runtimes/python.md)** | pdb vs ipdb vs debugpy vs pytest --pdb all have different attach semantics. Async code needs special breakpoint handling. Wrappers like `poetry run` swallow flags. |
+| Node.js / tsx / ts-node / Bun / Deno (running source) | 📖 **[references/runtimes/node.md](references/runtimes/node.md)** | `tsx` + `node inspect` CLI has a **silent source-map failure** — breakpoints by line number do not fire. You will not notice unless you read this first. |
+| Rust (cargo, tokio, panics) | 📖 **[references/runtimes/rust.md](references/runtimes/rust.md)** | Release builds strip symbols. Tokio tasks need `tokio-console`. The borrow checker makes `dbg!` the faster tool most of the time. |
+| Go (goroutines, dlv, pprof, race) | 📖 **[references/runtimes/go.md](references/runtimes/go.md)** | Goroutine leaks and recovered panics are silent by default. `dlv` has a specific port convention. `go test -race` is the first thing to run, not the last. |
+| Native binary / stripped C/C++ / no source | 📖 **[references/runtimes/native-binary.md](references/runtimes/native-binary.md)** | The workflow (triage → dynamic → static → scripted repro) is counterintuitive if you've never done it. `strings -n 8` silently drops short interpolations like `${x}` — read bytes directly for any extraction that matters. macOS adds SIP / Mach-O / lldb specifics that don't apply on Linux. |
+| **Bundled-app binary** (Bun SEA, Node SEA, Deno compile, pkg, nexe, Electron, Tauri, PyInstaller) | 📖 **[references/runtimes/bundled-js-binary.md](references/runtimes/bundled-js-binary.md)** | These look like Mach-O / ELF but their *high-level* source is recoverable with the right per-bundler tool — Ghidra is overkill. Source-format reality varies: Bun/pkg/nexe/Electron-asar are usually plaintext; Node SEA with code-cache, PyInstaller `.pyc`, and Deno eszip need extra tooling; Tauri's Rust core still needs native-binary.md. Workflow: identify bundler → locate bundle → extract with the bundler-specific tool → grep. |
+
+**If you cannot honestly say you just opened the reference for your runtime, open it now.**
+
+> 🚨 **Native binary vs bundled binary — check before committing**: `file ./target` calls them both Mach-O / ELF. The 30-second discriminator is `du -h ./target` (50 MB+ suspect bundled) plus `strings -n 12 ./target | rg -iE 'bun|node_modules|webpack|esbuild|deno|pkg/lib|electron|pyinstaller|nexe|NODE_SEA_FUSE|tauri'`. If hits → bundled-js-binary.md. If clean → native-binary.md.
+
+---
+
+## Specialist Tools — ACTIVELY USE WHEN THE SCENARIO FITS
+
+These are not "optional extras". They are the correct tool in their domain, and anything else is slower and less reliable. **If the bug fits the domain, you MUST use the tool. Read the reference first to know how.**
+
+| Tool | Use when | Reference |
+|---|---|---|
+| **Playwright CLI** | Any browser-served web UI bug. Any flow that requires clicking/typing/navigating. Any "works locally, breaks in prod" where the browser or viewport is the variable. **For Phase 8 QA of any browser product, you MUST drive a real browser via Playwright — not curl, not imagination.** | 📖 **[references/tools/playwright-cli.md](references/tools/playwright-cli.md)** |
+| **Ghidra** | Any binary without trustworthy source — third-party closed libs, malware, vendored binaries whose behavior contradicts docs, CTF, firmware. **Use Ghidra's decompiler before `strings`/`objdump` guessing. It turns machine code into readable C.** | 📖 **[references/tools/ghidra.md](references/tools/ghidra.md)** |
+| **pwndbg** | Any native binary debugging session. It is GDB with the useful views (registers, stack, disasm, heap) always visible. **If you'd reach for plain `gdb`, reach for `pwndbg` instead — it is strictly a superset.** | 📖 **[references/tools/pwndbg.md](references/tools/pwndbg.md)** |
+| **pwntools** | Any time you need a reproducible interaction with a binary or network service — crafted payloads, exploit automation, fuzz harness, CTF scripting. | 📖 **[references/tools/pwntools.md](references/tools/pwntools.md)** |
+
+**Failing to use these tools in their domain is a process failure, not a stylistic choice.** If the bug is in a browser and you did Phase 8 without Playwright, you are doing it wrong. If the bug is in a stripped binary and you read hex with `xxd`, you are doing it wrong. The references tell you how. Read them.
+
+---
+
+## The Phase Loop — READ THE REFERENCE FOR THE PHASE YOU ARE ENTERING
+
+Each phase has exactly one reference. Read it as you enter the phase — not in advance, not from memory. The references are self-contained and short.
+
+| # | Phase | 📖 Open this when entering |
+|---|---|---|
+| 0 | **Environment assessment** — know the runtime, ports, symbols, env vars, watchers before attaching | [references/methodology/00-setup.md](references/methodology/00-setup.md) |
+| 1 | **Journal setup** — single `.debug-journal.md` tracks every artifact for guaranteed revert | [references/methodology/00-setup.md](references/methodology/00-setup.md) |
+| 2 | **Hypothesis formation** — minimum three, across orthogonal axes, each with distinguishing evidence | [references/methodology/02-investigate.md](references/methodology/02-investigate.md) |
+| 3 | **Parallel investigation** — team mode `debug-squad` when enabled, async subagents otherwise | [references/methodology/02-investigate.md](references/methodology/02-investigate.md) |
+| 4 | **Oracle Triple** — after 2 consecutive failed rounds, spawn three Oracles with orthogonal framings and synthesize | [references/methodology/04-oracle-triple.md](references/methodology/04-oracle-triple.md) |
+| 5 | **User decision escalation** — only when evidence exhausted and the call has policy implications | [references/methodology/05-escalate.md](references/methodology/05-escalate.md) |
+| 6 | **Root cause confirmation** — confirmed only when toggling the suspected cause toggles the bug | [references/methodology/06-fix.md](references/methodology/06-fix.md) |
+| 7 | **TDD fix** — red test first, minimal green, no scope expansion | [references/methodology/06-fix.md](references/methodology/06-fix.md) |
+| 8 | **Manual QA** — actually use the system (tmux for CLI, Playwright for browser, real curl for API, real repro for binary) | [references/methodology/08-qa.md](references/methodology/08-qa.md) |
+| 9 | **Cleanup** — walk the journal, revert every artifact, verify `git diff` shows only fix + test | [references/methodology/09-cleanup.md](references/methodology/09-cleanup.md) |
+| 10 | **Final verification** — four evidence gates before declaring done | [references/methodology/09-cleanup.md](references/methodology/09-cleanup.md) |
+
+**Phase references are short by design.** Reading one takes a minute. Skipping one costs an hour.
+
+### Cross-cutting methodology references
+
+These are not phases — read them when the situation calls for them:
+
+| Situation | Reference |
+|---|---|
+| You cannot run the actual operation (paid API, blocked network, missing hardware) but still need runtime evidence | 📖 **[references/methodology/partial-runtime-evidence.md](references/methodology/partial-runtime-evidence.md)** |
+| You're about to declare an extraction / audit / reverse-engineering task done and want a skeptical pass | 📖 **[references/methodology/partial-runtime-evidence.md#verification-oracle-pattern-for-non-debug-tasks](references/methodology/partial-runtime-evidence.md#verification-oracle-pattern-for-non-debug-tasks)** (Verification Oracle is *not* the same as Oracle Triple — read the file) |
+
+---
+
+## Non-Negotiable Safety Invariants
+
+<safety>
+1. **Runtime state is the only source of truth.** A hypothesis without an observed value is a guess. Do not fix guesses.
+2. **Every debug artifact is journaled before it is created.** Journal-then-modify, not modify-then-remember-maybe.
+3. **Never ship a fix without a failing-first test.** Red→green transition required, or the fix is unverified.
+4. **Never declare done on type-check/compile alone.** Types catch declaration bugs. Only running the actual user scenario catches the actual user bug.
+5. **Never ask the user a question that runtime evidence can already answer.** Escalation is for genuine ambiguity.
+6. **Never silently swallow errors while debugging.** If the system swallows errors, that is often the bug itself. Make them loud temporarily; restore at cleanup.
+7. **Never `git commit` from inside this skill.** Commits belong to `/git-master` after the user confirms the fix.
+8. **Never attach without having read the runtime reference.** The gate rule.
+</safety>
+
+---
+
+## What to Do Right Now
+
+1. Read the user's bug description.
+2. Identify the runtime.
+3. **Open `references/runtimes/<runtime>.md`.** Read it.
+4. Identify which specialist tools apply. **Open each matching `references/tools/*.md`.** Read them.
+5. Open `references/methodology/00-setup.md` and start Phase 0.
+6. Follow the phase loop. Read each methodology reference as you enter the phase.
+
+**The references are the skill. This file is an index.**

package/packages/omo-codex/plugin/skills/debugging/references/methodology/00-setup.md

@@ -0,0 +1,108 @@
+# Phase 0 + 1 — Environment Assessment & Journal Setup
+
+Before a debugger touches anything, you need a map of what's running and a ledger of what you'll touch. Skipping either phase is how debug sessions turn into "why is my repo dirty a week later" sessions.
+
+---
+
+## Phase 0 — Environment Assessment
+
+Map the ground truth before you attach. Attaching the wrong way wastes the first hour.
+
+### 1. Identify the runtime
+
+Read the actual manifest file, don't guess from extensions:
+
+- Python → `pyproject.toml`, `requirements*.txt`, `setup.py`, `uv.lock`, `.python-version`
+- Node → `package.json` (check `scripts`, check `engines`, check `type: module`)
+- Rust → `Cargo.toml`, `rust-toolchain*`
+- Go → `go.mod`, `go.sum`
+- Native / mixed → `Makefile`, `CMakeLists.txt`, the binary itself (`file <path>`)
+
+### 2. Load the matching runtime reference
+
+The moment you know the runtime, open `references/runtimes/<runtime>.md`. The commands in this phase (and every phase after) are runtime-specific. The shape of the answers is the same; the commands are not.
+
+### 3. Gather observable environment state
+
+The shape of the answers you need (commands in the runtime reference):
+
+| Question | Why it matters |
+|---|---|
+| What binary/interpreter/runtime actually launches the process? | Determines debugger flag plumbing. Wrappers (`tsx`, `poetry run`, `cargo run`, `bun`, supervisor scripts) change how flags propagate. |
+| Is there already a debug-relevant port in use, or another instance of the service running? | Either attach to it or kill it deliberately — never silently compete. |
+| Are symbols / source maps / debug info present and correct? | This determines whether breakpoints land on the right lines. Compiled-but-not-debug builds, stripped binaries, and incomplete source maps all silently misplace breakpoints. |
+| Does the code path require env vars, config files, or auth tokens to reach the bug? | Missing env often produces early-return paths that masquerade as the bug itself. |
+| Is there an existing failing test or known repro? | Prefer amplifying an existing repro over inventing one. |
+| Are watchers (file watchers, hot reloaders, supervisors) going to restart the process mid-session? | If yes, turn them off before attaching. Restarts drop inspector connections and invalidate breakpoints. |
+
+### 4. Gate check
+
+If any answer is "I'm not sure", you are not ready for Phase 1. Investigate until certain. Guessing here cascades into false-positive hypotheses in Phase 2.
+
+---
+
+## Phase 1 — Journal Setup
+
+Open **one** journal file at the project root: `.debug-journal.md`. Single source of truth for every artifact this skill creates. The contract with the user that you can undo everything.
+
+### Exclude from git (don't pollute the committed ignore list)
+
+```bash
+grep -qx '.debug-journal.md' .git/info/exclude || echo '.debug-journal.md' >> .git/info/exclude
+```
+
+`.git/info/exclude` is per-clone and not committed — perfect for local-session artifacts.
+
+### Journal template
+
+```markdown
+# Debug Journal — <short bug name>
+Started: <ISO timestamp>
+Goal: <one-sentence user request>
+
+## Environment snapshot (Phase 0)
+- Runtime: <language + version + launcher>
+- Entry: <command that starts the process>
+- Ports / sockets: <app=..., debugger=..., etc>
+- Git HEAD: <sha>, working tree clean? <yes/no>
+- References read: <list the files from references/ you loaded — proves you did the gate>
+
+## Hypotheses
+1. [STATUS] <hypothesis> — distinguishing evidence: <what would confirm/refute> — if true, fix is: <two words>
+2. ...
+
+## Failed hypothesis round counter
+- Round 1: <result>
+- Round 2: <result>
+<!-- At 2 consecutive failures, invoke Oracle Triple (see 04-oracle-triple.md). -->
+
+## Artifacts to revert
+<!-- Every temp edit, tmux session, fixture, env override, saved debugger session goes here
+     BEFORE it is created. The rule is journal-then-modify. -->
+- [ ] `src/foo.py` — added `breakpoint()` on 2 lines. Revert: `git checkout src/foo.py`
+- [ ] tmux session `debug-server`. Kill: `tmux kill-session -t debug-server`
+- [ ] `/tmp/debug-payload.json`. Remove: `rm /tmp/debug-payload.json`
+- [ ] env var in current shell: `FOO_BASE_URL=...`. Unset when done.
+- [ ] GDB session save: `~/ghidra-projects/scratch.gzf`. Remove if not promoting.
+
+## Findings
+<!-- Append observed values here with timestamp. Verbatim only, no paraphrasing. -->
+
+## Oracle Triple (if invoked)
+<!-- One subsection per Oracle round, with the synthesized new hypothesis set. -->
+
+## Final fix
+<!-- File paths + test path. Filled during Phase 7. -->
+```
+
+### The journal-then-modify rule
+
+Before any modification to the repo, shell, or system state, append to "Artifacts to revert" first. This one discipline is what prevents debug sessions from becoming git cleanup sessions.
+
+If you catch yourself about to run a command that creates a file, opens a port, or modifies source — stop, journal the intended artifact with its revert command, then run the command. Not the other way around.
+
+### Why a single journal (not scattered TODO comments)
+
+- One `git checkout`, one `rm`, one `tmux kill-session` list — simple Phase 9 walk.
+- Survives interruptions. If you get pulled away mid-session, the next agent (or you later) can continue or revert without guessing.
+- Prevents the most common failure: leaving `console.log`/`print()`/`dbg!` scattered across the tree.

package/packages/omo-codex/plugin/skills/debugging/references/methodology/02-investigate.md

@@ -0,0 +1,130 @@
+# Phase 2 + 3 — Hypothesis Formation & Parallel Investigation
+
+One hypothesis is a hunch. Three hypotheses is a decision. Investigation is how you turn the decision into runtime evidence.
+
+---
+
+## Phase 2 — Hypothesis Formation (Minimum Three)
+
+### Why three, not one
+
+A single hypothesis creates confirmation bias: you'll read runtime state looking for evidence that confirms it and unconsciously discount contradictions. Three hypotheses force you to design queries that *distinguish* between them, which is the only way runtime evidence becomes decisive.
+
+### Generate across orthogonal axes
+
+If your three hypotheses are all variations of "the handler has a bug", you don't actually have three hypotheses. Span the space:
+
+| Axis | Example framing |
+|---|---|
+| **User-code logic** | "The handler early-returns because condition X is unexpectedly true" |
+| **Library/SDK behavior** | "The third-party client swallows the error and returns a stub" |
+| **Environment/config** | "The env var is read at module-load time before it gets populated, so it's empty" |
+| **Async/timing** | "The promise rejects (or goroutine panics) after the response is already sent" |
+| **Silent side-effect** | "An earlier turn mutated shared state that the current turn inherits" |
+| **Observability gap** | "The error is raised but suppressed before logging; it only exists as an unawaited rejection / ignored signal" |
+| **Binary-level** (when applicable) | "The function we think is running is actually jumped over by a patched thunk / a different version loaded" |
+| **Build-vs-runtime** | "The code we're reading is not the code that's running — stale build, wrong symlink, cached wheel, or dist/ ahead of src/" |
+
+### For each hypothesis, write in the journal
+
+1. **Claim** — one sentence.
+2. **Distinguishing evidence** — the exact value or state that confirms or refutes it, AND where to read it (file:line, log source, breakpoint location, memory address).
+3. **If true, the fix is** — two words. Forces you to think through fix cost before committing to the hunt.
+
+### Collapse rule
+
+If two hypotheses have identical distinguishing evidence, they aren't actually different — collapse them and find a real alternative. If you can't come up with a third distinct hypothesis, you don't understand the system well enough yet. Go read a little more code before investigating.
+
+---
+
+## Phase 3 — Parallel Investigation
+
+Branch depending on what's available.
+
+### Path A: Team mode ENABLED
+
+When the `team_*` tools are present, create a **debug-squad** team and split investigation across members working on different evidence sources. This is the right default whenever you have ≥3 hypotheses and any of them would take >10 minutes to investigate single-threaded.
+
+**Team spec** — write to `~/.omo/teams/debug-squad/config.json`:
+
+```json
+{
+  "name": "debug-squad",
+  "lead": { "kind": "subagent_type", "subagent_type": "sisyphus" },
+  "members": [
+    {
+      "kind": "category",
+      "category": "deep",
+      "prompt": "You are the Runtime State Inspector. Your job: attach to the live process, hit breakpoints, read program state (variables, heap, goroutines, stack, registers depending on runtime), and report observed values verbatim. Never guess — if you don't see the value, say so. Report back via team_send_message with file:line / address references and captured values. Never edit source code. Never run git commands. If you need an instrumentation statement added (breakpoint(), debugger;, dbg!, etc.), ask the Lead first."
+    },
+    {
+      "kind": "category",
+      "category": "deep",
+      "prompt": "You are the Log Archaeologist. Your job: grep server logs, stderr streams, SDK-internal debug output (DEBUG env, RUST_LOG, GODEBUG, PYTHONASYNCIODEBUG), and correlate timestamps. Produce a timeline of events with latencies. Flag anything that looks like a silent catch, a swallowed rejection, a panic recovered-and-ignored, a success response that contains failure signals (HTTP 200 with empty body, stopReason=error, exit 0 with error-in-stdout). Never edit source code."
+    },
+    {
+      "kind": "category",
+      "category": "deep",
+      "prompt": "You are the Reproduction Engineer. Your job: build the smallest reliable repro — a curl command, a vitest/pytest/go test, a tmux script, a Playwright script for browser bugs, a pwntools script for binary targets. It must reproduce on first try and be copy-pasteable by the Lead. Document exact input, expected output, observed output. Save repro artifacts under /tmp/ and tell the Lead to journal them. If the bug is browser-based you MUST use Playwright CLI — do not simulate with curl."
+    },
+    {
+      "kind": "category",
+      "category": "deep",
+      "prompt": "You are the Trace Correlator. Your job: take findings from the other members and cross-link them. Build a causal chain from symptom to suspected cause. Identify missing evidence. Propose the next single most-decisive runtime query. Never edit source code; only reason across already-captured evidence. If hypotheses diverge sharply after correlation, tell the Lead immediately — that is the signal for the Oracle Triple."
+    }
+  ]
+}
+```
+
+**Assignment rule**: one hypothesis → one `team_task_create`. Give each hypothesis to the member whose evidence source is most likely to confirm or refute it. Broadcast the full hypothesis list once via `team_send_message(to="*")` so members know what the others are testing.
+
+**Lead responsibilities**:
+- Maintain the journal (members do not write to it).
+- Approve any source-code edits (including `debugger;` / `breakpoint()` / `dbg!` statements).
+- Synthesize member reports into updated hypothesis statuses.
+- Decide when to disband: `team_shutdown_request` → `team_approve_shutdown` → `team_delete`.
+
+**Team does NOT include Oracle** — Oracle is a hard-reject team member type. Oracle is used separately in Phase 4 (see `04-oracle-triple.md`).
+
+### Path B: Team mode DISABLED
+
+Fan out async explore/deep subagents instead. Same rule: one hypothesis per subagent.
+
+```
+task(subagent_type="explore", load_skills=[], run_in_background=true,
+     prompt="[CONTEXT: bug summary + which hypothesis you own + what state to look at]
+     Runtime state investigation for hypothesis 1: ...")
+task(subagent_type="explore", load_skills=[], run_in_background=true,
+     prompt="Log/timing investigation for hypothesis 2: ...")
+task(category="deep", load_skills=[], run_in_background=true,
+     prompt="Reproduction minimizer for hypothesis 3: ...")
+```
+
+End your response, wait for completion notifications, then synthesize.
+
+---
+
+## Evidence capture discipline (both paths)
+
+For every piece of runtime state captured, record in the journal:
+
+```markdown
+### <ISO timestamp> — <what you looked at>
+- Source: <file:line | log source | curl command | breakpoint address>
+- Value: `<verbatim>`
+- Interpretation: <one line — why this matters>
+- Refutes/Confirms: H<n>
+```
+
+**Verbatim values only. No paraphrasing.**
+
+- `messages.length=0` is evidence.
+- "messages seemed empty" is not evidence — it's a memory of an observation, and memory of observations is where debug sessions go to die.
+
+If you find yourself about to paraphrase, stop, go back, and copy the raw value.
+
+---
+
+## Round completion
+
+A "round" is complete when every hypothesis has either confirming or refuting evidence — or when you have exhausted the evidence sources available without a decisive result. If the round ends inconclusively, that counts as a failed round for the counter in the journal. See `04-oracle-triple.md` for what to do at 2 consecutive failed rounds.