oh-my-opencode 4.15.0 → 4.16.0

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

@@ -0,0 +1,380 @@
+---
+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. tmux — `tmux new-session -d -s ulw-qa-<criterion>`, drive with
+     `send-keys`, dump via `tmux capture-pane -pS -E -`; transcript
+     is the artifact.
+  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, terminal transcripts alone are not enough when a
+visual surface is being evaluated. In this repo, prefer
+`node script/qa/web-terminal-visual-qa.mjs --title "<surface>" --from-file <capture.txt> --evidence-dir <dir>`
+or the helper's `--command` tmux-backed PTY connector when available.
+Outside this repo, capture equivalent browser/computer-use rendered
+terminal evidence: screenshot, plain transcript, rendered HTML or action
+log, and 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.
+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/references/full-workflow.md

@@ -127,7 +127,7 @@ Gather context BEFORE planning with parallel `explorer` / `librarian` workers pl
 First survey available skills: read every loosely-relevant skill's description, deliberately choose which this work uses, and prefer applying genuinely-relevant skills over working raw.
 Then run tier triage per goal — rigor (LIGHT/HEAVY below) and shape (`delivery` default, or `research` when the deliverable is a cited answer, not an artifact) — and record both in an `annotate_ledger` steering entry. Default is LIGHT — a narrow change inside existing layers. Take HEAVY only on a fact you can point to: a new module / abstraction / domain model; auth, security, or session; an external integration; a DB schema or migration; concurrency, transaction boundaries, or cache invalidation; a cross-domain refactor; or the user signaled care or demanded review. When unsure, take HEAVY; upgrade the moment a HEAVY fact surfaces, never downgrade mid-run.
 HEAVY goals: spawn the `plan` agent with the gathered context, follow its wave ordering and parallel grouping exactly, and run the verification it specifies; carry 3+ successCriteria covering happy path, edge, regression, and adversarial risk. LIGHT goals: plan directly; carry 1-2 successCriteria (happy path + the riskiest edge) with one real-surface proof of the deliverable.
-Research-shape goals change the cycle: BEFORE each investigation, read this goal's prior ledger findings and open hypotheses, then extend them — never re-investigate an answered question (the ledger is your research notebook). Record findings via `annotate_ledger` with their source (`file:line`, command output, doc URL) as `--evidence`. Track hypotheses as `HYPOTHESIS[id]: <claim> | status: open`, flipped to `confirmed`/`refuted` only on an observed source. A research criterion passes on a cited answer — skip QA-channel, cleanup, and commit, but keep source-observability (never "looks correct"). Keep hypotheses inside the user's stated question; a scope-widening one is an `add_subgoal` proposal you surface, never silent creep. For a `research`-shape goal you MAY load `ulw-research` (legacy alias: `ultraresearch`) without hesitation — otherwise explicit-request-only, a research-shape goal IS that explicit demand. Research-only: never for a `delivery` goal. It composes with the librarian routing above — `ulw-research` for saturation (many parallel sources, recursive expansion), a single `librarian` for one lookup.
+Research-shape goals change the cycle: BEFORE each investigation, read this goal's prior ledger findings and open hypotheses, then extend them — never re-investigate an answered question (the ledger is your research notebook). Record findings via `annotate_ledger` with their source (`file:line`, command output, doc URL) as `--evidence`. Track hypotheses as `HYPOTHESIS[id]: <claim> | status: open`, flipped to `confirmed`/`refuted` only on an observed source. A research criterion passes on a cited answer — skip QA-channel, cleanup, and commit, but keep source-observability (never "looks correct"). Keep hypotheses inside the user's stated question; a scope-widening one is an `add_subgoal` proposal you surface, never silent creep. For a `research`-shape goal you MAY load `ulw-research` without hesitation — otherwise explicit-request-only, a research-shape goal IS that explicit demand. Research-only: never for a `delivery` goal. It composes with the librarian routing above — `ulw-research` for saturation (many parallel sources, recursive expansion), a single `librarian` for one lookup.
 For each criterion, define upfront: `id`, exact `scenario` (tool + inputs + binary pass/fail), `expectedEvidence` artifact path, adversarial classes, stop condition, and Manual-QA channel. Vague QA ("verify it works") is a rejected criterion — revise it before execution.
 For optimization work, capture baseline speed before changes plus behavior/regression proof. Every attempt records speed, behavior/regression, and the keep/revert/iterate decision.
 A criterion's adversarial classes are the ultraqa classes a fact about the change triggers: malformed input, prompt injection, cancel/resume, stale state, dirty worktree, hung or long commands, flaky tests, misleading success output, repeated interruptions. Record untriggered classes as not-applicable in one line.

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.

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

@@ -36,7 +36,7 @@ Make ONE judgment and follow ONE reference. Review modifiers are not routing sig
 - CLEAR -> `intent-clear.md`: run the **two filters** on every candidate question; ask only surviving forks (owner-decisions), with WHY.
 - UNCLEAR -> `intent-unclear.md`: research maximally, adopt announced best-practice defaults, do not ask the user extra questions.
 
-If a draft/plan already exists and the user asks for high-accuracy review, high-accuracy planning, or to make the plan more accurate, do not reroute from scratch unless the scope changed. Load the draft, preserve its recorded `intent`, set `review_required: true`, update stale plan content if needed, then run the required review loop against the current plan.
+If a draft/plan already exists and the user says a review modifier - even appended to an otherwise unrelated follow-up question - or asks to make the plan more accurate, do not reroute from scratch unless the scope changed. Load the draft, preserve its recorded `intent`, set `review_required: true`, answer the question if one was asked, update stale plan content if needed, then run the required review loop against the current plan in that same turn. A more rigorous answer is not a substitute for the review.
 
 Both paths record `intent`, `review_required`, and decisions to `.omo/drafts/<slug>.md` as they go - long sessions outlive your context, and plan generation reads the draft, not your memory.
 
@@ -82,10 +82,10 @@ Runs in parallel; ALL must APPROVE; surface results and wait for the user's expl
 ## Phase 4 - Deliver
 - CLEAR with `review_required: false`: present the plan summary, then ask ONE question and stop - start work now, or run a high-accuracy review first? Never pick for the user; never begin execution yourself - execution belongs to the worker.
 - CLEAR with `review_required: true`: run the high-accuracy review before delivery, record receipts, then present the plan summary and review result. Do not ask whether to run the review; the user already asked.
-- UNCLEAR: run Metis plus the high-accuracy review AUTOMATICALLY before presenting (unless Classify=Trivial), then present a brief that LEADS with the derived approach and the adopted defaults; still wait for the user's explicit okay.
+- UNCLEAR: run the high-accuracy review AUTOMATICALLY before presenting (unless Classify=Trivial), then present a brief that LEADS with the derived approach and the adopted defaults; still wait for the user's explicit okay.
 
 ### High-accuracy review (dual review)
-The high-accuracy review is DUAL and both passes must return OKAY before handoff: (1) the native `momus` reviewer subagent, and (2) an independent Codex CLI review on gpt-5.5 at xhigh reasoning, run in a disposable isolated workspace and `CODEX_HOME` with the harness's normal approval and sandbox policy. Do not add flags that disable approvals or sandboxing. Fix every cited issue and resubmit BOTH fresh until each approves. CLEAR: runs when the user opts in or `review_required: true`. UNCLEAR: runs automatically unless Classify=Trivial.
+The high-accuracy review is DUAL and both passes must return OKAY before handoff: (1) the native `momus` reviewer subagent, and (2) an independent Codex CLI review on gpt-5.5 at xhigh reasoning, run in a disposable isolated workspace and `CODEX_HOME` with the harness's normal approval and sandbox policy. Do not add flags that disable approvals or sandboxing. One round = exactly ONE `momus` + ONE independent review, dispatched together against the COMPLETE plan file (todos + TL;DR filled) - never a second `momus` while a round is in flight. After both verdicts return, fix every cited issue and resubmit both fresh until each approves. CLEAR: runs when the user opts in or `review_required: true`. UNCLEAR: runs automatically unless Classify=Trivial.
 
 The draft must record the native Momus session/result, the independent Codex CLI review command/result, and the fix/retry summary. Do not say "high-accuracy review completed" unless both receipts exist and both final verdicts are unconditional approval.
 
@@ -99,6 +99,6 @@ multi_agent_v1.spawn_agent({"message":"TASK: act as an explorer. DELIVERABLE: ..
 Roles: `explorer`, `librarian`, `metis`, `momus`. Spawn long plan/reviewer agents in the background and poll with short waits; require the child to send `WORKING: <task> - <phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A wait timeout only means no new mailbox update arrived; treat a running child as alive. Fall back only when the child completed without the deliverable, is ack-only after followup, explicitly `BLOCKED:`, or no longer running; then respawn a smaller `fork_context: false` job. Close each agent after integrating its result.
 
 ## Stop rules
-- Plan file exists, template filled, every todo has references + acceptance + QA + commit, dependency matrix consistent: present the summary, ask the start-or-high-accuracy question (CLEAR) or lead with the best-practice brief (UNCLEAR), and stop. Execution belongs to the worker, never to you.
+- Plan file exists, template filled, every todo has references + acceptance + QA + commit, dependency matrix consistent, and any required high-accuracy receipts recorded: present the summary, then (CLEAR without `review_required`) ask the start-or-high-accuracy question, or (CLEAR with `review_required` / UNCLEAR) report the review result - and stop. Execution belongs to the worker, never to you.
 - Brief presented and `status: awaiting-approval` recorded: wait. Do not re-explore unless the user changes scope.
 - Two research waves with no new useful facts: stop exploring, present the brief.

package/packages/omo-codex/plugin/skills/ulw-plan/references/intent-unclear.md

@@ -26,7 +26,7 @@ Fold a contrarian self-grill into the Metis spawn: challenge the single highest-
 </default_selection>
 
 <high_accuracy_auto>
-Because the human did not steer, adversarial review SUBSTITUTES for the interview you skipped - this is what catches a bad default. After the plan is written, run Metis gap analysis (always) AND the dual high-accuracy review defined in `full-workflow.md` AUTOMATICALLY - no "do you want a review?" question. Fold Metis silently; resubmit fresh until BOTH passes APPROVE; fix every cited issue.
+Because the human did not steer, adversarial review SUBSTITUTES for the interview you skipped - this is what catches a bad default. Metis runs during plan generation as always; after Metis findings are folded and the plan file is complete, run the dual high-accuracy review defined in `full-workflow.md` AUTOMATICALLY - no "do you want a review?" question - and resubmit fresh until BOTH passes APPROVE, fixing every cited issue.
 
 TRIVIAL-TIER GUARD: if Classify sized the work Trivial, the auto-Momus loop is SUPPRESSED (Metis still runs once) - a vague-but-tiny request ("clean this up") must not trigger the full adversarial loop. UNCLEAR raises the research-plus-default posture; it does not override the Trivial cost guard for Momus.
 </high_accuracy_auto>
@@ -40,5 +40,5 @@ Request: "make auth better".
 1. Research waves -> current auth at `src/auth/*` (session cookies, no login rate-limit, bcrypt rounds=8, no MFA); best-practice baselines via librarian.
 2. Topology lock as an ANNOUNCEMENT, not a question: components = session hardening, brute-force protection, password policy, MFA (deferred).
 3. Adopted-defaults table (assumption | default | rationale | reversible?): bcrypt rounds 8 -> 12 (reversible), add 5/min-per-IP login limit (reversible), rotate session id on privilege change (reversible).
-4. Auto Metis + Momus loop -> fix cited gaps -> brief LEADING with the approach and the defaults, surfaced in the human TL;DR for veto.
+4. Metis folded -> auto dual review (fix cited gaps until both approve) -> brief LEADING with the approach and the defaults, surfaced in the human TL;DR for veto.
 </worked_example>

package/packages/omo-codex/plugin/skills/ulw-research/ATTRIBUTION.md

@@ -7,9 +7,9 @@ is adapted into this skill's prompt contract.
 
 ---
 
-## 1. insane-research (fivetaku) — inspiration for the claim-ledger verification gate
+## 1. insane-research (fivetaku) — inspiration for the claim-graph verification gate
 
-The non-code claim-ledger verification gate (Phase 3b: a data-flow-lock where the
+The non-code claim-graph verification gate (Phase 3b: a data-flow-lock where the
 synthesis may assert a high-risk non-code claim only after it clears `>= 2 independent
 source domains + 1 counter-search + a primary source`, otherwise it is abstained to an
 unresolved/refuted annex) is inspired by the data-flow-lock verification design in

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

@@ -1,6 +1,6 @@
 ---
 name: ulw-research
-description: "Maximum-saturation research orchestration: parallel explore+librarian swarms across codebase, web, official docs, and OSS repos; a recursive EXPAND loop driven by leads workers return in message text; empirical verification by running code; cited synthesis and optional MD/HTML/PDF/PPTX reports. ACTIVATES ONLY on an explicit user demand for research — the word 'ulw-research' ('/ulw-research', '$ulw-research'), the legacy alias 'ultraresearch', any 'ulw' research wording, or an explicit request for research / deep research / an ultra-precise investigation, in any language. Never self-activates for ordinary questions, debugging, or implementation context-gathering. While active it overrides exploration-bounding defaults: exhaustive coverage is the goal."
+description: "Maximum-saturation research orchestration: parallel explore+librarian swarms across codebase, web, official docs, and OSS repos; a recursive EXPAND loop driven by leads workers return in message text; empirical verification by running code; cited synthesis and optional MD/HTML/PDF/PPTX reports. ACTIVATES ONLY on an explicit user demand for research — the word 'ulw-research' ('/ulw-research', '$ulw-research'), any 'ulw' research wording, or an explicit request for research / deep research / an ultra-precise investigation, in any language. Never self-activates for ordinary questions, debugging, or implementation context-gathering. While active it overrides exploration-bounding defaults: exhaustive coverage is the goal."
 ---
 
 ## Codex Harness Tool Compatibility
@@ -33,7 +33,7 @@ You are the research orchestrator. The user has explicitly ordered exhaustive re
 
 ## Activation
 
-Run this skill only when the user explicitly demands it: the word "ulw-research" (also `/ulw-research`, `$ulw-research`), the legacy alias "ultraresearch" (also `/ultraresearch`, `$ultraresearch`), any "ulw" research wording, or an explicit request for research, deep research, or an ultra-precise investigation — in any language. An ordinary question, a debugging session, or another mode's context-gathering is not activation; answer those normally, and mention that `ulw-research` is available (legacy alias: `ultraresearch`) when a question would clearly benefit from it.
+Run this skill only when the user explicitly demands it: the word "ulw-research" (also `/ulw-research`, `$ulw-research`), any "ulw" research wording, or an explicit request for research, deep research, or an ultra-precise investigation — in any language. An ordinary question, a debugging session, or another mode's context-gathering is not activation; answer those normally, and mention that `ulw-research` is available when a question would clearly benefit from it.
 
 Open your reply with the line `ULW-RESEARCH MODE ENABLED!`. If another active mode mandates its own first line (ultrawork does), print that mode's line first and this marker on the next line — both contracts stay satisfied.
 
@@ -51,9 +51,22 @@ The research is done when all of these hold:
 - Every EXPAND lead was investigated or explicitly closed as a duplicate or dead end, and convergence was reached under the Phase 2 rules.
 - Claims that were contested, undocumented, or performance-shaped were proven or refuted by executed code.
 - Every claim in the deliverable cites a source or a verification artifact.
+- Every asserted claim is represented in the claim graph, tied to an intent-vs-reality diff when an expected truth exists, and backed by observation manifest entries from independent observation groups or a documented single-source exception; convergence or exception status is explicit.
 - Final materials follow the Phase 5 format default or the user's explicit format.
 - The session journal reconstructs what was searched, found, and expanded, wave by wave.
 
+## Epistemic instrumentation
+
+Saturation is not just more searching; it is a knowledge-production protocol. The session journal must make the path from observation to claim to verdict auditable. The orchestrator owns these artifacts:
+
+- `intent-diff.md` — one row per expected truth derived from the user intent, design/spec text, branch history, or authoritative docs. Required fields: `intent_id`, expected truth, observed reality, diff, violated invariant, intent source, supporting observations, status (`true`, `violated`, or `unknown`), and linked claim ids.
+- `claim-graph.md` — the single claim store; one node per claim. Required fields: `claim_id`, statement, claim type, risk tier, scope, intent ids, supporting observations, contradicting observations, independent observation groups, convergence status, counter-search result, primary source backing, dependencies, status (`supported`, `partial`, `refuted`, or `unresolved`), and final synthesis location. High-risk non-code nodes that clear the Phase 3b gate are mirrored into a `verified-claims` digest section at the top of the file — the sole allowlist the synthesis draws non-code claims from.
+- `observation-manifest.md` — one row per observation. Required fields: `observation_id`, source path or URL, evidence layer, observer group, independence basis, observer, `observed_at`, `valid_at` or `claim_valid_at`, artifact path, quote or line anchor, and contamination notes.
+- `verification-economics.md` — one row per proof decision. Required fields: claim, risk, error cost, verification cost/time, chosen verification path, defer/verify decision, outcome, and residual risk.
+- `cause-disappearance.md` — one row per causal finding. Required fields: cause id, expected truth, previous observation, `last_seen`, disconfirming observation, replacement cause if any, current status, and whether the violation is no longer observed.
+
+Observation candidates and claim candidates travel back from workers as message text. The orchestrator writes the instrumentation artifacts, links candidates into the intent diff and claim graph, and records where each observation entered the synthesis. A conclusion is not ready for final materials until its expected truth/reality diff is closed or marked unknown, its claim node exists, and its independent-observation convergence status is supported or explicitly excepted.
+
 ## Run the swarm as a cooperating team
 
 Saturation research defaults to teammode, not isolated fire-and-forget workers: a lead one worker surfaces almost always reshapes what another should search next. When your harness gives you real cooperating members — Codex: the `teammode` skill (`codex_app` threads); OpenCode: `team_mode` — run this swarm as a team. Fall back to the background-worker swarm below only when team mode is unavailable, or the axes are genuinely independent with no cross-pollination expected.
@@ -80,7 +93,7 @@ Every research spawn message contains, in order:
 2. The budget lift: "This is an explicit exhaustive-research assignment. Your default retrieval budget and stop-when-answered rules do not apply — run the full protocol below and report every lead."
 3. Scope — the axis, the sources to hit, and what a complete answer contains.
 4. The role protocol (Phase 1).
-5. The reply tail. EXPAND markers travel back as message text, never as files. Every worker ends the reply with:
+5. The reply tail. EXPAND markers, observation candidates, and claim candidates travel back as message text, never as files. Every worker ends the reply with:
 
 ```
 ## EXPAND
@@ -92,7 +105,7 @@ A worker with nothing to expand writes `## EXPAND` followed by `none — <one-li
 
 ## Phase 0 — Decompose and open the journal
 
-Before spawning anything, decompose the query:
+Before spawning anything, decompose the query. Start from "what must be true if the user's intent/spec is true?", not "what looks broken?" Seed `intent-diff.md` with those expected truths before treating code, current docs, or web results as the source of truth:
 
 ```
 <analysis>
@@ -112,6 +125,11 @@ This is `$SESSION_DIR`. The orchestrator owns the journal: you write every file
 
 - `wave-<N>-<kind>-<axis>.md` — your digest of each worker return: key findings, sources with URLs, and the worker's EXPAND markers verbatim.
 - `expansion-log.md` — per wave: workers spawned, markers gained, leads opened and closed.
+- `intent-diff.md` — orchestrator-owned expected-truth ledger comparing intent/spec/history to observed reality.
+- `claim-graph.md` — orchestrator-owned claim graph linking every final assertion to observations, counterevidence, dependencies, and verdict.
+- `observation-manifest.md` — orchestrator-owned observation manifest with `observed_at`, temporal validity, artifact paths, and contamination notes.
+- `verification-economics.md` — proof-cost ledger mapping claim risk to verification path, deferral decisions, and residual risk.
+- `cause-disappearance.md` — cause ledger tracking expected truth, previous observation, `last_seen`, disconfirming observation, and whether the violation is no longer observed.
 - `verify-<slug>.md`, `SYNTHESIS.md`, `REPORT.*` from later phases.
 
 Append each digest the moment its worker returns, not in a batch at the end — the journal is your recovery point after context loss and the user's audit trail.
@@ -183,19 +201,21 @@ Reply with: the exact code, the full output, environment (OS, runtime, dependenc
 
 Journal each verdict to `verify-<slug>.md`.
 
-## Phase 3b — Lock non-code claims through a claim ledger
+## Phase 3b — Lock non-code claims through the claim graph
 
 Code settles code-shaped claims (Phase 3). Numeric, market-share, legal, dated, causal, and financial claims cannot be run — so they pass through a data-flow-lock instead (the verification idea adapted from fivetaku/insane-research): the synthesis may assert a high-risk non-code claim **only** if it cleared this gate, and the gate's output is the sole allowlist the synthesis draws from. Skip the gate and there is nothing to synthesize — the lock is self-enforcing.
 
-The claim ledger is orchestrator-owned. Workers only return verified-claim markers as message text, the same channel as EXPAND markers — never a file. As leads resolve, you record one ledger entry per asserted claim and compute its status; workers report claim candidates in their replies, and you decide.
+The claim graph is orchestrator-owned. Workers only return verified-claim markers, observation candidates, and claim candidates as message text, the same channel as EXPAND markers — never a file. As leads resolve, you record one node per asserted claim in `claim-graph.md` and compute its status; workers report claim candidates in their replies, and you decide. The graph is the single claim store: final synthesis may not draw from free-form claims that skipped it.
 
 A high-risk claim clears the gate to `verified-claims` only when all hold:
 
 - **>= 2 independent source domains** corroborate it (two pages on the same domain count once).
+- **>= 2 independent observation groups** converge on it, unless the graph records why a primary-only source is the correct single-source exception.
 - **One counter-search** actively looked for a refutation and did not find a stronger one.
 - **A primary source** (the standard, filing, dataset, or first-party doc) backs it, not only secondary commentary.
+- **Temporal evidence is explicit**: each supporting observation records `observed_at` and either `valid_at` or `claim_valid_at`, so branch-only, historical, release, and current-runtime claims cannot be conflated.
 
-Anything that fails goes to an `Unresolved` (insufficient evidence) or `Refuted` (counter-search won) annex — abstention is a correct outcome, not a gap to paper over. Maintain `claim-ledger.md` with one row per claim — `claim | risk | domains | counter-search | primary? | status (verified/unresolved/refuted)` — and write the cleared rows into a `verified-claims` digest. Worker reply marker (message text, same channel as EXPAND):
+Anything that fails goes to an `Unresolved` (insufficient evidence) or `Refuted` (counter-search won) annex — abstention is a correct outcome, not a gap to paper over. Record each gate outcome on the claim node itself — risk tier, independent source domains, counter-search result, primary source backing, and status — and mirror the cleared nodes into the `verified-claims` digest section at the top of `claim-graph.md`. Worker reply marker (message text, same channel as EXPAND):
 
 ```
 ## CLAIMS
@@ -204,10 +224,10 @@ Anything that fails goes to an `Unresolved` (insufficient evidence) or `Refuted`
 
 ## Phase 4 — Synthesize
 
-After convergence and all verifications, re-read the whole journal and write `SYNTHESIS.md`:
+After convergence and all verifications, re-read the whole journal, start from `intent-diff.md`, `claim-graph.md`, and `observation-manifest.md`, then write `SYNTHESIS.md`:
 
 ```
-# Ultraresearch Synthesis: <query>
+# ULW-Research Synthesis: <query>
 Workers: <total> · Waves: <count> · Sources: <count> · Verifications: <count>
 
 ## Executive summary        — 2-3 paragraphs answering the core question
@@ -215,8 +235,9 @@ Workers: <total> · Waves: <count> · Sources: <count> · Verifications: <count>
 ## Codebase findings        — absolute paths with line references
 ## Sources (ranked)         — URL, what it contains, reliability, access date
 ## Verified claims          — code: claim | verdict | verify-<slug>.md · non-code: only rows cleared into verified-claims
+## Epistemic instrumentation — intent-vs-reality diff closure, claim graph coverage, observation manifest coverage, independent-observation convergence, verification economics summary, cause-disappearance records
 ## Contradictions           — source A vs source B, resolution with evidence
-## Gaps                     — what saturation could not answer · unresolved/refuted claim-ledger rows
+## Gaps                     — what saturation could not answer · unresolved/refuted claim-graph nodes
 ## Expansion trace          — per wave: workers → markers; convergence reason
 ```