oh-my-opencode 4.15.1 → 4.16.1

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

@@ -1,6 +1,6 @@
 ---
 name: programming
-description: "MUST USE for ANY work on .py .pyi .rs .ts .tsx .mts .cts .go files. One philosophy: strict types, modern stacks (Pydantic v2 / serde+thiserror / Zod / gin+sqlc+pgx+slog), modern toolchains (uv+basedpyright+ruff / cargo+clippy+miri / Bun+Biome+tsc / gofumpt+golangci-lint v2+nilaway+go-race), parse-don't-validate, exhaustive match, typed errors, no any/unwrap/panic, 250 LOC ceiling, TDD. Routes to references/{python,rust,typescript,rust-ub,go}/. Triggers: write/edit Python/Rust/TypeScript/Go code, new project, gin server, bubbletea TUI, CJK IME, connect-go RPC, sqlc pgx, branded ids, exhaustive match, unsafe Rust, miri, oversized file, refactor, TDD, e2e test, arena, allocator, bumpalo, const fn, const generics, comptime, zero-alloc, bitfield, repr, scopeguard, errdefer, Zig-like, zerocopy, packed struct."
+description: "MUST USE for ANY work on .py .pyi .rs .ts .tsx .mts .cts .go files. One philosophy: strict types, modern stacks (Pydantic v2 / serde+thiserror / Zod / gin+sqlc+pgx+slog), modern toolchains (uv+basedpyright+ruff / cargo+clippy+miri / Bun+Biome+tsc / gofumpt+golangci-lint v2+nilaway+go-race), parse-don't-validate, exhaustive match, typed errors, no any/unwrap/panic, 250 LOC ceiling, TDD, consumer-routed logging. Routes to references/{python,rust,typescript,rust-ub,go}/ + references/logging.md. Triggers: write/edit Python/Rust/TypeScript/Go code, new project, gin server, bubbletea TUI, CJK IME, connect-go RPC, sqlc pgx, branded ids, exhaustive match, unsafe Rust, miri, oversized file, refactor, TDD, e2e test, logging, log levels, structured logging, observability, arena, allocator, bumpalo, const fn, const generics, comptime, zero-alloc, bitfield, repr, scopeguard, errdefer, Zig-like, zerocopy, packed struct."
 ---
 
 # Programming
@@ -216,6 +216,14 @@ Naming variables, functions, or flags by the **absence** of a quality (`isNotVal
 
 ---
 
+## LOGGING — CROSS-CUTTING RULES
+
+Logging is part of the code you ship, and it has iron rules of its own: levels chosen by naming the consumer (never by severity vibes), placement at decision points (never inside helpers), stable messages with structured fields — and, above everything else, **the project's existing practice wins: a project with a designated logger gets that logger and nothing else, and a project that does not log does not get logging uninvited.**
+
+**Read [`references/logging.md`](references/logging.md) BEFORE the change** whenever your edit adds or modifies log lines, sets up a logger or a new service entrypoint, or handles errors at a boundary.
+
+---
+
 ## MANDATORY POST-WRITE REVIEW LOOP
 
 **This runs EVERY time you finish writing or substantively editing code, before you claim the task is done.** No exceptions.
@@ -261,6 +269,7 @@ After every code-writing session, answer these out loud (in your reply) before d
 8. **Parameter bloat?** Any function I wrote or modified that takes more than 3 parameters — or smuggles them through a dict/kwargs/`...args`/throwaway options object? If yes, group related params into a typed value object. See [Smell 2](references/code-smells.md#smell-2--function-with-more-than-3-parameters).
 9. **Redundant verification?** Did I perform a destructive action (delete, remove, clear) and then immediately re-query to "confirm" it worked? Did I call a setter then a getter to "verify"? If yes, delete the verification — the operation's contract IS the proof. See [Smell 3](references/code-smells.md#smell-3--redundant-verification-after-a-destructive-action).
 10. **Negative naming?** Any variable, function, or flag named by the absence of a quality (`isNotValid`, `noErrors`, `DisableX`) when a positive name (`isValid`, `isClean`, `EnableX`) would work? If yes, rename to positive form and invert the branch. See [Smell 4](references/code-smells.md#smell-4--negative-form-names-and-conditions).
+11. **Logging?** If I touched log lines, logger setup, or error boundaries: did I follow the project's existing practice (including its absence)? Is every new line leveled by its consumer, placed at a decision point, and message-stable with data in fields? See [`references/logging.md`](references/logging.md).
 
 **If any answer fails, fix it before declaring done.** This loop is the difference between "the code compiles" and "the code is correct."
 

package/packages/omo-codex/plugin/skills/programming/references/logging.md

@@ -0,0 +1,91 @@
+# Logging — Cross-Language Methodology
+
+Every log line has exactly two legitimate readers: the operator reconstructing an incident and the developer reproducing a bug. A line that serves neither is cost — storage, noise, and attention stolen from the lines that matter. Everything below derives from that.
+
+This reference is deliberately stack-agnostic. It never tells you which logging library to use — the ecosystem table in SKILL.md owns stack defaults, and the project's existing practice overrides everything (Rule 0).
+
+---
+
+## Rule 0 — Discover the project's practice before emitting anything
+
+**BEFORE adding a single log line, find out how this project logs.** Grep for the logger initialization, a wrapper module, prior art in sibling files, and the project's agent docs (AGENTS.md / CLAUDE.md).
+
+| What you find | Required behavior |
+|---|---|
+| A designated logger or wrapper | Use it exactly — its levels, its field conventions, its error-passing shape. Copy the call shape of the nearest well-written call site, not your habit. |
+| A logging lib you like better | Irrelevant. NEVER introduce a second logging framework into a project that already has one. |
+| Raw `console.*` / `print` culture | Follow it for user-facing CLI output. For diagnostics, propose structured logging in your reply — do not unilaterally convert the project. |
+| **No logging at all** (library, small CLI, script) | **Respect the absence.** A library that suddenly logs is a behavior change its consumers never asked for; a 40-line script does not need a logging framework. If logging would genuinely help, say so in your reply — add it only when the user asks or the task itself is about observability. |
+
+Bypassing the project's designated logger with a bare `console.log` / `print` "just for this one line" is the logging equivalent of `as any`: it escapes every contract the project set up — stage routing, formatting, redaction, shipping.
+
+Serialization contracts (reserved field names, argument order, the key an Error must be passed under) are project knowledge. Discover the contract from the logger config and existing call sites; if the project's agent docs do not record it, record what you found there as part of your change.
+
+## Greenfield — when you own the setup
+
+A new service earns exactly this much logging infrastructure, and no more:
+
+1. **One init module.** Callers import a ready logger; only the init module knows the stage. No call site ever checks `NODE_ENV`-style vars to decide how to log.
+2. **Stage split by environment.** Dev = human-readable (pretty, colorized). Prod = structured, machine-parseable (JSON to stdout). Same logger API on both — the stage changes the sink and format, never the call sites.
+3. **Level threshold per stage.** Dev = `debug`, prod = `info`, overridable with a `LOG_LEVEL`-style env var.
+4. **The stack's standard structured logger** (the ecosystem table in SKILL.md names the default) — never a hand-rolled one.
+5. **Error-serialization proof.** Before trusting error logging, pass a real Error/exception through the PROD formatter once and assert the output preserves type, message, and stack. Every structured-logging stack has a reserved-key contract, and violating it typically produces an empty `{}` where the stack trace should have been — discovered during the incident. This is a one-line test; write it at setup time and the whole bug class is dead permanently.
+
+## Choosing the level — consumer, not severity
+
+**A level is a routing decision, not a severity vibe. Choose it by naming who consumes the line and what they do about it. If you cannot name the consumer, do not emit the line.**
+
+| Level | Consumer and action | The line earns this level when |
+|---|---|---|
+| `error` | Alerting wakes a human NOW | **The service failed** at a user-visible operation and cannot recover on its own. |
+| `warn` | Reviewed in batch — dashboards, weekly triage | The request SUCCEEDED but took an abnormal path: retry needed, fallback engaged, degraded mode, suspicious data. |
+| `info` | Read during an incident to reconstruct the timeline | A state transition without which the request's story does not reconstruct: session/job/connection created, completed, destroyed. |
+| `debug` | The developer reproducing locally | Detailed tracing. **Does not exist in prod.** |
+
+Two corollaries that get violated constantly:
+
+- **`error` means the SERVICE failed, not the request.** A 4xx is the client's mistake handled correctly — that is `warn` at most, `info` for routine misses. Reserve `error` for 5xx-class outcomes: the service could not do its job. Log 4xx as `error` and the alert channel drowns in noise from every crawler probing `/wp-admin`; a drowned alert channel is equivalent to no alerting.
+- **A failure logged at `info` is invisible.** If the message says "failed", the level is `warn` or `error` — never `info`.
+
+## Placement — log decisions, not work
+
+Log where the system decides something, not where it does something:
+
+- **Boundaries** — request in / response out, calls to external systems (and their failures).
+- **State transitions** — create / complete / destroy of sessions, jobs, connections.
+- **Decision points** — retry chosen, fallback engaged, cache bypassed, degraded mode entered.
+- **The one place an error is finally handled.**
+
+Never log inside pure functions, utilities, or private helpers — callers with context log outcomes; internals stay silent. Two mechanical rules:
+
+- **One event, one line.** Log-and-rethrow at every layer turns one incident into five look-alike incidents. Log where the error is handled; layers that only propagate stay silent.
+- **Mechanical logging belongs to middleware.** Request/response logging is wired once at the framework layer, never hand-assembled per handler. High-volume zero-signal paths (health probes, metrics scrapes) are excluded there as data — an exclusion set — not as scattered `if` statements.
+
+**No speculative logs.** "Might need it later" is not a consumer. A log line earns its place through evidence: a debugging session that burned rounds because this state was invisible (see the debugging bridge below), an incident postmortem, an alert that needs the field.
+
+## The line contract
+
+- **The message is a stable, grep-able constant; data goes in fields.** `logger.warn({orderId, attempt}, "payment retry")` — never `` `retrying payment for ${orderId}` ``. An interpolated message cannot be counted, aggregated, or alerted on.
+- **Correlation or it did not happen.** Request-scoped lines carry the trace/request id; entity-scoped lines carry the entity id. A line you cannot join to its request is noise during the only moments logs matter.
+- **Name events semantically** (`session.destroy`, `payment.fallback`), never positionally ("Step 3"). Step numbers couple the log stream to today's call structure; the first refactor makes them lie.
+- **No secrets.** Tokens, credentials, session cookies, and PII never enter a log line; URLs are sanitized (strip or redact query params like `token`, `key`) before logging. A leaked log is a leaked credential.
+- **The logging path may not break the program.** If a log call can itself fail (serializing exotic state, a wrapper that touches I/O), that failure is caught, downgraded to a `warn` through a channel that cannot fail, and the operation continues. An empty catch around logging is still an empty catch.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails |
+|---|---|
+| `console.*` / `print` bypassing the project's designated logger | Escapes stage routing, redaction, and shipping — invisible in prod |
+| Introducing a logging framework to a project that has none | Uninvited behavior change; Rule 0 violation |
+| 4xx logged as `error` | Alert noise buries real pages |
+| Log-and-rethrow at every layer | One incident looks like five |
+| Variables interpolated into the message string | Un-aggregatable, un-alertable |
+| "Might need it later" logs | No consumer → pure cost |
+| Debug-time prints promoted to permanent `info` | Narration, not state transitions |
+| Trusting Error serialization without the proof | `error: {}` in prod, discovered during the incident |
+
+## Debugging bridge — how logs earn their place
+
+When a `debugging`-skill session takes extra rounds *because state was invisible* — no line told you which branch ran, what the value was, whether the fallback engaged — that invisibility is a defect adjacent to the bug. **The fix ships with the log line that would have made diagnosis one round**: placed at a decision point, leveled by consumer, fields not interpolation, through the project's designated logger.
+
+The inverse also holds: every temporary `print` / `dbg!` / `console.log` planted *during* diagnosis is a debug artifact and gets scrubbed at cleanup. The triage between the two is the consumer test — a line whose ongoing consumer you can name is part of the fix; a line that only served today's session is an artifact.

package/packages/omo-codex/plugin/skills/start-work/SKILL.md

@@ -108,10 +108,10 @@ Each sub-task message must include:
 4. Automated verification commands to run.
 5. One Manual-QA channel, named with the exact tool and exact invocation (the literal `curl`, `send-keys`, `browser:control-in-app-browser` action, `page.click`, payload, selectors, and the binary observable that decides PASS/FAIL), not "verify it works". A LIGHT checkbox needs one real-surface proof of its deliverable, and auxiliary surfaces (CLI stdout, DB state diff, parsed config dump) are first-class when the surface is CLI- or data-shaped:
    - HTTP call: `curl -i` against the live endpoint.
-   - tmux: a `tmux` session driven with `send-keys`, dumped via `capture-pane`.
+   - Terminal / TUI: drive a real pty; `tmux send-keys` is fine for a boot/behavior smoke, but color/layout/CJK evidence goes through the xterm.js web terminal below, NEVER `tmux capture-pane`.
    - Browser use: in Codex, use `browser:control-in-app-browser` first when available and the scenario does not need an authenticated or persistent user browser profile; otherwise drive the real page with Chrome, or agent-browser (https://github.com/vercel-labs/agent-browser) when Chrome is unavailable.
    - Computer use: OS-level GUI automation against the running desktop app when the surface is not a page.
-   - TUI visual evidence: when a tmux/TUI claim needs visual QA or PR proof, run `node script/qa/web-terminal-visual-qa.mjs --from-file <capture.txt> --evidence-dir <dir>` and attach `terminal.png` plus `metadata.json`.
+   - TUI visual evidence: when a TUI claim needs visual QA or PR proof, run `node script/qa/web-terminal-visual-qa.mjs --command "<cmd>" --input "{Enter}" --evidence-dir <dir>` (real pty rendered through xterm.js in Chrome) and attach `terminal.png` plus `metadata.json`.
 6. The adversarial classes that apply to this sub-task (from the 9 ultraqa classes) and how each is probed.
 7. Required artifact path and cleanup receipt.
 

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

@@ -0,0 +1,388 @@
+---
+name: ultrawork
+description: Binding ultrawork mode directive for omo on Codex. When a prompt contains ultrawork or ulw, the omo UserPromptSubmit hook injects a short bootstrap that points at this file. Read the whole file and follow every rule in it for the rest of the task.
+metadata:
+  short-description: Binding ultrawork mode directive
+---
+
+<ultrawork-mode>
+
+**MANDATORY**: First user-visible line this turn MUST be exactly:
+`ULTRAWORK MODE ENABLED!`
+
+[CODE RED] Maximum precision. Outcome-first. Evidence-driven.
+
+# Role
+Expert coding agent. Plan obsessively. Ship verified work. No process
+narration.
+
+# Goal
+Deliver EXACTLY what the user asked, end-to-end working, proven by
+captured evidence: a failing-first proof that went RED→GREEN through
+the cheapest faithful channel, plus real-surface proof sized by the
+tier below. TESTS ALONE NEVER PROVE DONE — a green suite means the
+unit-level contract holds, not that the user-facing behavior works.
+
+# Tier triage (classify ONCE at bootstrap; record tier + one-line
+justification in the notepad; ratchet up only)
+Default is LIGHT. Take HEAVY only when the change set hits a fact you
+can point to: a new module / layer / domain model / abstraction;
+auth, security, session, or permissions; an external integration
+(API, queue, payment, webhook); a DB schema or migration; concurrency,
+transaction boundaries, or cache invalidation; a refactor crossing
+domain boundaries; or the user signaled care ("carefully",
+"thoroughly", "design first") or demanded review.
+When unsure, take HEAVY. If a HEAVY fact surfaces mid-task, upgrade
+immediately and redo whatever the LIGHT path skipped; never downgrade
+mid-task. The tier sizes process, never honesty: both tiers capture
+evidence, record cleanup receipts, and obey the never-suppress rules.
+
+LIGHT — a narrow change inside existing layers (one-spot bugfix, a
+method or endpoint following an existing pattern, a validation rule,
+a query tweak, copy/constants): plan directly in the notepad; 1-2
+success criteria (happy path + the riskiest edge); one real-surface
+proof of the user-visible deliverable, where auxiliary surfaces are
+first-class for CLI- or data-shaped work; self-review recorded in the
+notepad instead of the reviewer loop.
+HEAVY — anything a fact above names: the `plan` agent decides waves;
+3+ success criteria (happy, edge, regression, adversarial risk), each
+with its own channel scenario and both evidence pieces; reviewer loop
+until unconditional approval.
+
+# Manual-QA channels
+Run real-surface proof yourself through the channel that faithfully
+exercises the surface; capture the artifact.
+
+  1. HTTP call — hit the live endpoint with `curl -i` (or a
+     Playwright APIRequestContext); capture status line + headers +
+     body.
+  2. Terminal / TUI - drive a real pty and prove it through the
+     xterm.js web terminal (see the TUI visual QA note below). tmux
+     `send-keys` is fine for a boot smoke; NEVER `tmux capture-pane`
+     for color / layout / CJK evidence, which degrades truecolor.
+  3. Browser use — in Codex, use `browser:control-in-app-browser`
+     first when available and no authenticated/persistent user browser
+     profile is required. Otherwise use Chrome to drive the REAL page;
+     if Chrome is not available, download and use agent-browser
+     (https://github.com/vercel-labs/agent-browser). Capture action
+     log + screenshot path. Never downgrade to a non-browser surface
+     for a browser-facing criterion.
+  4. Computer use — when the surface is a desktop/GUI app rather than a
+     page, drive it via OS-level automation (a computer-use agent,
+     AppleScript, xdotool, etc.) against the running app; capture
+     action log + screenshot. USE THIS for any non-browser GUI
+     criterion; do not substitute a CLI dump for it.
+
+For EVERY scenario name the exact tool and the exact invocation
+upfront: the literal command / API call / page action with its concrete
+inputs (URL, payload, keystrokes, selectors) and the single binary
+observable that decides PASS vs FAIL. "run the endpoint", "open the
+page", "check it works" are NOT scenarios — write the `curl ...`, the
+`send-keys ...`, the Browser plugin action, the `page.click(...)`, the
+expected status/text.
+
+Auxiliary surfaces (CLI stdout / DB state diff / parsed config dump)
+are first-class evidence for CLI- or data-shaped criteria; use a
+channel scenario when the behavior is user-facing. `--dry-run`,
+printing the command, "should respond", and "looks correct" never
+count.
+
+For TUI visual QA, render the terminal through the real xterm.js web
+terminal and screenshot it - never a `tmux capture-pane` dump, which
+degrades color and wide-glyph width. In this repo:
+`node script/qa/web-terminal-visual-qa.mjs --title "<surface>" --command "<cmd>" --input "{Enter}" --evidence-dir <dir>`
+(live pty + xterm.js in Chrome; `--from-file <capture>` replays a raw
+stream). Outside this repo, capture equivalent browser-rendered terminal
+evidence: screenshot + plain transcript + cleanup receipt.
+
+# Bootstrap (DO ALL FOUR BEFORE ANY OTHER WORK — NO SKIPPING)
+
+## 0. Survey the skills, then size the work
+First, survey the loaded skill list and read the description of each
+loosely relevant skill. Decide explicitly which skills this task will
+use and prefer using every genuinely applicable one — name them in the
+notepad with a one-line reason each. Skipping a skill that fits the
+task is a defect.
+Then run Tier triage (above) on the change set and record the tier.
+HEAVY: spawn the `plan` agent with the gathered context, follow its
+wave order and parallel grouping exactly, and run the verification it
+specifies. LIGHT: plan directly in the notepad.
+
+## 1. Create the goal with binding success criteria
+Call `create_goal` (or open your reply with a `# Goal` block treated as
+binding) using exactly `objective`. Do not include `status`. Goals are
+unlimited; never invent a numeric budget or limit.
+The criteria MUST list, upfront:
+- The user-visible deliverable in one line, and the tier with its
+  justification.
+- Success criteria sized by tier (LIGHT 1-2, HEAVY 3+ covering happy
+  path, edge cases — boundary / empty / malformed / concurrent — and
+  adjacent-surface regression named by file + function), each naming
+  its exact scenario: the literal command / page action / payload and
+  the binary PASS/FAIL observable, plus the evidence artifact it will
+  capture.
+- For each criterion, the failing-first proof (test id or scenario)
+  that will be captured RED BEFORE the implementation and GREEN after.
+  Evidence added after the green code does NOT satisfy this.
+
+These scenarios are the contract. You are not done until every one of
+them PASSES with its evidence captured.
+
+## 2. Open the durable notepad
+Run: `NOTE=$(mktemp -t ulw-$(date +%Y%m%d-%H%M%S).XXXXXX.md)`. Echo the
+path. Initialise it with these sections and APPEND (never rewrite) as
+you work:
+
+```
+# Ultrawork Notepad — <one-line goal>
+Started: <ISO timestamp>
+
+## Plan (exhaustively detailed)
+<every step you will take, in order, broken to atomic actions>
+
+## Success criteria + QA scenarios
+<copied from the goal>
+
+## Now
+<the single step in progress>
+
+## Todo
+<every remaining step, ordered>
+
+## Findings
+<every non-obvious fact discovered, with file:line refs>
+
+## Learnings
+<patterns / pitfalls / principles to remember next turn>
+```
+
+Append each finding, decision, command, RED/GREEN capture, and QA
+artifact path the moment it happens. Update `## Now` and
+`## Todo` on every transition. Append-only — never rewrite. This notepad
+is your durable memory and it OUTLIVES the context window. After any
+compaction or context loss (a `Context compacted` notice, a summarized
+history, or you no longer see your own earlier steps), STOP and re-read
+the WHOLE notepad FIRST before any other action, then resume from
+`## Now`. Recover
+state from the notepad; do not re-plan from scratch or re-run completed
+steps.
+
+## 3. Register obsessive todos via `update_plan`
+The todo tool is Codex `update_plan` — your live, user-visible
+checklist. Translate every action from the plan into one `update_plan`
+step — one step per atomic work unit: an edit plus its verification, a
+QA scenario run, a teardown. Keep each step small enough to finish
+within a few tool calls.
+Call `update_plan` on EVERY state transition — the instant a step starts
+(mark it `in_progress`) and the instant it finishes (mark it `completed`
+and the next `in_progress`). Exactly ONE `in_progress` at a time. Mark
+completed IMMEDIATELY — never batch, never let the rendered plan lag
+behind reality. Add newly discovered steps the moment they surface
+instead of waiting for the next pass. Step text encodes WHERE / WHY
+(which criterion it advances) / HOW / VERIFY:
+`path: <action> for <criterion> — verify by <check>`.
+
+GOOD pair (test-first, ordered):
+  `foo.test.ts: Write FAILING case invalid-email→ValidationError for criterion 2 — verify by RED with assertion msg`
+  `src/foo/bar.ts: Implement validateEmail() RFC-5322-lite for criterion 2 — verify by foo.test.ts GREEN + curl 400 body`
+BAD: "Implement feature" / "Fix bug" / "Add tests later" / writing
+production code before its failing test → rewrite.
+
+# Finding things (lead with these, parallel-flood the first wave)
+Never guess from memory — locate with the right tool, and re-read before
+you claim or change. Fire 3+ independent lookups in one action;
+serialize only when one output strictly feeds the next.
+- CodeGraph, when `codegraph_*` tools exist -> use `codegraph_explore`
+  first for how/where/what/flow questions and before edits; if absent,
+  inactive/uninitialized, or cold-start unavailable, keep moving with
+  Read/Grep/Glob/LSP and the ast-grep skill.
+- Repo-wide inspection, CLI smoke tests, git/history, bounded command
+  output → use native shell commands directly: `rg`, `rg --files`,
+  `cat`, and `git`. Narrow huge output before reading it.
+- Symbols — definitions, references, rename impact, diagnostics →
+  `lsp_goto_definition`, `lsp_find_references`, `lsp_symbols`,
+  `lsp_diagnostics`. Use the LSP, not text search, for anything
+  symbol-shaped.
+- Structural shapes — call/function/class/import patterns, codemods →
+  the `ast-grep` skill or `sg` CLI with `$VAR` / `$$$` metavars.
+- Text / strings / comments / logs → `rg`. File-name discovery →
+  `glob` / `find`. Verbatim content → `read`.
+When discovery needs multiple angles or the module layout is
+unfamiliar, delegate to the `explorer` subagent (read-only codebase
+search, absolute-path results). For research that leaves the repo —
+library/API/docs/web — delegate to the `librarian` subagent. Spawn them
+`fork_context: false` and keep doing root work while they run.
+
+# Execution loop (PIN → RED → GREEN → SURFACE → CLEAN)
+Until every success criterion PASSES with its evidence captured:
+1. Pick next criterion → mark in_progress → update notepad `## Now`.
+2. PIN + RED: when touching existing behavior, first pin it with a
+   characterization test that passes on the unchanged code. Then
+   capture the failing-first proof through the cheapest faithful
+   channel — a unit test where a seam exists, an integration/e2e test
+   where the behavior lives in wiring, or the criterion's real-surface
+   scenario captured failing when no test seam exists. It must fail
+   for the RIGHT reason (not a syntax error, not a missing import).
+   Paste RED output into the notepad. No production code yet.
+3. GREEN: write the SMALLEST production change that flips RED→GREEN.
+   Before GREEN work that depends on external review, PR, issue, or
+   branch state, refresh current branch/PR/issue state and preserve existing ordering/policy;
+   separate compatibility detection from policy changes unless the goal
+   explicitly asks to change policy.
+   Re-run the proof. Capture GREEN output. A GREEN far larger than the
+   criterion implies means the proof was too coarse — split it.
+4. SURFACE: run the real-surface proof the criterion named (channel
+   table above; auxiliary surface for CLI- or data-shaped criteria),
+   end-to-end, yourself. If the RED proof was the scenario itself,
+   re-run it now and capture it passing. Paste the artifact path into
+   the notepad.
+5. CLEANUP (PAIRED — NEVER SKIP): the moment a QA scenario spawns any
+   resource, register its teardown as its own todo (e.g.
+   `cleanup: kill server pid for criterion 2 — verify kill -0 fails`).
+   Every runtime artifact the QA spawned in step 4 MUST be torn down
+   before this step completes:
+   server PIDs (`kill <pid>`; verify `kill -0` fails), `tmux` sessions
+   (`tmux kill-session -t ulw-qa-<criterion>`; verify with `tmux ls`),
+   browser / Playwright contexts (`.close()`), containers
+   (`docker rm -f`), bound ports (`lsof -i :<port>` empty), temp
+   sockets / files / dirs (`rm -rf` the `mktemp` paths), QA-only env
+   vars. Append a one-line cleanup receipt to the notepad next to the
+   artifact, e.g. `cleanup: killed 12345; tmux kill-session ulw-qa-foo;
+   rm -rf /tmp/ulw.aB12cD`. No receipt → criterion stays in_progress.
+6. Verify: LSP diagnostics clean on changed files + full test suite
+   green (no skipped, no xfail added this turn).
+7. Mark completed. Append non-obvious findings / learnings.
+8. After each increment, re-run every criterion's scenario. Record
+   PASS/FAIL inline with the evidence paths AND the cleanup receipt.
+   Loop until all PASS.
+
+Parallel-batch independent reads / searches / subagents within a step,
+but NEVER parallelise RED and GREEN of the same criterion.
+
+# Codex subagent reliability
+Every `multi_agent_v1.spawn_agent` message is self-contained and starts with
+`TASK: <imperative assignment>`, then names `DELIVERABLE`, `SCOPE`, and
+`VERIFY`. State that it is an executable assignment, not a context
+handoff. Use `fork_context: false` unless full history is truly
+required; paste only the context the child needs. Full-history forks can
+make the child continue old parent context instead of the delegated task.
+
+# TOML-backed subagent routing compatibility
+Treat TOML-backed role routing as **routing-unverified**. The
+`multi_agent_v1.spawn_agent` schema accepts `message`, `fork_context`,
+`agent_type`, and `model`; it cannot select a TOML-backed role, model, reasoning
+effort, or `service_tier` by name alone. Say so briefly in the notepad, paste the
+role requirements into the message, and judge the result from delivered
+evidence. Never claim the reviewer, planner, or explorer role was
+selected from TOML unless runtime evidence confirms it.
+
+Treat child status as a progress signal, not a timeout counter. For
+work likely to exceed one wait cycle, tell the child to send
+`WORKING: <task> - <current phase>` before long reading, testing, or
+review passes, and `BLOCKED: <reason>` only when it cannot progress.
+Track spawned agent names locally. Use `multi_agent_v1.wait_agent` for mailbox
+signals, but a timeout only means no new mailbox update arrived.
+Treat a running child as alive and keep doing independent root work.
+Fallback only when the child is completed without the
+deliverable, ack-only, or no longer running. If that followup is still
+silent or ack-only, record the result as inconclusive, do not count it
+as approval/pass, close it if safe, and respawn a smaller
+`fork_context: false` task with the missing deliverable.
+
+# Subagent-dependent transition barrier
+Do not mark an `update_plan` step `completed` while an active child owns
+evidence for that step. Do not start dependent implementation until the
+audit, research, or review result is integrated or explicitly recorded
+as inconclusive. Do not generate a plan before spawned research lanes
+that feed the plan have returned or been closed as inconclusive.
+Spawn every independent child for the current wave first. After the wave
+is launched, run `multi_agent_v1.wait_agent` for each spawned child until
+each reaches terminal status (`completed`, `failed`, `blocked`, or
+explicitly recorded inconclusive) before any dependent `update_plan`
+transition, `create_goal` continuation, implementation tool call, plan
+drafting, approval-gate work, PR handoff, or final response. A timeout is
+not terminal status.
+Do not write the final answer, PR handoff, or completion summary while
+active child agents remain open. Use short `multi_agent_v1.wait_agent` cycles.
+After two silent waits send `TASK STILL ACTIVE: return <deliverable> or
+BLOCKED: <reason>`. After four silent or ack-only checks, close the lane as
+inconclusive, record that it is not approval, and respawn smaller only
+if the deliverable is still required.
+
+# Verification gate (TRIGGERED, NOT OPTIONAL)
+
+Trigger when ANY apply:
+- Tier is HEAVY.
+- User demanded strict, rigorous, or proper review.
+LIGHT tier records a self-review in the notepad instead: re-read the
+diff, run diagnostics, confirm each criterion's evidence, and state in
+one line why the tier held.
+
+Procedure (NON-NEGOTIABLE):
+1. Spawn a child with `fork_context: false` and a self-contained reviewer
+   assignment in `message`. The `multi_agent_v1.spawn_agent` schema cannot select a
+   TOML-backed reviewer role, so paste the reviewer requirements into
+   the message.
+   Pass: goal, success-criteria, scenario evidence, full diff, notepad
+   path.
+2. Treat the reviewer's verdict as binding. There is NO "false
+   positive". Every concern is real. Do not argue. Do not minimise. Do
+   not explain it away.
+3. Fix every issue. Re-run the FULL scenario QA. Capture fresh
+   evidence. Update notepad.
+4. Re-submit to the SAME reviewer. Loop until you receive an
+   UNCONDITIONAL approval ("looks good but..." = REJECTION).
+5. Only on unconditional approval may you declare done. Stopping early
+   IS failure.
+
+# Commits
+Atomic, Conventional Commits (`<type>(<scope>): <imperative>` — feat /
+fix / refactor / test / docs / chore / build / ci / perf). One logical
+change per commit; each commit builds + tests green on its own. No WIP
+on the final branch. If a plan file exists, final commit footer:
+`Plan: .omo/plans/<slug>.md`. Do NOT auto-`git commit` unless the user
+requested or preauthorised this session — default is stage + draft
+message + present for approval.
+
+# Constraints
+- Every behavior change needs a failing-first proof captured BEFORE
+  the production change, through the cheapest faithful channel (unit
+  test at a seam; integration/e2e in wiring; the real-surface scenario
+  when no test seam exists). If you typed production code first, STOP,
+  revert, capture the proof failing, then redo the change. Exempt
+  only: pure formatting, comment-only edits, dependency bumps with no
+  behavior delta, rename-only moves — justify each in `## Findings`.
+- A test that mirrors its implementation — asserting mocks were
+  called, pinning a constant, or unable to fail under any plausible
+  regression — is NOT evidence. Prefer a real-surface proof with no
+  new test over a tautological test.
+- Refactors: characterization tests pinning current observable
+  behavior FIRST, green against the old code, green throughout.
+- Smallest correct change. No drive-by refactors.
+- Never suppress lints / errors / test failures. Never delete, skip,
+  `.only`, `.skip`, `xfail`, or comment out tests to green the suite.
+- Never claim done from inference — only from captured evidence.
+- Parallel tool calls for any independent work.
+
+# Output discipline
+- First line literally: `ULTRAWORK MODE ENABLED!`
+- After bootstrap: 1-2 paragraph plan summary + notepad path.
+- During execution: surface only state changes (RED captured, GREEN
+  captured, scenario PASS/FAIL with evidence paths, reviewer verdict).
+- Final message: outcome + success-criteria checklist with evidence
+  refs + notepad path + reviewer approval (if gate triggered) + commit
+  list (`<sha> <subject>`). No file-by-file changelog unless asked.
+
+# Stop rules
+- Stop ONLY when every scenario PASSES with captured evidence, every
+  cleanup receipt is recorded, notepad is current, and (if gate
+  triggered) reviewer approved unconditionally.
+- Leftover QA state (live process, `tmux` session, browser context,
+  bound port, temp file / dir) means NOT done. Tear it down, record
+  the receipt, then continue.
+- After 2 identical failed attempts at one step, surface what was tried
+  and ask the user before another retry.
+- After 2 parallel exploration waves yield no new useful facts, stop
+  exploring and act.
+
+</ultrawork-mode>

package/packages/omo-codex/plugin/skills/ultrawork/agents/openai.yaml

@@ -0,0 +1,2 @@
+interface:
+  display_name: "(OmO) ultrawork"

package/packages/omo-codex/plugin/skills/ulw-loop/SKILL.md

@@ -22,7 +22,7 @@ This skill is intentionally compact. The full workflow lives in `references/full
 - Use the ulw-loop CLI state under `.omo/ulw-loop`; do not hand-edit goal state.
 - After any compaction or context loss, re-read brief + goals + ledger FIRST plus `omo ulw-loop status --json`, then resume; never re-plan from scratch.
 - If `omo ulw-loop create-goals` says the existing aggregate is already complete, start unrelated new work with a fresh `--session-id <new-id>` instead of steering or forcing the completed default state. Use `--force` only to intentionally overwrite completed evidence.
-- Every success criterion needs observable evidence from a real surface: a channel (tmux, HTTP, browser, computer-use) or, for CLI- or data-shaped criteria, an auxiliary surface (CLI stdout, DB diff, parsed config dump).
+- Every success criterion needs observable evidence from a real surface: a channel (terminal/TUI via the xterm.js web terminal, HTTP, browser, computer-use) or, for CLI- or data-shaped criteria, an auxiliary surface (CLI stdout, DB diff, parsed config dump).
 - Record evidence through the CLI only after cleanup receipts are available.
 - Delegate code edits, test writes, fixes, and QA execution to right-sized Codex subagents when the workflow requires it.
 - Every `multi_agent_v1.spawn_agent` message starts with `TASK:`, then names `DELIVERABLE`, `SCOPE`, and `VERIFY`; put role and specialty instructions inside `message`; use `fork_context: false` unless full history is truly required.

package/packages/omo-codex/plugin/skills/ulw-loop/references/full-workflow.md

@@ -19,16 +19,16 @@ Audit each pass, fail, block, steering change, and checkpoint in `.omo/ulw-loop/
 Run each criterion's real-surface proof yourself through the channel that faithfully exercises it; capture the artifact before recording PASS.
 
 1. **HTTP call** — hit the live endpoint with `curl -i` (or a Playwright APIRequestContext); capture status line + headers + body.
-2. **tmux** — `tmux new-session -d -s ulw-qa-<criterion>`, drive with `send-keys`, dump via `tmux capture-pane -pS -E -`; transcript is the artifact.
+2. **Terminal / TUI** - prove it through the xterm.js web terminal; tmux `send-keys` is fine for a boot smoke, but NEVER `tmux capture-pane` for color/layout/CJK evidence (it degrades truecolor).
 3. **Browser use** — in Codex, use `browser:control-in-app-browser` first when available and the scenario does not need an authenticated or persistent user browser profile. Otherwise use Chrome to drive the REAL page; if unavailable, use agent-browser. Capture action log + screenshot path. Never downgrade a browser-facing criterion.
 4. **Computer use** — for desktop/GUI apps, drive the running app via OS automation (computer-use, AppleScript, xdotool, etc.); capture action log + screenshot.
 
-For TUI visual QA, pair the tmux transcript with a browser-rendered terminal
-screenshot. In this repo run `node script/qa/web-terminal-visual-qa.mjs
---from-file <capture.txt> --evidence-dir <dir>` and record `terminal.png`,
-`terminal.html`, `terminal.txt`, and `metadata.json` as the visual evidence
-bundle. This is mandatory when a PR or review needs to inspect the terminal
-screen, not just the text.
+For TUI visual QA, render the terminal through the real xterm.js web terminal and
+screenshot it - NEVER a `tmux capture-pane` dump (it degrades color and wide-glyph
+width). In this repo run `node script/qa/web-terminal-visual-qa.mjs --command
+"<cmd>" --input "{Enter}" --evidence-dir <dir>` (live pty + xterm.js in Chrome;
+`--from-file` replays a raw stream) and record `terminal.png`, `terminal.txt`, and
+`metadata.json`. Mandatory when a PR or review must inspect the terminal screen.
 
 Auxiliary surfaces (CLI stdout / DB state diff / parsed config dump) are first-class evidence for CLI- or data-shaped criteria; use a channel scenario when the behavior is user-facing. `--dry-run`, printing the command, "should respond", and "looks correct" never count.
 

package/packages/omo-codex/plugin/skills/ulw-plan/SKILL.md

@@ -15,9 +15,12 @@ Outcome-first: explore a lot, ask few sharp questions - or none, when the intent
 
 ## INTENT ROUTING - pick ONE intent reference
 
-Before routing, parse review modifiers separately. If the user says "high accuracy", "ultra high accuracy", "고정밀", "deep review", or equivalent, set `review_required: true` in the draft. This does NOT choose CLEAR/UNCLEAR and does NOT suppress interview; it only makes the high-accuracy review gate required after the plan exists.
+**Review modifiers are a gate trigger, not a style cue.** If the user says "high accuracy", "ultra high accuracy", "고정밀", "deep review", or equivalent - in ANY turn, even appended to a follow-up question and even after the plan already exists - set `review_required: true` in the draft: the dual high-accuracy review (native `momus` + the independent Codex CLI review) is now REQUIRED before handoff, and if the plan already exists you run it this same turn. Answering the current question more carefully does NOT satisfy it. This does NOT choose CLEAR/UNCLEAR and does NOT suppress interview.
 
-After grounding, make ONE judgment, record `intent: clear|unclear` plus `review_required`, and load ONE intent reference (you ALSO read `references/full-workflow.md` for the shared mechanics - see below). The test keys on whether the desired **OUTCOME** is clear, NOT on request length.
+After grounding, make ONE judgment, record `intent: clear|unclear` plus `review_required`, **ANNOUNCE both to the user in one line**, then load ONE intent reference (you ALSO read `references/full-workflow.md` for the shared mechanics - see below). The test keys on whether the desired **OUTCOME** is clear, NOT on request length. The announcement is the user's first signal of whether they will be interviewed and whether high-accuracy review is already requested - never skip it.
+
+> "Intent: **CLEAR**, review required - you specified the endpoint and asked for high accuracy. I will ask only the genuine forks, then run the high-accuracy review after approval."
+> "Intent: **UNCLEAR**, review required - 'make auth better' is open-ended and you asked for high accuracy. I will choose best-practice defaults, then run the high-accuracy review automatically."
 
 - **OVERRIDE - explicit ask wins:** if the user explicitly asks to be questioned or interviewed ("ask me", "interview me", "why aren't you asking me" - in any language), route **CLEAR**, run the interview, and turn the adopt-default filter OFF: the user has claimed the forks, so every surviving one is ASKED, not defaulted. This beats the OUTCOME test below, even on a fuzzy brief.
 - **CLEAR** - the user knows the outcome; the only open items are preferences/tradeoffs the repo cannot answer (genuine owner-decisions). Read **`references/intent-clear.md`**: ask the surviving forks with WHY, run the normal approval gate, and offer high-accuracy review only when `review_required` is false.
@@ -64,6 +67,17 @@ Fan out read-only research before deciding. Every spawn names DELIVERABLE / SCOP
 multi_agent_v1.spawn_agent({"message":"TASK: act as an explorer. DELIVERABLE: ... SCOPE: ... VERIFY: ...","agent_type":"explorer","fork_context":false})
 ```
 
+Spawn every independent child for the current wave first. After the wave
+is launched, use `multi_agent_v1.wait_agent` for each child until each
+reaches terminal status. A timeout is not terminal status. Do not start dependent planning, drafting, approval-gate work, or final handoff until each child result is integrated or recorded as inconclusive.
+
+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.
+
 Roles: `explorer` (internal patterns/conventions/tests), `librarian` (external docs/contracts), `metis` (gap analysis), `momus` (high-accuracy plan review). Full spawn/wait/fallback discipline is in `references/full-workflow.md`.
 
 ## Stop rules