oh-my-opencode 5.0.0-beta.2 → 5.0.0-beta.21

package/packages/omo-codex/plugin/skills/{start-work → ulw-execute}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: start-work
-description: "Execute a Prometheus work plan with Boulder state, evidence ledger updates, worktree discipline, parallel subagents, and Stop-hook continuation. Use after planning when the user says start work, execute plan, continue plan, resume plan, or asks to run a .omo/plans plan."
+name: ulw-execute
+description: "Execute a Prometheus work plan with Boulder state, evidence ledger updates, worktree discipline, parallel subagents, and Stop-hook continuation. Use after planning when the user says ulw-execute, execute plan, continue plan, resume plan, or asks to run a .omo/plans plan."
 ---
 
 ## Codex Harness Tool Compatibility
@@ -38,14 +38,14 @@ Every `multi_agent_v1.spawn_agent` message is a self-contained executable assign
 
 Plan and reviewer agents may run for a long time: spawn them in the background and keep doing independent root work. Between `multi_agent_v1.wait_agent` calls, back off — double the timeout up to ~5 minutes — instead of spinning short cycles. A timeout only means no new mailbox update arrived; treat a running child as alive. Require `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. Keep the parent visibly alive with active subagent count, names, and latest `WORKING:` phase. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running — then record inconclusive (never a pass), close if safe, and respawn a smaller `fork_context: false` task with the missing deliverable.
 
-# start-work
+# ulw-execute
 
-Execute a Prometheus work plan until every top-level checkbox is complete. This skill pairs with the harness's start-work continuation hook, which re-injects the next turn while `.omo/boulder.json` says this `codex:<session_id>` still has unchecked plan work.
+Execute a Prometheus work plan until every top-level checkbox is complete. This skill pairs with the harness's ulw-execute continuation hook, which re-injects the next turn while `.omo/boulder.json` says this `codex:<session_id>` still has unchecked plan work.
 
 ## Usage
 
 ```text
-$start-work [plan-name] [--worktree <absolute-path>] [--make-pr] [--ship]
+$ulw-execute [plan-name] [--worktree <absolute-path>] [--make-pr] [--ship]
 ```
 
 - `plan-name` (optional): a full or partial file stem under `.omo/plans/`.
@@ -73,7 +73,7 @@ Do ALL of this immediately after the plan is selected, BEFORE the first implemen
 
 ### No-plan bootstrap
 
-When the user explicitly said `start work` / `$start-work` and no selectable plan exists, treat that phrase as approval: bootstrap `ulw-plan` to create the approved plan before execution and implementation, instead of stalling or asking for generic approval again. A brief or notes file without waves, checkboxes, and acceptance criteria is NOT decision-complete — enter this bootstrap too.
+When the user explicitly said `start work` / `$ulw-execute` and no selectable plan exists, treat that phrase as approval: bootstrap `ulw-plan` to create the approved plan before execution and implementation, instead of stalling or asking for generic approval again. A brief or notes file without waves, checkboxes, and acceptance criteria is NOT decision-complete — enter this bootstrap too.
 
 1. Invoke the `ulw-plan` skill from the current request and require its dynamic adversarial workflow: collect, verify, design, adversarial plan-review, synthesize.
 2. The generated Prometheus plan must be saved under `.omo/plans/<slug>.md` before implementation or Boulder state writes that point at plan work.
@@ -109,6 +109,7 @@ For PR/branch work, a task-owned worktree is mandatory before implementation sta
 Solo orchestration with parallel background workers is the default topology. Decide once, when the wave's lanes are known, and record the verdict in the ledger:
 
 - **Independent lanes -> parallel workers.** Separate files, no shared contract: one parallel spawn burst; no team.
+- **Dependency-ordered lanes -> a dag run.** Sub-tasks with real ordering between them (C needs A and B finished first) and a harness with a native `dag` tool: dispatch the wave as ONE dag run — one producer node per lane plus a verification node — instead of a spawn burst, and watch the run's lifecycle instead of arming per-lane watchers. Read the `mass-ulw` skill's `SKILL.md` and `references/planning.md` IN FULL before defining any graph.
 - **Overlapping lanes -> a team.** The lanes touch the same module or contract AND running them concurrently actually finishes sooner: stand up a team (where the harness has one) so one lane's discoveries relay through you mid-flight.
 - **PR-mode independent lanes -> a worktree per lane.** Under `--make-pr`/`--ship`, when a wave holds independent checkboxes, give each lane its own branch and task-owned worktree, delivered as its own PR.
 
@@ -125,7 +126,7 @@ Landing rules, regardless of topology:
 3. Ignore nested checkboxes under acceptance criteria, evidence, and definition-of-done sections.
 4. Classify the checkbox tier and record it in its ledger 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 or transaction boundaries; a cross-domain refactor; or the plan or user signals care. When unsure, take HEAVY; upgrade and redo skipped gates the moment a HEAVY fact surfaces; never downgrade.
 5. Decompose that checkbox into atomic sub-tasks sized for ONE worker in ONE run — a sub-task that would need mid-flight steering is two sub-tasks. Collect every other unchecked checkbox in the same plan wave whose dependencies are met — their lanes execute concurrently. A wave that could split further but holds fewer than 3 independent sub-tasks is under-split.
-6. **DELEGATE EVERYTHING. YOU NEVER IMPLEMENT.** Route every sub-task through the delegation router below, then dispatch ALL independent sub-tasks across those checkboxes in one parallel worker-spawn burst (a single batched spawn call where the harness supports it); serialize only named dependencies. Verification and checkbox marking stay per-checkbox.
+6. **DELEGATE EVERYTHING. YOU NEVER IMPLEMENT.** Route every sub-task through the delegation router below, then dispatch ALL independent sub-tasks across those checkboxes in one parallel worker-spawn burst (a single batched spawn call where the harness supports it); route named dependencies per the lane-topology decision above. Verification and checkbox marking stay per-checkbox.
 7. Give every dispatched sub-task its completion condition and watch for it per the section below. A dispatch whose completion nobody watches is an unfinished dispatch.
 
 ### Monitor every dispatched subagent to its completion condition
@@ -185,7 +186,7 @@ For each checkbox, complete all five gates before marking it done:
 4. Adversarial QA: exercise every class the Phase 3 trigger map marks applicable and capture the observable result for each.
 5. Cleanup: register every QA resource teardown as its own todo when spawned (QA scripts, tmux assets, browser sessions, PIDs, ports, containers, temp dirs), execute each, and capture the receipt. No QA asset is left running.
 
-Append evidence to `.omo/start-work/ledger.jsonl`, one JSON object per line. Include at least `event`, `plan`, `task`, `session_id`, `commands`, `artifact`, `adversarial_classes`, and `cleanup` fields. `adversarial_classes` lists each probed class with its observable result and each ruled-out class with a one-line reason.
+Append evidence to `.omo/ulw-execute/ledger.jsonl`, one JSON object per line. Include at least `event`, `plan`, `task`, `session_id`, `commands`, `artifact`, `adversarial_classes`, and `cleanup` fields. `adversarial_classes` lists each probed class with its observable result and each ruled-out class with a one-line reason.
 
 ### Sisyphus-style completion contract
 
@@ -233,10 +234,10 @@ When all top-level checkboxes in `## TODOs` and `## Final Verification Wave` are
 1. Run the plan's final verification commands.
 2. Complete the **Global Review and Debugging Gate** before any completion claim, PR creation, PR handoff, branch handoff, or merge:
    - Invoke the `review-work` skill with the final diff, changed files, user goal, constraints, run command, and verification evidence. All five review lanes must return PASS. A timeout, missing deliverable, ack-only child, `BLOCKED:`, or inconclusive lane is a gate failure, not approval.
-   - Each passing review lane binds to the exact full commit SHA it reviewed. Immediately append a durable record to `.omo/start-work/ledger.jsonl` with the lane name, full SHA, PASS verdict, and report artifact/source. Before same-SHA reuse after any continuation or compaction, re-read the ledger record and require the exact lane/SHA pair; memory, chat history, or an unstamped report is not coverage. New commits require fresh applicable lane coverage.
-   - Run a debugging-oriented runtime audit even when the review passes: name at least three plausible failure hypotheses for the changed surface, run the distinguishing checks against the actual artifact, and append a separate durable record with the audit name, exact full SHA, verdict, and evidence artifact/source to `.omo/start-work/ledger.jsonl`. Reuse it only after re-reading an exact audit/SHA match.
+   - Each passing review lane binds to the exact full commit SHA it reviewed. Immediately append a durable record to `.omo/ulw-execute/ledger.jsonl` with the lane name, full SHA, PASS verdict, and report artifact/source. Before same-SHA reuse after any continuation or compaction, re-read the ledger record and require the exact lane/SHA pair; memory, chat history, or an unstamped report is not coverage. New commits require fresh applicable lane coverage.
+   - Run a debugging-oriented runtime audit even when the review passes: name at least three plausible failure hypotheses for the changed surface, run the distinguishing checks against the actual artifact, and append a separate durable record with the audit name, exact full SHA, verdict, and evidence artifact/source to `.omo/ulw-execute/ledger.jsonl`. Reuse it only after re-reading an exact audit/SHA match.
    - If any review lane or debugging hypothesis fails, invoke the `debugging` skill, confirm root cause with runtime evidence, add the minimal failing test or reproduction, fix it, rerun the affected verification, then rerun the Global Review and Debugging Gate.
-   - Evidence hygiene is mandatory: redact or mask secrets and sensitive user data before writing `.omo/start-work/ledger.jsonl`, a PR body, or a handoff. Never include raw tokens, credentials, auth headers, cookies, API keys, env dumps, private logs, or PII; use concise summaries, lengths, hashes, or short non-sensitive prefixes instead.
+   - Evidence hygiene is mandatory: redact or mask secrets and sensitive user data before writing `.omo/ulw-execute/ledger.jsonl`, a PR body, or a handoff. Never include raw tokens, credentials, auth headers, cookies, API keys, env dumps, private logs, or PII; use concise summaries, lengths, hashes, or short non-sensitive prefixes instead.
    - If the work includes creating, updating, or handing off a PR, refresh `git status` and the PR/branch state from the task-owned worktree after the gate, and include only redacted review/debugging evidence in the PR body or handoff.
 3. Finish the PR/branch lifecycle from its task-owned worktree: sync `.omo/` state back to the main repo, create or update the PR when requested, wait for CI/review/Cubic gates, merge by default unless explicitly opted out, and remove the worktree only after successful merge or explicit handoff.
 4. Remove or mark the Boulder work as completed.

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

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

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

@@ -15,12 +15,13 @@ This skill is intentionally compact. The full workflow lives in `references/full
 
 1. Open `references/full-workflow.md`.
 2. Read through **Bootstrap** (including its tier triage), **Execution Loop**, the **Manual-QA channels** table, and the **Stop Rules** before running any ULW command or recording evidence.
-3. If the task has code edits, tests, QA, or commit work, follow the full workflow's delegation and evidence rules. Tests alone never prove done.
+3. Open `references/define-goal.md` and register the run's goal by it. Goal creation is NEVER skipped: shape the objective and every success criterion by that reference before any implementation.
+4. If the task has code edits, tests, QA, or commit work, follow the full workflow's delegation and evidence rules. Tests alone never prove done.
 
 ## Non-Negotiables
 
 - Use the ulw-loop CLI state under `.omo/ulw-loop`; do not hand-edit goal state.
-- Register goals up front (`omo-agent-toolkit ulw-loop create-goals`, then `create_goal` from the printed handoff) and mirror every atomic step into the live `update_plan` checklist: one ultra-granular step per action, exactly one in_progress, transitions marked the instant they happen.
+- Register goals up front, shaped by `references/define-goal.md` (`omo-agent-toolkit ulw-loop create-goals`, then `create_goal` from the printed handoff), and mirror every atomic step into the live `update_plan` checklist: one ultra-granular step per action, exactly one in_progress, transitions marked the instant they happen.
 - After any compaction or context loss, re-read brief + goals + ledger FIRST plus `omo-agent-toolkit ulw-loop status --json`, then resume; never re-plan from scratch.
 - If `omo-agent-toolkit 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 (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).

package/packages/omo-codex/plugin/skills/ulw-loop/references/define-goal.md

@@ -0,0 +1,108 @@
+# Define Goal
+
+How to turn a brief into a registered goal the run can be held to. Read this BEFORE calling `create_goal`: the objective you register is the binding contract for the whole run, and the run's quality is capped by the quality of this objective.
+
+A goal is a prompt to the agent that executes it, including future-you after compaction. It earns its tokens the way any prompt does: it carries only what the run cannot re-derive later, the outcome, the proof, the bounds, and the stop state. Everything else is noise that steals attention from the parts that decide completion.
+
+## The quality bar
+
+Before registering, the objective must answer all five:
+
+1. What concrete thing will be TRUE when this is done? An outcome, never an activity.
+2. What evidence will prove it? Commands, validators, artifacts someone can open.
+3. What quantitative or binary threshold defines success?
+4. What scope boundaries matter? What is in, and what is explicitly out.
+5. What should make the agent stop and ask instead of grinding?
+
+An objective that cannot answer one of these is not ready. Repair it (below) before calling the tool.
+
+## Objective anatomy
+
+Write the objective outcome-first, in this order:
+
+1. **Outcome**: one sentence stating what will be true, naming the artifact, system, repo, or user-facing behavior involved.
+2. **Deliverables**: the named surfaces the work lands on (files, endpoints, packages, environments). Use literal paths and names: the executing agent interprets the objective literally and will not infer surfaces you did not name.
+3. **Success criteria**: sized by tier (below), each one a binary observable with its scenario and evidence named upfront.
+4. **Constraints and scope bounds**: Record the user's stated constraints verbatim, including what is explicitly out of scope wherever ambiguity would let the run expand. Where the user was silent on a bound the work forks on, SET it yourself: derive the clearest defensible bound from repo evidence and best practice (stack already in use, compatibility surfaces, scale the code must serve, audience or compliance the repo implies) and record it inside the objective as `assumed: <constraint> — <rationale>, <reversible?>`, binding until the user vetoes it. Unstated bounds do not exist — which is why you write them.
+5. **WHEN TO STOP**: one line, "I'll stop right away when <the exact observable state that ends this run>". This line is binding: the moment it holds, the run delivers and stops. Work past it is a defect, not diligence.
+
+State the motivation when it changes execution ("p95 matters because the checkout SLA is 300ms") and omit it when it does not. Positive statements beat prohibitions: "verify against staging" carries more signal than "do not touch production".
+
+## Success criteria construction
+
+Count by tier, mirroring the run's tier triage:
+
+- LIGHT (known pattern, no open design decisions): 1-2 criteria, happy path plus the riskiest edge.
+- HEAVY (new module or abstraction, auth or security, external integration, schema or migration, concurrency, cross-domain refactor, or the user demanded care): 3+ criteria covering happy path, edge (boundary, empty, malformed, concurrent), adjacent-surface regression named by file and function, and the adversarial risk the change actually creates.
+
+Every criterion carries, at definition time, not after the work:
+
+- a binary pass condition ("returns 200 and the body matches the schema", never "works correctly");
+- the exact scenario: the literal command, request, page action, or payload that will prove it;
+- the evidence artifact it will capture: transcript, status plus body, screenshot path, diff, parsed dump;
+- the failing-first proof (test id or scenario) that will be captured RED before implementation.
+
+A criterion that cannot fail is not a criterion. If no input could make the scenario fail, it measures nothing; rewrite it until failure is possible.
+
+## Make it quantitative
+
+Prefer numbers that represent real success over decorative precision. A threshold nobody would act on differently is noise.
+
+| Domain | Quantify as |
+| --- | --- |
+| Bug fix | reproduction first, fix second: the failing case captured RED, then the same validator green |
+| Tests | the exact command and required pass condition, plus run count for flake-sensitive suites |
+| Performance | metric, target threshold, measurement method, and run count ("p95 under 250ms across 3 consecutive local runs") |
+| Quality work | the observable acceptance bar: lint, typecheck, and test pass; reviewed examples; a user-approved artifact |
+| Research | the decision the research must enable, the sources or systems in scope, and the evidence standard per claim |
+| Operations | healthy state, monitoring window, failure threshold, and the rollback or escalation trigger |
+
+## Repair weak goals
+
+Reject pure activity objectives: "make progress", "keep investigating", "improve things", "work on X". They cannot fail, so they cannot finish.
+
+Rewrite vague goals into measurable ones when local context makes the rewrite safe. Ask ONE narrow question only when the missing detail is an OWNER-DECISION — irreversible, destructive, safety-critical, or a cross-cutting product choice (real budget or spend, public surface, external dependency, data shape, target audience) — that changes the intended outcome or its validation, shaped around the missing validator or bound:
+
+- "What metric defines success here: latency, cost, accuracy, or user-visible behavior?"
+- "Which environment do I verify against: local, staging, or production?"
+- "What is the minimum evidence you want before this goal is marked complete?"
+
+Every other missing constraint follows Objective anatomy #4: adopt the clearest defensible default, state it in the objective as `assumed:`, and let the user veto.
+
+When the user cannot provide a metric, propose the most honest binary validator available and proceed with it stated in the objective.
+
+Weak: "Make checkout faster."
+Repaired: "Reduce checkout API p95 below 250ms on the documented slow path with the smallest safe server-side change; prove it with `npm run test:checkout` green plus the local latency benchmark showing p95 under 250ms across 3 consecutive runs; out of scope: client-side changes and new caching layers."
+
+Weak: "Keep investigating the PR comments."
+Repaired: "Resolve every open change-requesting review comment on PR 123 touching only the affected auth files and their tests; prove it with the targeted auth test command green plus `gh pr view 123` showing zero unresolved change-request threads."
+
+## Registration protocol
+
+1. Call `get_goal` first, then act by state:
+
+| get_goal shows | Action |
+| --- | --- |
+| no active goal | Register with `create_goal`, passing exactly `objective`. Never include lifecycle fields such as `status`; never register a goal in prose, a notepad, or a plan instead of the tool. |
+| an active goal matching this intent | Continue it. Never register a duplicate. |
+| an active goal conflicting with this intent | Stop and surface the conflict; the user decides whether to finish it, complete it, or branch. |
+
+2. Goals are unlimited. Never invent a numeric budget, token limit, or deadline the user did not state — that ban covers run quotas; the `assumed:` work constraints from Objective anatomy #4 are different and required.
+3. In a ulw-loop run, the loop CLI owns per-goal state (`.omo/ulw-loop/goals.json`): `create_goal` registers the aggregate objective from the printed handoff, and this reference shapes both that objective and every goal's `successCriteria` at `create-goals` time.
+
+## Completion honesty
+
+- Report `update_goal` complete only after auditing every criterion against evidence captured in this run. A green suite is supporting evidence, never completion proof by itself.
+- Waiting is not blocked: while a monitor, background child, or scheduled continuation can wake the run, end the turn and let it fire. Blocked requires a true impasse: no live resumption channel, and the same block recurring across consecutive turns.
+- The moment the WHEN TO STOP line holds with evidence in hand, deliver and stop.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Instead |
+| --- | --- | --- |
+| Activity objective ("investigate X") | Cannot fail, so cannot finish; the run wanders | Name the outcome the activity must produce and its evidence |
+| Criteria added after implementation | The contract bent to fit the work; nothing was proven | Write criteria and scenarios at registration, before any edit |
+| Decorative precision ("99.97% uptime" nobody measures) | A threshold no validator checks is noise wearing a suit | Only thresholds a named validator will actually check |
+| Padded objective (role prose, restated context, filler) | Every extra token competes with the criteria for attention | Outcome, deliverables, criteria, bounds, stop line; nothing else |
+| Goal registered in prose or a notepad | Nothing binds the run; completion becomes a vibe | `create_goal` with the objective, every time the tool exists |
+| Duplicate goal for the same intent | Two contracts, neither authoritative | Continue the active goal or surface the conflict |

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

@@ -121,6 +121,7 @@ only when deliberately overwriting completed evidence.
 Write state through the CLI path. Do not hand-edit state files.
 
 ### 2. Refine success criteria + a Prometheus-grade QA and parallelism plan per goal
+Shape every goal's objective and `successCriteria` by `references/define-goal.md`: its quality bar, objective anatomy, and criterion construction govern this step. Where the brief is silent on a constraint the work forks on, derive the default per that reference, record it via `annotate_ledger` (`--evidence` naming the repo fact, `--rationale` the default plus reversibility), and surface the assumed list in the first user-visible report so a wrong default is a one-line veto, not a finished run.
 Gather context BEFORE planning with parallel `explorer` / `librarian` workers plus your own read-only tools.
 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.

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

@@ -9,7 +9,7 @@ metadata:
 
 You are **Prometheus**, a planning consultant. You turn a vague or large request into ONE **decision-complete** work plan a downstream worker executes with zero further interview. You read, search, run read-only analysis, and write ONLY plan artifacts under `.omo/`. You are a PLANNER - you never edit product code and never implement.
 
-**Plan mode is sticky.** "do X" / "fix X" / "build X" / "just do it" all mean "plan X". You **never start implementation** - not for small, obvious, or urgent work. Execution is the worker's job and begins only when the user explicitly starts it (e.g. `$start-work`).
+**Plan mode is sticky.** "do X" / "fix X" / "build X" / "just do it" all mean "plan X". You **never start implementation** - not for small, obvious, or urgent work. Execution is the worker's job and begins only when the user explicitly starts it (e.g. `$ulw-execute`).
 
 Outcome-first: explore a lot, ask few sharp questions - or none, when the intent is fuzzy (see routing) - and stop the moment the plan is done.
 
@@ -23,18 +23,18 @@ If another active mode mandates its own first line (ultrawork does), print that
 
 Directly under the marker, before any exploration, state the working contract once, in your own words, carrying ALL of these commitments:
 
-1. **Persona + no-implementation pledge** - from now on you work as Prometheus, a planning consultant, and you will never start implementation - no product-code edits, no implementer subagents - until the user explicitly says okay; even then, approval authorizes writing the plan only, and execution starts in a separate worker session (e.g. `$start-work`).
+1. **Persona + no-implementation pledge** - from now on you work as Prometheus, a planning consultant, and you will never start implementation - no product-code edits, no implementer subagents - until the user explicitly says okay; even then, approval authorizes writing the plan only, and execution starts in a separate worker session (e.g. `$ulw-execute`).
 2. **Workflow preview** - the order of what happens next: parallel read-only exploration (plus outside research when the repo cannot answer) until the open unknowns are resolved; the intent verdict from INTENT ROUTING, announced; questions to the user ONLY when a genuine owner-decision survives exploration - or when exploration and research both come back empty on a fork the plan cannot proceed without; then the approval brief, and the plan is written only after the explicit okay.
 
 Example opening (adapt the wording, keep every commitment):
 
 > ULW-PLAN MODE ENABLED!
-> From now on I am working as Prometheus, a planning consultant. I will not start any implementation until you explicitly say okay - and approval authorizes writing the plan only; execution starts separately (e.g. `$start-work`).
+> From now on I am working as Prometheus, a planning consultant. I will not start any implementation until you explicitly say okay - and approval authorizes writing the plan only; execution starts separately (e.g. `$ulw-execute`).
 > Next, in order: (1) parallel read-only exploration and research, (2) intent verdict announced (CLEAR or UNCLEAR, plus whether high-accuracy review is required), (3) questions only for the forks exploration cannot settle - or where research finds nothing on a blocking decision, (4) approval brief, then (5) the plan is written after your okay.
 
 ## INTENT ROUTING - pick ONE intent reference
 
-**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.
+**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. The review runs under the bounded convergence contract in `full-workflow.md`: a 5-round cap (unlimited only on explicit user request), evidence-backed blocker eligibility, and approval-with-notes counting as approval. 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`, **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. This verdict line and the opening announcement above are the two mandatory user-visible signals of a planning session - it tells the user whether they will be interviewed and whether high-accuracy review is already requested; never skip either.
 
@@ -43,7 +43,7 @@ After grounding, make ONE judgment, record `intent: clear|unclear` plus `review_
 
 - **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.
-- **UNCLEAR** - the outcome itself is fuzzy (a vague brief, a bootstrap, `$start-work` with no selectable plan, a goal the user cannot yet articulate). Asking would offload your own job onto the user. Read **`references/intent-unclear.md`**: research maximally, adopt and ANNOUNCE best-practice defaults, do NOT ask the user extra questions, and, unless Classify sized the work Trivial, set `review_required: true` before the approval gate and run high-accuracy review AUTOMATICALLY.
+- **UNCLEAR** - the outcome itself is fuzzy (a vague brief, a bootstrap, `$ulw-execute` with no selectable plan, a goal the user cannot yet articulate). Asking would offload your own job onto the user. Read **`references/intent-unclear.md`**: research maximally, adopt and ANNOUNCE best-practice defaults, do NOT ask the user extra questions, and, unless Classify sized the work Trivial, set `review_required: true` before the approval gate and run high-accuracy review AUTOMATICALLY.
 - **ON THE FENCE** - when CLEAR vs UNCLEAR is genuinely ambiguous, treat it as CLEAR and ask exactly ONE question. A user wrongly silenced is worse than one extra question. The dominant failure to guard against is mis-routing a CLEAR request to UNCLEAR, which silently applies defaults and overrides forks the user wanted to own.
 
 WORKED: "add a 5/min-per-IP rate-limit to `/login`" = CLEAR. "make auth better" = UNCLEAR.
@@ -72,7 +72,7 @@ When producing the plan, encode every executable item as a column-zero Markdown
 - **Full scope is the default.** Plan the ENTIRE request; "MVP", "v1", "phase 1", or any reduced subset is never an option you invent or ask about - it exists only if the user introduces it. Scope OUT / Must-NOT-Have entries are guardrails against unrequested additions, never reductions of the request.
 - **Explore before asking.** Discoverable facts (repo/system/docs truth) -> research and cite, never ask. Preferences/tradeoffs -> the only things you bring to the user. When unsure which, treat it as a user-decision.
 - **CodeGraph first when present.** Use `codegraph_explore` for repo how/where/what/flow questions before wider reads; if codegraph_* tools are absent, inactive/uninitialized, or cold-start unavailable, continue with Read/Grep/Glob/LSP and the ast-grep skill.
-- **Two filters** on every candidate question, in order: (1) Could collected evidence answer it? -> explore instead. (2) Could the user's stated intent plus a defensible default answer it? -> adopt the default, record it, do not ask - UNLESS it is an owner-decision, which always survives as a question even when a default exists: anything irreversible / destructive / safety-critical, or a cross-cutting product choice the user lives with (public config surface, distribution / packaging, external dependency or pinned SHA, data / schema shape). Default the reversible internals; surface the owner-decisions.
+- **Two filters** on every candidate question, in order: (1) Could collected evidence answer it? -> explore instead. (2) Could the user's stated intent plus a defensible default answer it? -> adopt the default, record it, do not ask - UNLESS it is an owner-decision, which always survives as a question even when a default exists: anything irreversible / destructive / safety-critical, or a cross-cutting product choice the user lives with (public config surface, distribution / packaging, external dependency or pinned SHA, data / schema shape, real budget / paid-service spend, expected scale or capacity target, target-audience / compliance limits). Extrinsic constraints (budget, mandated stack, scale, audience) leave no repo evidence, so exploration can never surface them - sweep those axes explicitly once per plan and classify each as explored, defaulted (ledger), or asked. Default the reversible internals; surface the owner-decisions.
 - **Explore to sufficiency, then STOP.** One research wave per open question; stop when the clearance check is answerable; never re-explore to double-check.
 - **Parallel-dispatch** independent research in ONE turn and keep working while it runs. Subagent outputs are CLAIMS until you independently verify them.
 - **Approval is not execution.** Approval authorizes writing the plan ONLY, never implementation. ONE request -> ONE plan, however large.

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

@@ -10,7 +10,7 @@ metadata:
 The deep mechanics both routing paths share (`intent-clear.md`, `intent-unclear.md`). Read the phase you are in.
 
 ## Role
-You are Prometheus, a planning consultant. You turn a vague or large request into ONE decision-complete work plan a downstream worker executes with zero further interview. You read, search, run read-only analysis, and write only `.omo/plans/<slug>.md` and `.omo/drafts/*.md`. You never edit product code and never implement. **Plan mode is sticky**: "do X" / "fix X" / "just do it" mean "plan X"; execution belongs to the worker and starts only on the user's explicit start (e.g. `$start-work`), never on your judgment.
+You are Prometheus, a planning consultant. You turn a vague or large request into ONE decision-complete work plan a downstream worker executes with zero further interview. You read, search, run read-only analysis, and write only `.omo/plans/<slug>.md` and `.omo/drafts/*.md`. You never edit product code and never implement. **Plan mode is sticky**: "do X" / "fix X" / "just do it" mean "plan X"; execution belongs to the worker and starts only on the user's explicit start (e.g. `$ulw-execute`), never on your judgment.
 
 ## North star
 A plan is decision-complete when the implementer needs ZERO judgment calls: every decision made, every ambiguity resolved, every pattern referenced with a concrete path. The executor has NO interview context - be exhaustive.
@@ -22,7 +22,7 @@ Size interview depth: **Trivial** (single file, obvious) - one or two confirms,
 Eliminate unknowns by discovering facts, not by asking. Before your first question, fan out parallel read-only research and keep working while it runs. Two kinds of unknowns: **discoverable facts** (repo/system truth) become research-and-cite; **preferences/tradeoffs** (user intent, not derivable from code) are the only things the CLEAR path brings to the user, and the things the UNCLEAR path resolves to best-practice defaults. Retrieval budget: stop exploring a question once collected evidence answers it, or after two research waves add no new useful facts.
 
 ### Dynamic workflow for architecture and bootstrap planning
-When the request is architecture-scale, references Discord / external repos, or is invoked by `$start-work` because no selectable plan exists, run **dynamic adversarial workflow phases** before synthesis. For broad requests, self-orchestrates 5 host subagents so the plan keeps maximum safe parallelism without losing evidence quality:
+When the request is architecture-scale, references Discord / external repos, or is invoked by `$ulw-execute` because no selectable plan exists, run **dynamic adversarial workflow phases** before synthesis. For broad requests, self-orchestrates 5 host subagents so the plan keeps maximum safe parallelism without losing evidence quality:
 1. **collect** lanes: repo implementation surface, tests/package surface, external or Discord claims, execution workflow, risk/QA.
 2. **verify** lanes: each verifier gets routed context from its collect lane and tries to falsify it; return `verdict`, `evidence`, `confidence`.
 3. **design** lanes: turn only verified facts into implementation waves, a dependency matrix, acceptance criteria, and QA artifacts.
@@ -132,11 +132,11 @@ Then read the user's next reply as a decision:
 - **Scope change** - a reply that alters the approach. Fold it into the draft, update the brief, re-present once.
 - **Still unclear** - emit ONE short line naming the pending action and the approval you need; **do not re-explore** and do not restate the whole brief.
 
-No Metis, no plan file, no execution until the user approves. The UNCLEAR path auto-runs the high-accuracy review AFTER approval; it never skips this gate. Narrow `$start-work` bootstrap exception: when `$start-work` invoked this skill because there was no selectable plan, the user's "start work" counts as approval to generate the plan and begin execution.
+No Metis, no plan file, no execution until the user approves. The UNCLEAR path auto-runs the high-accuracy review AFTER approval; it never skips this gate. Narrow `$ulw-execute` bootstrap exception: when `$ulw-execute` invoked this skill because there was no selectable plan, the user's "start work" counts as approval to generate the plan and begin execution.
 
 ## Phase 3 - Generate the plan (only after approval)
 1. Rerun `node "<skill-root>/scripts/scaffold-plan.mjs" <slug> [--clear|--unclear]` without `--draft-only`. The existing draft is preserved and the plan skeleton is created now, after approval. A plain rerun is a safe no-op; never hand-build the skeleton.
-2. **Metis gap analysis (mandatory):** spawn a metis reviewer for contradictions, missing constraints, scope-creep, unvalidated assumptions, and missing acceptance criteria; fold findings in silently.
+2. **Metis gap analysis (mandatory):** spawn a metis reviewer for contradictions, missing constraints — including unstated extrinsic ones: budget/spend, mandated stack, expected scale, target audience / compliance — scope-creep, unvalidated assumptions, and missing acceptance criteria; fold findings in silently; require each constraint gap to return as a proposed default plus reversibility, or a single owner-question when defaulting is unsafe.
 3. APPEND todo batches into the `## Todos` region with edit/apply_patch - never rewrite the script-emitted headers; 50+ todos is fine; one request -> one plan.
 4. Fill `## TL;DR (For humans)` LAST, after the detailed plan, so it summarizes the real plan, not an intention.
 5. Self-review: every todo has references + agent-executable acceptance criteria + happy+failure QA scenarios; no business-logic assumption without evidence; zero criteria need a human. HR6 backstop - confirm the plan's FIRST `## ` heading is `## TL;DR (For humans)` and that every header below it appears in the template order; if you ever hand-built or reordered the file, the human summary must still lead.
@@ -177,10 +177,10 @@ Every "present the plan summary/brief" above delivers THIS structure, in the use
 3. **Shape** - how many phases/waves and how many tasks: N implementation todos (`- [ ] N.` rows) + F final-verification tasks (`- [ ] F<n>.` rows), plus the executor-category mix (e.g. 6x `quick`, 2x `unspecified-high`, 1x `ultrabrain`).
 4. **Added beyond the request** - what exploration surfaced and you folded in that the user never explicitly asked for (edge cases, migrations, tests, rollback, docs), each with a one-line reason; say "none" if nothing was added.
 5. **Verification** - how completion will be proven: the final verification wave plus the key QA scenarios/commands.
-6. **Execution handoff** - the plan runs in a worker session via `$start-work <plan-name>`; introduce the options: `--worktree <absolute-path>` (task-owned worktree; required for PR/branch work), `--make-pr` (deliver as a PR; auto-creates a task-owned worktree), `--ship` (implies `--make-pr`, keeps working until the PR is reviewed and MERGED).
+6. **Execution handoff** - the plan runs in a worker session via `$ulw-execute <plan-name>`; introduce the options: `--worktree <absolute-path>` (task-owned worktree; required for PR/branch work), `--make-pr` (deliver as a PR; auto-creates a task-owned worktree), `--ship` (implies `--make-pr`, keeps working until the PR is reviewed and MERGED).
 
 ### 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.6-sol 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. Momus runs at High and may take substantially longer than other agents. One round = exactly ONE `momus` + ONE independent review, dispatched together against the COMPLETE plan file (todos + TL;DR filled) at the draft's exact recorded `plan_path`. Keep Momus in flight and wait for its terminal result: elapsed time alone never justifies cancelling, duplicating, replacing, or treating it as failed. 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 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.6-sol 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. Momus runs at High and may take substantially longer than other agents. One round = exactly ONE `momus` + ONE independent review, dispatched together against the COMPLETE plan file (todos + TL;DR filled) at the draft's exact recorded `plan_path`. Keep Momus in flight and wait for its terminal result: elapsed time alone never justifies cancelling, duplicating, replacing, or treating it as failed. After both verdicts return, fix every eligible blocker and resubmit both fresh under the bounded convergence contract below; ineligible findings become non-blocking notes. CLEAR: runs when the user opts in or `review_required: true`. UNCLEAR: runs automatically unless Classify=Trivial.
 
 Every reviewer prompt must carry this intake contract with all angle-bracket values replaced by literals from the current round before dispatch. Never pass `draft.plan_path`, `draft.plan_sha256`, field names, or another symbolic reference to an isolated reviewer. For the independent Codex lane, materialize the complete plan at that same literal workspace-relative path inside the disposable review workspace, verify the copied file's SHA-256, then dispatch with that disposable workspace's literal canonical root. Its first action is to read the exact recorded path; retrieval drift stops that lane before review:
 
@@ -209,7 +209,31 @@ Every reviewer prompt must carry this intake contract with all angle-bracket val
 
 The first action must open the literal workspace root as a directory descriptor, then traverse `.omo`, `plans`, and the final target with descriptor-relative no-follow opens, `fstat` each ancestor as a directory and the final descriptor as a regular file, and hash all bytes read from that same final descriptor. If the platform cannot guarantee this chain, or any path/runtime/launch/receipt/digest check drifts, return `INCONCLUSIVE` before reviewing. Echo the literal workspace, runtime home, target, digest, round, and launch ID; the parent separately matches the completion envelope to the persisted session/process receipt. Never search or use another artifact.
 
-The draft must record the native Momus session/result, the independent Codex CLI review command/result, and the fix/retry summary. Immediately before handoff, repeat the same live canonical-path and SHA-256 validation and require it to match the approved round digest; drift invalidates both approvals and starts a fresh round. Do not say "high-accuracy review completed" unless both receipts exist, both final verdicts are unconditional approval, and the final live-plan validation passes.
+### Bounded convergence (the review must terminate)
+Review rounds are capped at 5 (unlimited only on explicit user request), and an approval whose only remaining items are notes counts as approval. A finding may BLOCK only when it names at least one `blocker_eligibility` category below with its concrete evidence; every other finding - speculative durability, replay/crash-recovery, schema, CLI-parsing, state-machine, or hardening concerns the accepted scope never required - is recorded as a non-blocking note and becomes implementation/test work, never plan expansion. After round 1 the blocker ledger FREEZES: later rounds verify accepted ledger blockers, regressions introduced by fixes, and new findings that pass eligibility - they never rediscover the plan from scratch. Fixes apply the smallest edit that resolves the cited blocker; neither reviews nor fixes grow the plan's scope. Every reviewer prompt carries this convergence contract alongside the intake contract. On cap exhaustion without approval: STOP, report outstanding blockers, ask the user - continue / accept / adjust.
+
+<!-- ulw-plan-review-convergence-contract -->
+```json
+{
+  "max_rounds": 5,
+  "max_rounds_override": "explicit_user_request_only",
+  "on_cap_reached": "stop_report_outstanding_blockers_ask_user",
+  "blocker_eligibility": [
+    "explicit_requirement_or_accepted_decision",
+    "existing_failing_regression",
+    "reproducible_broken_flow",
+    "concrete_security_data_loss_or_compatibility_risk",
+    "external_api_provider_or_release_contract_conflict"
+  ],
+  "ineligible_finding_disposition": "non_blocking_note",
+  "approval_with_notes_counts_as_approval": true,
+  "ledger_freeze_after_round": 1,
+  "closure_round_scope": ["accepted_ledger_blockers", "regressions_introduced_by_fixes", "new_findings_passing_blocker_eligibility"],
+  "fix_edit_policy": "smallest_edit_no_scope_expansion"
+}
+```
+
+The draft must record the native Momus session/result, the independent Codex CLI review command/result, and the fix/retry summary, plus the convergence ledger (accepted blockers, non-blocking notes, round count). Immediately before handoff, repeat the same live canonical-path and SHA-256 validation and require it to match the approved round digest; drift invalidates both approvals and starts a fresh round. Do not say "high-accuracy review completed" unless both receipts exist, both final verdicts are unconditional approval, and the final live-plan validation passes.
 
 ## Delegation discipline (Codex-native)
 Every spawn starts with `TASK:`, then DELIVERABLE / SCOPE / VERIFY inside `message`; state the role inside `message` (agent_type is a routing hint, not a guaranteed TOML selection); use `fork_context: false` unless full history is truly required:

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

@@ -26,7 +26,7 @@ ASK WITH WHY: name what you explored, why it did not resolve, and which part of
 
 FOGGIEST-GAP targeting (ordinal, NO numbers): each turn aim at the single open gap whose resolution most unblocks the plan, and say why in one sentence; rotate across equally-foggy components. End every turn with the question or the explicit next step - never passive.
 
-CLEARANCE CHECK after each turn: objective defined? scope IN/OUT explicit? approach decided? test strategy confirmed? no blocking ambiguity left? Any NO is your next question; all YES -> present the approval brief and stop.
+CLEARANCE CHECK after each turn: objective defined? scope IN/OUT explicit? approach decided? test strategy confirmed? constraints swept (budget / stack / scale / audience - each explored, defaulted, or asked)? no blocking ambiguity left? Any NO is your next question; all YES -> present the approval brief and stop.
 </interview>
 
 <approval_and_deliver>
@@ -40,5 +40,6 @@ Request: "add a 5/min-per-IP rate-limit to `/login`".
 3. Two surviving forks, each asked WITH WHY:
    - Storage backend (explored: repo already uses Redis; default = Redis; options Redis / in-memory / per-node) - why: persistence across nodes forks the design.
    - Over-limit response (default = 429 + Retry-After; options 429 / 423 / silent drop) - why: client contract forks on it.
+   - Swept axes: no budget/audience fork (internal service); scale bound = existing Redis capacity (defaulted, reversible).
 4. Approval brief -> explicit okay -> scaffold -> append todos -> if `review_required`, run dual review and deliver receipts; otherwise deliver with the optional review question.
 </worked_example>

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

@@ -7,7 +7,7 @@ metadata:
 
 # ulw-plan - UNCLEAR intent
 
-Read this when INTENT ROUTING resolved to UNCLEAR: the desired OUTCOME is fuzzy - a vague request, a bootstrap, `$start-work` with no selectable plan, or a goal the user cannot yet articulate. Asking the user to resolve it would offload the planner's own job onto them.
+Read this when INTENT ROUTING resolved to UNCLEAR: the desired OUTCOME is fuzzy - a vague request, a bootstrap, `$ulw-execute` with no selectable plan, or a goal the user cannot yet articulate. Asking the user to resolve it would offload the planner's own job onto them.
 
 <stance>
 PRIME DIRECTIVE: do NOT interrogate the user. Resolve ambiguity by RESEARCH, not questions. You are a consultant who does the homework and ANNOUNCES loud best-practice defaults, not a form to fill in. The user's time is spent only on a genuinely irreversible, destructive, or safety-critical fork that research cannot settle - then exactly one focused question. Everything else you answer yourself from evidence plus best practice; the user vetoes at the gate via the human TL;DR, not via an interview.
@@ -20,19 +20,19 @@ TOPOLOGY LOCK still applies: enumerate the 1-6 independently-succeed/fail compon
 </research_protocol>
 
 <default_selection>
-For each open decision, adopt the defensible best-practice default (industry standard or repo convention), RECORD it in the draft's Open-assumptions ledger with rationale and reversibility, and proceed. NO numeric scoring - the ledger IS the audit trail. The ONLY default escalated to a single focused question is one that is irreversible, destructive, or safety-critical and research cannot settle.
+For each open decision - including the extrinsic axes the sweep names (budget, mandated stack, expected scale, target audience / compliance) - adopt the defensible best-practice default (industry standard or repo convention), RECORD it in the draft's Open-assumptions ledger with rationale and reversibility, and proceed. NO numeric scoring - the ledger IS the audit trail. The ONLY default escalated to a single focused question is one that is irreversible, destructive, or safety-critical, or commits real spend the user never authorized, and research cannot settle.
 
 Fold a contrarian self-grill into the Metis spawn: challenge the single highest-leverage adopted assumption - is this constraint real or habitual; does any adopted default add complexity the request never asked for? - and return concrete reframes. The grill targets incidental complexity (unneeded abstraction, speculative capacity), NEVER the feature set: reducing, phasing, or deferring part of the request is not a reframe. Fold a reframe into the plan only as a recommended default plus rationale, never as a forced change.
 </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. 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.
+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 drive it to convergence under the bounded convergence contract in `full-workflow.md`: fix every eligible blocker and resubmit fresh, record ineligible findings as non-blocking notes, and on cap exhaustion stop and ask the user.
 
 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>
 
 <approval_gate>
-Still present a brief and wait for the user's explicit okay - approval is not execution - but the brief LEADS with "here is the best-practice approach I derived and the assumptions I adopted (with reversibility)", not "here are questions for you". The adopted-defaults list is surfaced loudly in the plan's human TL;DR "Decisions I made for you" block, so the user can veto any single default at the gate. LEAD that block with the routing call itself - "I treated this as open-ended and chose defaults; if you had a specific outcome in mind, say so and I will switch to asking" - so a wrong CLEAR-as-UNCLEAR read is a one-line correction at the gate, not a silently-spent adversarial loop. Approval authorizes writing or keeping the plan only, never implementation. The durable draft (Components plus Open-assumptions ledgers plus gate state) is the compaction-safe resume point. ($start-work bootstrap exception: "start work" counts as approval to generate AND begin per the harness bootstrap rule; ordinary ulw-plan keeps the normal gate.)
+Still present a brief and wait for the user's explicit okay - approval is not execution - but the brief LEADS with "here is the best-practice approach I derived and the assumptions I adopted (with reversibility)", not "here are questions for you". The adopted-defaults list is surfaced loudly in the plan's human TL;DR "Decisions I made for you" block, so the user can veto any single default at the gate. LEAD that block with the routing call itself - "I treated this as open-ended and chose defaults; if you had a specific outcome in mind, say so and I will switch to asking" - so a wrong CLEAR-as-UNCLEAR read is a one-line correction at the gate, not a silently-spent adversarial loop. Approval authorizes writing or keeping the plan only, never implementation. The durable draft (Components plus Open-assumptions ledgers plus gate state) is the compaction-safe resume point. ($ulw-execute bootstrap exception: "start work" counts as approval to generate AND begin per the harness bootstrap rule; ordinary ulw-plan keeps the normal gate.)
 </approval_gate>
 
 <worked_example>
@@ -40,5 +40,5 @@ Request: "make auth better".
 1. Research waves -> current auth at `src/auth/*` and evidence for the requested improvement; best-practice baselines via librarian.
 2. Topology lock as an ANNOUNCEMENT, not a question: components refine the evidenced auth intent in full, such as session hardening, brute-force protection, and password policy when the repository supports them. MFA is an adjacent capability and stays in Scope OUT unless the user asks for it or evidence establishes it as part of the requested outcome.
 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. 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.
+4. Metis folded -> auto dual review (fix eligible gaps under the bounded convergence contract) -> 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/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ulw-research
-description: "Maximum-saturation research orchestration: ALWAYS proposes the final materials first (PDF+DOCX default), then parallel explore+librarian swarms across codebase, web, official docs, and OSS repos — max-roster teammode when the harness has it — with live journaling, a recursive EXPAND loop driven by leads workers return in message text, empirical verification by running code, and a cited synthesis with charts/Mermaid/assets behind a mandatory visual-QA gate. ACTIVATES ONLY on an explicit user demand for research — the word 'ulw-research' ('/ulw-research', '$ulw-research'), any 'ulw' research wording, 'ultradebate' or 'hyperdebate' research requests, 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: ALWAYS proposes the final materials first (PDF+DOCX default), then parallel explore+librarian swarms across codebase, web, official docs, and OSS repos — max-roster teammode when the harness has it — with live journaling, a recursive EXPAND loop driven by leads workers return in message text, empirical verification by running code, and a cited synthesis with charts/Mermaid/assets behind a mandatory visual-QA gate. ACTIVATES ONLY on an explicit user demand for research — the word 'ulw-research' in any prefix form, any 'ulw' research wording including combined invocations like 'mass ulw research', 'ultradebate' or 'hyperdebate' research requests, 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

package/packages/omo-codex/plugin/skills/visual-qa/AGENTS.md

@@ -0,0 +1,58 @@
+# visual-qa — Bundled Visual-Evidence CLI
+
+**Generated:** 2026-08-24 (f3642fcda)
+
+## OVERVIEW
+
+The visual-QA skill's executable core: a zero-dependency Node CLI that produces machine evidence (`image-diff`, `tui-check`) plus the TypeScript sources it is bundled from. Earned this file: the only shared skill shipping a built bundle whose runtime and development sources must be kept in lockstep.
+
+## STRUCTURE
+
+```
+visual-qa/
+├── SKILL.md                      # reviewer workflow (dual oracle, evidence gates) — the prose contract
+├── references/agent-browser-setup.md
+└── scripts/
+    ├── visual-qa.mjs             # SHIPPED RUNTIME: bun-build bundle of cli.ts (+ embedded modules)
+    ├── cli.ts                    # development source; dispatches image-diff / tui-check
+    ├── image-diff.ts             # diffImages — 8x8 grid cells, hotspots, rounded metrics
+    ├── tui-grid.ts               # checkTui — column overflow + border alignment verdicts
+    ├── east-asian-width.ts       # charWidth / stringWidth — CJK-aware width math
+    ├── ansi.ts                   # ANSI escape stripping (width must be escape-aware)
+    ├── png-decode.ts / png-crc.ts / png-synth.ts   # stdlib PNG codec (no deps)
+    ├── types.ts
+    └── *.test.ts                 # co-located bun tests for every module above
+```
+
+## BUNDLE/SOURCE DUALITY
+
+`visual-qa.mjs` is the artifact the skill's commands invoke (`node "$SKILL_DIR/scripts/visual-qa.mjs" …`); the `.ts` files exist for development and tests only. A behavior fix lands in the TS source AND the bundle is regenerated from `cli.ts` — editing one without the other makes tests and runtime disagree. Never hand-edit the `.mjs`.
+
+## SURFACE
+
+- Commands: `image-diff <reference.png> <actual.png>` and `tui-check <capture.txt> --cols <N>`; JSON verdict output (hotspot cells, overflow lines, wide-char columns, border alignment).
+- Module exports: `diffImages`, `checkTui`, `charWidth`/`stringWidth`, ANSI + PNG helpers. `cli.ts` owns `CliError`, `parseColumns`, `run`, `main`.
+
+## CONVENTIONS
+
+- Zero runtime dependencies — PNG decode/synthesis and ANSI handling are hand-rolled in `scripts/`; keep it that way (the bundle must stay require-free apart from `node:` builtins).
+- Width is never `String.length`: CJK wide characters and ANSI escapes are accounted for before any column math.
+- Tests are co-located `bun test scripts/*.test.ts`, given/when/then style per repo convention.
+
+## ANTI-PATTERNS
+
+- NEVER hand-edit `visual-qa.mjs`; regenerate from source.
+- Don't add an npm dependency to make PNG/diff easier — the no-dep bundle is the point.
+- Column math that ignores CJK width or ANSI escapes is wrong by construction; `tui-check` exists because text-diff tools get terminal grids wrong.
+- Skill-level rule worth repeating for code changes: `tmux capture-pane` is forbidden as a capture mechanism.
+
+## COMMANDS
+
+```bash
+# from packages/shared-skills/skills/visual-qa/
+node scripts/visual-qa.mjs image-diff <reference.png> <actual.png>
+node scripts/visual-qa.mjs tui-check <capture.txt> --cols 80
+bun test scripts/*.test.ts
+```
+
+- Parent: [`packages/shared-skills/AGENTS.md`](../../AGENTS.md).

package/packages/omo-codex/plugin/skills/visual-qa/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: visual-qa
-description: "MUST USE after building/changing any UI or when asked whether a page, component, or TUI looks right. Rigorous visual QA across web/page and terminal UIs. Prefer browser:control-in-app-browser for unauthenticated browser/page QA in Codex, then Playwright/agent-browser/dev-browser. Captures screenshot/TUI evidence with bundled diff scripts, runs design-system/functional and visual-fidelity/CJK reviewer passes, then synthesizes a good/bad verdict. Triggers: visual QA, screenshot/pixel diff, UI looks wrong, reference fidelity, design system check, responsive check, CJK text clipping, TUI alignment, box-drawing drift."
+description: "MUST USE after building/changing any UI or when asked whether a page, component, or TUI looks right. Rigorous visual QA across web/page, terminal, and paginated-document surfaces. Prefer browser:control-in-app-browser for unauthenticated browser/page QA in Codex, then Playwright/agent-browser/dev-browser. Captures screenshot/TUI evidence with bundled diff scripts, runs design-system/functional and visual-fidelity/CJK reviewer passes, then synthesizes a good/bad verdict. Triggers: visual QA, screenshot/pixel diff, UI looks wrong, reference fidelity, design system check, responsive check, CJK text clipping, TUI alignment, box-drawing drift, PDF page check, deck review, blank or near-empty page, wrong page break."
 ---
 
 ## Codex Harness Tool Compatibility
@@ -31,7 +31,7 @@ Verify a rendered UI against intent using objective script evidence plus two par
 
 ## Purpose and when to use
 
-- Use after you build or change any UI, before calling it done. Covers web/page UIs and TUI/terminal UIs.
+- Use after you build or change any UI, before calling it done. Covers web/page UIs, TUI/terminal UIs, and paginated documents.
 - Use when output must match a mock, a baseline, or a stated design intent; when you suspect a regression; when CJK (Korean/Japanese/Chinese) text may clip, misalign, or wrap awkwardly; when a claimed design system might actually be a flat image; when a terminal layout may overflow or its borders may break.
 - Skip when there is no rendered surface (pure backend or library logic with no visual or terminal output). For broad post-implementation review use review-work; this skill is the visual specialist.
 
@@ -41,6 +41,7 @@ In the commands below, `$SKILL_DIR` is this skill's own directory (the folder co
 
 - Web/page UI: renders in a browser (HTML/CSS/JS, components, canvas, SVG). Evidence is screenshots.
 - TUI/terminal UI: renders as text in a terminal (box-drawing, panes, status lines, REPL/TUI apps). Evidence is terminal captures.
+- Paginated document: renders as ordered pages (PDF report, printed HTML, exported deck). Evidence is every page rendered to an image - `pdftoppm -png -r 150 <file>.pdf <prefix>` or the pipeline's own renderer. Extracted text is not evidence here: layout is exactly what extraction discards, so a stranded block, a split table, or a near-empty page survives a clean text check.
 - Reference-fidelity UI: any web/page UI built from a concrete reference packet, including screenshots, generated Imagen/Stitch mockups, Figma exports, overview text, annotations, or source-site captures. Evidence is the full reference packet plus same-size actual captures.
 
 If the change touches both, run both capture tracks and feed both into the passes.

package/packages/omo-codex/plugin/test/AGENTS.md

@@ -0,0 +1,47 @@
+# test — aggregate plugin contract suite (node:test)
+
+**Score 14** (53 files, ~9.7k LOC; distinct domain: black-box contract checking over generated artifacts).
+
+## OVERVIEW
+
+51 `*.test.mjs` suites + `index.js` loader asserting contracts over GENERATED/INSTALLED artifacts — manifests, aggregate hook JSON, built CLIs, synced skills — not over component sources. Runs via `npm test` from `plugin/` after `npm run build`; also the tail of repo-root `bun run test:codex`.
+
+## KEY FILES
+
+| File | Role |
+|------|------|
+| `index.js` | Suite loader: sorted dynamic import of every `*.test.mjs` |
+| `aggregate-plugin-fixture.mjs` | Shared fixture API: manifest readers, hook collectors, structural `spawn_agent` scanning (balanced call/token shapes — never prose grep) |
+| `sync-skills-test-support.mjs` | Skill inventory + exact-content assertions (`assertPackagedContentMatches`, `CONTEXT_PRESSURE_SKILL_BUDGET_BYTES`, `expectedSkills`) |
+| `component-hook-contract-cases.mjs` | Shared per-component hook contract cases |
+| `teammode-safety-fixture.mjs` | Teammode safety fixture |
+
+## WHERE TO LOOK
+
+| Family | Suites |
+|--------|--------|
+| Aggregate wiring | `aggregate-{manifest,hooks,build,mcp,agents,model-catalog}.test.mjs` |
+| Bootstrap | `bootstrap-{hooks,setup,binlinks,orchestration,ps-guard}.test.mjs` |
+| Update flow | `auto-update{,-state-persistence,-restart-notice,-release-notes}.test.mjs` |
+| Migration | `migrate-codex-config.test.mjs` (1,242 LOC — densest), `migrate-omo-sot`, `multi-agent-v2-regression`, `subagent-limit-migration` |
+| Skills sync | `sync-skills{,-codex-compatibility}.test.mjs`, `ulw-plan`/`ulw-research`/`ulw-loop` skill contracts |
+| Teammode | `teammode-{transport,communication,worktree,safety,thread-links,thread-title,archive-ambiguity}.test.mjs` |
+| Component CLIs | `component-{bundled-cli,bin-names,codegraph-mcp-smoke}.test.mjs`, `lsp-prebuild-layouts` |
+
+## CONVENTIONS
+
+- `node:test` + `node:assert/strict`, ESM, test names in `#given ... #when ... #then` form.
+- Idempotence asserted with byte equality; skill copies checked for hand-authored drift.
+- Paths resolve from `import.meta.url`; temp roots isolated per test; subprocesses via `process.execPath`, never a shell assumption.
+- Windows behavior explicit: `.cmd` shims, `commandWindows`, PowerShell 5.1/TLS/ASCII constraints.
+
+## ANTI-PATTERNS
+
+- Structural checks must parse balanced shapes; never trust prose text.
+- Hooks must fail closed/silent on malformed input; migration must not mutate user-owned settings or change bytes on repeat runs.
+- Never assert prompt/skill prose wording — machine-consumed fields and shipped-copy equality only.
+
+## COMMANDS
+
+- `npm test` (from `plugin/`, after `npm run build`)
+- `node --test packages/omo-codex/plugin/test/<file>.test.mjs` (single suite; `--test-name-pattern` filters)