oh-my-opencode 4.19.4 → 5.0.0-beta.10

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

@@ -136,7 +136,7 @@ No Metis, no plan file, no execution until the user approves. The UNCLEAR path a
 
 ## 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.
@@ -154,11 +154,11 @@ No Metis, no plan file, no execution until the user approves. The UNCLEAR path a
 ## Commit strategy
 ## Success criteria
 ```
-> Target 5-8 todos per wave; fewer than 3 (except the final) means under-splitting. Implementation + Test = ONE todo. Each todo carries: exhaustive References (the executor has no interview context), agent-executable Acceptance criteria, happy + failure QA scenarios each with an evidence path, and a Commit line.
+> Target 5-8 todos per wave; fewer than 3 (except the final) means under-splitting. Implementation + Test = ONE todo. Each todo carries: exhaustive References (the executor has no interview context), agent-executable Acceptance criteria, happy + failure QA scenarios each with an evidence path, a Commit line, and a `Recommended task executor category:` line - the routing verdict the executor follows, with a one-line reason, in the omo category vocabulary: `quick` (mechanical / single-file - the default for every splittable piece), `unspecified-low` (small misc), `unspecified-high` (standard multi-file feature), `visual-engineering` (frontend/UI), `writing` (docs), `git` (git ops), `deep` (hairy debugging or cross-module reasoning), `ultrabrain` (ONE genuinely hard cohesive problem, delegated whole). Prefer many small `quick`-routable todos spread across parallel waves; when splitting would sever shared reasoning, keep ONE todo routed to `deep`/`ultrabrain` - never force-split work whose parts share one insight. Harnesses without categories map by difficulty: quick/unspecified-low/writing/git = low, unspecified-high/visual-engineering = medium, deep/ultrabrain = high.
 
 ## Plan artifact producer contract
 
-When producing the plan, encode every executable item as a column-zero Markdown task row: implementation rows MUST match `- [ ] N. <title>` (where `N` is a positive decimal integer), and final-verifier rows MUST match `- [ ] F<number>. <title>`. Prose headings, numbered paragraphs, and ordinary bullets are not task substitutes and MUST NOT be counted as implementation or final-verifier tasks. Before handoff, run a structural self-check over the plan: verify that every implementation row and final-verifier row is column-zero, matches its required grammar, and appears in the intended `## Todos` or `## Final verification wave` section; verify that no prose heading or bullet is being used as a task; and repair the plan before handoff if any check fails.
+When producing the plan, encode every executable item as a column-zero Markdown task row: implementation rows MUST match `- [ ] N. <title>` (where `N` is a positive decimal integer), and final-verifier rows MUST match `- [ ] F<number>. <title>`. Prose headings, numbered paragraphs, and ordinary bullets are not task substitutes and MUST NOT be counted as implementation or final-verifier tasks. Before handoff, run a structural self-check over the plan: verify that every implementation row and final-verifier row is column-zero, matches its required grammar, and appears in the intended `## Todos` or `## Final verification wave` section; verify that no prose heading or bullet is being used as a task; verify that every implementation row carries a nested `Recommended task executor category:` line (final-verifier rows default to `unspecified-high` when unannotated); and repair the plan before handoff if any check fails.
 
 ### Final verification wave (after ALL todos)
 Runs in parallel; ALL must APPROVE; surface results and wait for the user's explicit okay before declaring complete: F1 plan compliance audit, F2 code quality review, F3 real manual QA, F4 scope fidelity.
@@ -174,13 +174,13 @@ Every "present the plan summary/brief" above delivers THIS structure, in the use
 
 1. **What this plan drives** - the work it performs, in 1-2 sentences.
 2. **End state** - the concrete things that will exist or behave differently once execution finishes.
-3. **Shape** - how many phases/waves and how many tasks: N implementation todos (`- [ ] N.` rows) + F final-verification tasks (`- [ ] F<n>.` rows).
+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).
 
 ### 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

@@ -20,13 +20,13 @@ 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>
@@ -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-plan/scripts/scaffold-plan.mjs

@@ -254,7 +254,7 @@ Your next move: <fill - e.g. approve, or run a high-accuracy review>. Full execu
 ## Verification strategy
 > Zero human intervention - all verification is agent-executed.
 - Test decision: <TDD | tests-after | none> + framework
-- Evidence: <attemptDir>/task-<N>-${slug}.<ext> (attemptDir = currentAttemptDir from 'omo ulw-loop status --json', .omo/evidence/ulw/<session>/<goalId>/a<attempt>; outside ulw-loop use .omo/evidence/)
+- Evidence: <attemptDir>/task-<N>-${slug}.<ext> (attemptDir = currentAttemptDir from 'omo-agent-toolkit ulw-loop status --json', .omo/evidence/ulw/<session>/<goalId>/a<attempt>; outside ulw-loop use .omo/evidence/)
 
 ## Execution strategy
 ### Parallel execution waves

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

@@ -157,7 +157,7 @@ Never guess the shape of the deliverable. After the decomposition and before spa
 - Propose the TEMPLATE too, chosen from the domain and the user's own context: section skeleton, citation style, length target, language, and any house style they have used before. A prior document the user points at is the strongest template signal — read it and mirror its structure and tagging.
 - Ask once, compactly: proposed format + proposed template + what each option costs. Then stop and wait. Guessing here wastes the entire assembly pass.
 
-Record the answer in the journal; it is the binding contract for Phase 5.
+Record the answer in the journal; Phase 5 opens by turning it into `design-spec.md`.
 
 ## Phase 1 — Saturation wave
 
@@ -179,7 +179,7 @@ Role protocols — embed the relevant one in each spawn message; every worker ge
 
 - **Codebase (explore), 2-4 workers.** Grep with 3+ keyword variations; structural/AST search; LSP definitions and references; file-name globs; `git log --all -S '<keyword>'` and `--grep` for history including deleted code. Cross-validate hits across tools. Report absolute file paths, patterns with `file:line`, and how findings connect.
 - **Web (librarian), 3-6 workers.** At least 10 distinct websearch queries per worker, each with a different operator or angle (see Search craft); fetch the full page for every result that matters — snippets lie. Context7 with 3+ queries per known library. grep.app and `gh search code|repos|issues` for real-world usage. Official docs via sitemap discovery (`<base>/sitemap.xml`), then targeted pages.
-- **Browsing, 0-3 workers.** Pages plain fetch cannot read (WAF, 403, Cloudflare, dynamic rendering, login): the worker loads the `ultimate-browsing` skill and escalates through its tiers — Tier-1 insane-search engine first, then Tier-2 Chrome stealth — rather than abandoning the source. Capture screenshots when visual context matters. When one blocked territory hides many leads, fan out more browsing subagents in parallel for breadth instead of serializing one worker through them.
+- **Browsing, 0-3 workers.** Pages plain fetch cannot read (WAF, 403, Cloudflare, dynamic rendering, login): the worker loads the `ultimate-browsing` skill and escalates through its tiers — Tier-1 insane-search engine first (including its Phase-2.5 archive surrogates), then Tier-2 Chrome stealth — rather than abandoning the source. Capture screenshots when visual context matters. **Provenance is part of the claim**: when a source came back with `provenance` of `snapshot` (an archive copy), cite it with its `snapshot_timestamp` and never state it as the current live page; content from a `proxy` route is `untrusted` and needs a second independent route before any claim rests on it. When one blocked territory hides many leads, fan out more browsing subagents in parallel for breadth instead of serializing one worker through them.
 - **Repo deep-dive (librarian), 0-2 workers.** Shallow-clone the most relevant repos to `${TMPDIR:-/tmp}`, pin the HEAD SHA, read core modules, follow call chains, return SHA-pinned permalinks.
 
 Example spawn (codebase axis; librarian, browsing, and repo-dive follow the same contract with their own protocol):
@@ -220,7 +220,7 @@ The Phase 0 core question is the fixed goal of the run and never drifts. An excu
 
 Interest alone is not a trigger. Anything without one stays a queued lead in `expansion-log.md`, and the wave plan continues.
 
-**Budget the dive before you take it.** State the worker count and the probe count for this level in the ENTER row. An excursion may spawn at most ONE nested sub-excursion; a third level means the thing has become its own research question — surface immediately and either promote it to a real axis with its own worker or record it as an out-of-scope gap in `SYNTHESIS.md`. When the `ulw-loop` skill is driving the run, a promotion is `omo ulw-loop steer --kind add_subgoal --title "<axis>" --objective "<what it must answer>" --evidence "<what surfaced it>" --rationale "<why the plan changes>"`.
+**Budget the dive before you take it.** State the worker count and the probe count for this level in the ENTER row. An excursion may spawn at most ONE nested sub-excursion; a third level means the thing has become its own research question — surface immediately and either promote it to a real axis with its own worker or record it as an out-of-scope gap in `SYNTHESIS.md`. When the `ulw-loop` skill is driving the run, a promotion is `omo-agent-toolkit ulw-loop steer --kind add_subgoal --title "<axis>" --objective "<what it must answer>" --evidence "<what surfaced it>" --rationale "<why the plan changes>"`.
 
 **EXIT (surface) the moment any of these holds** — you do not need all of them:
 
@@ -229,7 +229,7 @@ Interest alone is not a trigger. Anything without one stays a queued lead in `ex
 - The finding stops moving any claim's status — diminishing return is an exit, not a reason to push harder.
 - The level's stated budget is spent.
 
-**Fold back on the way out.** Every EXIT writes one line saying what the excursion changed in the top-level answer, and `none — <reason>` is a legitimate, required outcome; an excursion whose result is silently dropped is a lost run. Update the parent claim node or axis digest with the result, then mirror the whole excursion into the loop ledger — `omo ulw-loop steer --kind annotate_ledger --evidence "<what the excursion observed>" --rationale "<what it changed, or none>"`, and `omo ulw-loop record-evidence --goal-id <id> --criterion-id <id> --status pass|fail|blocked --evidence "<artifact>"` when it settled a criterion. After a compaction, `omo ulw-loop status --json` plus `excursion-log.md` tell you which excursions are still open.
+**Fold back on the way out.** Every EXIT writes one line saying what the excursion changed in the top-level answer, and `none — <reason>` is a legitimate, required outcome; an excursion whose result is silently dropped is a lost run. Update the parent claim node or axis digest with the result, then mirror the whole excursion into the loop ledger — `omo-agent-toolkit ulw-loop steer --kind annotate_ledger --evidence "<what the excursion observed>" --rationale "<what it changed, or none>"`, and `omo-agent-toolkit ulw-loop record-evidence --goal-id <id> --criterion-id <id> --status pass|fail|blocked --evidence "<artifact>"` when it settled a criterion. After a compaction, `omo-agent-toolkit ulw-loop status --json` plus `excursion-log.md` tell you which excursions are still open.
 
 **Anti-drift.** After every EXIT, re-read the core question in the journal and confirm the run still answers it. Three consecutive excursions that changed nothing end excursions for the run: converge on what you have.
 
@@ -311,27 +311,31 @@ The format answered at the Phase 0 gate is binding. Absent an explicit user over
 
 | Target | How |
 |---|---|
-| PDF (default) | Author the report as one self-contained HTML file, then print it headless: `chrome --headless --disable-gpu --no-pdf-header-footer --print-to-pdf=<out.pdf> file://<report.html>`. For CJK, embed a real webfont (Pretendard, Noto Sans KR) instead of trusting system fallbacks. `uv run --with weasyprint python` is the fallback renderer. |
+| PDF (default) | Author the report as one self-contained HTML file, then print it headless: `chrome --headless --disable-gpu --no-pdf-header-footer --print-to-pdf=<out.pdf> file://<report.html>`. Embed the `design-spec.md` fonts as real webfonts (CJK included) instead of trusting system fallbacks. `uv run --with weasyprint python` is the fallback renderer. |
 | DOCX (default) | `pandoc <report.md> -o <out.docx>`, adding `--reference-doc=<template.docx>` when the user has a house style; `uv run --with python-docx python` when pandoc is unavailable. Charts and Mermaid renders go in as images. |
 | Slides / deck | `uv run --with python-pptx python` — one claim per slide, a chart or diagram per claim. |
 | Standalone HTML / Markdown | The authored source itself. |
 
-Asset workers (background, parallel) — a research report without visuals is a wall of text nobody reads:
+**Write `design-spec.md` the moment the format gate is answered — before any asset worker spawns.** It is the one design contract every asset and assembly worker receives: template family (a document the user pointed at is the strongest signal — mirror its structure and register; absent one, default to the clean analyst-report register — restrained accent palette, generous margins, styled section headings, no emoji, no clipart), accent palette, body/heading fonts (a real CJK webfont — Pretendard, Noto Sans KR — when the report language needs one), and the figure standard below. One font family and one palette govern prose, charts, Mermaid, and generated images alike; a diagram rendering in a random default font inside a styled report is a defect, not a style choice.
+
+**The figure standard — binding for every image, chart, and diagram.** Each figure sits in a fixed-size container styled from the spec (border, background, caption); the image scales to fit entirely inside it with its original aspect ratio preserved — object-fit: contain semantics — never stretched, never cropped, never spilling out. Every chart carries a title, axis labels, units, and value labels in the report's language; a bare number the reader cannot name is a defect.
+
+Asset workers (background, parallel, each fed `design-spec.md`) — visuals are the DEFAULT deliverable of this phase, not garnish the user must ask for; a delivered report without figures is an incomplete run:
 
 - **Charts for every quantitative finding, computed from real data.** Pull the numbers into an actual table first (CSV/JSON under `$SESSION_DIR`), then plot from that table, never from prose. Follow the data-scientist tool doctrine — numpy always, Polars for filtering/sorting/transforms, DuckDB for joins/aggregations/window functions, never pandas — and load the `data-scientist` skill when this session has it: `uv run --with numpy --with polars --with duckdb --with pyarrow --with matplotlib python`. Keep `pyarrow` in that set — the DuckDB-to-Polars handoff (`.pl()`) fails without it, and `.df()` fails without pandas, so hand data across through `.pl()`, never `.df()`. Save to `$SESSION_DIR/assets/`.
-- **Mermaid graphs** for process, architecture, argument, timeline, and evidence-flow structure. Render each to SVG and confirm the file exists before the document references it.
-- **Generated visuals** through the imagegen skill when a diagram, cover, or narrative visual earns its place.
+- **Mermaid graphs** for process, architecture, argument, timeline, and evidence-flow structure, themed to the spec's fonts and palette. Render each to SVG and confirm the file exists before the document references it.
+- **Generated visuals through the imagegen skill whenever the session has it:** a cover plus a concept illustration per major theme, prompted from the spec's style, palette, and mood — document-styled illustration, never generic stock art dropped into a designed page.
 - **Full-page screenshots** of the top 5-10 sources (browsing worker) as provenance you can show.
 
 **Verify the asset manifest before rendering.** List every asset the document references, assert each file exists and is non-empty on disk, and re-render whatever is missing. A document that renders with three broken diagrams is a document you will publish twice.
 
-Assembly worker — `task(category="deep", load_skills=["frontend", "visual-qa", "open-design", "data-scientist", "imagegen", "ulw-loop"], run_in_background=true, ...)`: before writing, read every available design and visualization skill and apply it — the report is a designed artifact, not a text dump. Use the template the user approved; absent a stronger house style the default skeleton is executive summary → key findings by theme → detailed analysis (quotes under 20 words with attribution, charts, Mermaid graphs, generated visuals, SHA-pinned permalinks, verification results) → comparative analysis when options compete → numbered sources with access dates → methodology appendix (workers, waves, searches, verifications, debate rounds) → correction log naming what verification overturned. Write it long and specific: every claim cites `[Source N]`, and the sources section lists every source the run actually used rather than a curated few.
+Assembly worker — `task(category="deep", load_skills=["frontend", "visual-qa", "open-design", "data-scientist", "imagegen", "ulw-loop"], run_in_background=true, ...)`: before writing, read every available design and visualization skill and apply it — the report is a designed artifact, not a text dump; the worker's prompt carries `design-spec.md`. Use the template the user approved; absent a stronger house style the default skeleton is executive summary → key findings by theme → detailed analysis (quotes under 20 words with attribution, charts, Mermaid graphs, generated visuals, SHA-pinned permalinks, verification results) → comparative analysis when options compete → numbered sources with access dates → methodology appendix (workers, waves, searches, verifications, debate rounds) → correction log naming what verification overturned. Write it long and specific: every claim cites `[Source N]`, and the sources section lists every source the run actually used rather than a curated few.
 
 ### The delivery gate — visual QA must PASS
 
 Nothing reaches the user until the gate passes:
 
-**Visual QA (always).** Render the produced artifact back to images — PDF pages to PNG, the HTML in a real browser — and look at them: missing or broken figures, clipped tables, overflowing CJK text, blank pages, unreadable chart labels, wrong page breaks. Fix and re-render until the pages are clean. Reading the source markup is not visual QA; inspect the pixels.
+**Visual QA (always).** Render the produced artifact back to images — PDF pages to PNG, the HTML in a real browser — and look at them: missing or broken figures, images stretched or spilling their containers, diagram or chart text rendered off the spec's font or palette, clipped tables, overflowing CJK text, blank pages, unlabeled chart values, wrong page breaks. Fix and re-render until the pages are clean. Reading the source markup is not visual QA; inspect the pixels.
 
 Then deliver: the artifact plus a compact chat-readable summary of what it says — the answer in a few sentences, the numbers that matter, and what to look at first. The document is the deliverable; the summary is what gets it read.
 
@@ -387,6 +391,7 @@ High-yield combinations: official docs (`site:<docs domain>`), GitHub implementa
 | A derived estimate presented as a measured number | MEASURED / ASSUMED / DERIVED lineage on every quantitative claim, plus a sensitivity line |
 | Delivering before the delivery gates pass | Visual QA on rendered pages always, plus the harness's proofread gate — a typo the user finds means a gate did not run |
 | Referencing an asset that is not on disk | Verify the asset manifest before rendering; re-render whatever is missing |
+| A figure stretched, cropped, or styled off the report's design language | `design-spec.md` binds every asset: fixed containers, contain-fit with aspect preserved, spec fonts and palette in charts and Mermaid |
 | Chasing an interesting find with no ENTER trigger | Excursions need a named trigger; everything else stays a queued lead |
 | An excursion that never came back, or drifted into a new mission | EXIT rules are unconditional; depth 3 means promote it to an axis or record it as a gap |
 | An excursion whose result was never folded back | Every EXIT writes what it changed in the top-level answer, `none` included, and mirrors into the loop ledger |

package/packages/omo-codex/plugin/test/aggregate-agents.test.mjs

@@ -15,103 +15,25 @@ const agentSchemaKeys = new Set([
 	"developer_instructions",
 ]);
 
+// `includes` entries below are machine-consumed tokens only: EVIDENCE_RECORDED is the sentinel the
+// lazycodex-executor-verify SubagentStop hook greps from worker messages; recommendation, blockers,
+// codeQualityStatus, not_applicable, surfaceEvidence, and adversarialCases are fields the ulw-loop
+// quality gate parses out of reviewer/QA reports; <attemptDir>/<goalId>-code-review.md and
+// -manual-qa.md are the artifact names the ulw-loop spawn guard requires before a gate-reviewer
+// spawn; currentAttemptDir is a field of `ulw-loop status --json`.
 const lazycodexAgentInvariants = new Map([
-	[
-		"explorer.toml",
-		{
-			model: "gpt-5.6-luna",
-			effort: "low",
-			includes: [/Read-only/, /working tree/, /rg/],
-		},
-	],
-	[
-		"librarian.toml",
-		{
-			model: "gpt-5.6-luna",
-			effort: "low",
-			includes: [/Read-only/, /SHA-pinned GitHub permalink/, /external/],
-		},
-	],
-	[
-		"metis.toml",
-		{
-			model: "gpt-5.6-sol",
-			effort: "high",
-			includes: [/pre-planning analyst/i, /contradictions/, /Read-only/],
-		},
-	],
-	[
-		"momus.toml",
-		{
-			model: "gpt-5.6-terra",
-			effort: "high",
-			includes: [/plan reviewer/i, /OKAY, ITERATE, or REJECT/, /Read-only/],
-		},
-	],
-	[
-		"plan.toml",
-		{
-			model: "gpt-5.6-sol",
-			effort: "high",
-			includes: [/strategic planning consultant/i, /\.omo\/plans\/<slug>\.md/, /never implements/i],
-		},
-	],
-	[
-		"lazycodex-worker-low.toml",
-		{
-			model: "gpt-5.6-luna",
-			effort: "high",
-			includes: [/EVIDENCE_RECORDED: <path>/, /low-difficulty/i, /smallest correct change/i],
-		},
-	],
-	[
-		"lazycodex-worker-medium.toml",
-		{
-			model: "gpt-5.6-terra",
-			effort: "high",
-			includes: [/EVIDENCE_RECORDED: <path>/, /medium-difficulty/i, /smallest correct change/i],
-		},
-	],
-	[
-		"lazycodex-worker-high.toml",
-		{
-			model: "gpt-5.6-sol",
-			effort: "medium",
-			includes: [/EVIDENCE_RECORDED: <path>/, /high-difficulty/i, /smallest correct change/i],
-		},
-	],
-	[
-		"lazycodex-clone-fidelity-reviewer.toml",
-		{
-			model: "gpt-5.6-terra",
-			effort: "high",
-			includes: [/recommendation/, /blockers/, /\.omo\/evidence\/<goal>-clone-fidelity\.md/],
-		},
-	],
-	[
-		"lazycodex-code-reviewer.toml",
-		{
-			model: "gpt-5.6-terra",
-			effort: "medium",
-			includes: [/codeQualityStatus/, /recommendation/, /<attemptDir>\/<goalId>-code-review\.md/, /currentAttemptDir/],
-		},
-	],
-	[
-		"lazycodex-qa-executor.toml",
-		{
-			model: "gpt-5.6-luna",
-			effort: "high",
-			includes: [/not_applicable/, /surfaceEvidence/, /adversarialCases/, /<attemptDir>\/<goalId>-manual-qa\.md/],
-		},
-	],
-	[
-		"lazycodex-gate-reviewer.toml",
-		{
-			model: "gpt-5.6-sol",
-			effort: "low",
-			includes: [/APPROVE\/REJECT/, /blockers/, /<attemptDir>\/<goalId>-gate-review\.md/, /currentAttemptDir/],
-		},
-	],
+	["explorer.toml", { model: "gpt-5.6-luna", effort: "low" }],
+	["librarian.toml", { model: "gpt-5.6-luna", effort: "low" }],
+	["metis.toml", { model: "gpt-5.6-sol", effort: "high" }],
+	["momus.toml", { model: "gpt-5.6-terra", effort: "high" }],
+	["plan.toml", { model: "gpt-5.6-sol", effort: "high" }],
+	["lazycodex-worker-low.toml", { model: "gpt-5.6-luna", effort: "high", includes: [/EVIDENCE_RECORDED: <path>/] }],
+	["lazycodex-worker-medium.toml", { model: "gpt-5.6-terra", effort: "high", includes: [/EVIDENCE_RECORDED: <path>/] }],
+	["lazycodex-worker-high.toml", { model: "gpt-5.6-sol", effort: "medium", includes: [/EVIDENCE_RECORDED: <path>/] }],
+	["lazycodex-clone-fidelity-reviewer.toml", { model: "gpt-5.6-terra", effort: "high", includes: [/recommendation/, /blockers/] }],
+	["lazycodex-code-reviewer.toml", { model: "gpt-5.6-terra", effort: "medium", includes: [/codeQualityStatus/, /recommendation/, /<attemptDir>\/<goalId>-code-review\.md/, /currentAttemptDir/] }],
+	["lazycodex-qa-executor.toml", { model: "gpt-5.6-luna", effort: "high", includes: [/not_applicable/, /surfaceEvidence/, /adversarialCases/, /<attemptDir>\/<goalId>-manual-qa\.md/] }],
+	["lazycodex-gate-reviewer.toml", { model: "gpt-5.6-sol", effort: "low", includes: [/blockers/, /currentAttemptDir/] }],
 ]);
 
 const externalSourceTokenPattern = new RegExp(
@@ -156,7 +78,6 @@ test("#given bundled Codex agents #when components/ultrawork/agents directory is
 		}
 	}
 });
-
 test("#given bundled agent TOMLs #when nickname_candidates are inspected #then they use only the codex-accepted charset", async () => {
 	// given: codex_app_server ignores a role whose nickname has characters outside
 	// ASCII letters, digits, spaces, hyphens, underscores (observed live in task-15 QA)
@@ -174,16 +95,6 @@ test("#given bundled agent TOMLs #when nickname_candidates are inspected #then t
 	}
 });
 
-test("#given planner agent prompt #when inspected #then generated artifacts stay under .omo", async () => {
-	const prompt = await readFile(join(root, "components", "ultrawork", "agents", "plan.toml"), "utf8");
-
-	assert.match(prompt, /\.omo\/plans\/<slug>\.md/);
-	assert.match(prompt, /<attemptDir>\/task-<N>-<slug>\.<ext>/);
-	assert.match(prompt, /\.omo\/evidence\/ulw\/<session>\/<goalId>\/a<attempt>/);
-	assert.doesNotMatch(prompt, /(?<!\.omo\/)plans\/<slug>\.md/);
-	assert.doesNotMatch(prompt, /(?<!\.omo\/)evidence\/task-/);
-});
-
 test("#given lazycodex agent prompts #when inspected #then each role pins model effort and evidence discipline", async () => {
 	const agentsDir = join(root, "components", "ultrawork", "agents");
 
@@ -197,73 +108,8 @@ test("#given lazycodex agent prompts #when inspected #then each role pins model
 		assert.doesNotMatch(prompt, /^blocking\s*=/m);
 		assert.doesNotMatch(prompt, externalSourceTokenPattern);
 
-		for (const pattern of invariant.includes) {
+		for (const pattern of invariant.includes ?? []) {
 			assert.match(prompt, pattern, `${fileName} must include ${pattern}`);
 		}
 	}
 });
-
-test("#given LazyCodex reviewer prompts #when inspected #then anti-slop review coverage is required", async () => {
-	const agentsDir = join(root, "components", "ultrawork", "agents");
-	const codeReviewer = await readFile(join(agentsDir, "lazycodex-code-reviewer.toml"), "utf8");
-	const gateReviewer = await readFile(join(agentsDir, "lazycodex-gate-reviewer.toml"), "utf8");
-
-	assert.match(codeReviewer, /remove-ai-slops/);
-	assert.match(codeReviewer, /programming/);
-	assert.match(codeReviewer, /load or consult/);
-	assert.match(codeReviewer, /documented criteria/);
-	assert.match(codeReviewer, /violates either skill perspective/);
-	assert.match(codeReviewer, /overfit\/slop review pass/);
-	assert.match(codeReviewer, /deletion-only tests/);
-	assert.match(codeReviewer, /tests that merely verify a requested removal/);
-	assert.match(codeReviewer, /tautological tests/);
-	assert.match(codeReviewer, /mirror implementation constants/);
-	assert.match(codeReviewer, /unnecessary production data extraction, parsing, or normalization/);
-	assert.match(codeReviewer, /false confidence/);
-
-	assert.match(gateReviewer, /remove-ai-slops/);
-	assert.match(gateReviewer, /programming/);
-	assert.match(gateReviewer, /load or consult/);
-	assert.match(gateReviewer, /documented criteria/);
-	assert.match(gateReviewer, /Run the `remove-ai-slops`/);
-	assert.match(gateReviewer, /Apply the `programming`/);
-	assert.match(gateReviewer, /overfit\/slop pass yourself/);
-	assert.match(gateReviewer, /tests that merely verify a requested removal/);
-	assert.match(gateReviewer, /deletion-only/);
-	assert.match(gateReviewer, /tautological/);
-	assert.match(gateReviewer, /implementation-mirroring tests/);
-	assert.match(gateReviewer, /unnecessary production extraction, parsing, or normalization/);
-
-	const directPassIndex = gateReviewer.indexOf("overfit/slop pass yourself");
-	const reportCoverageIndex = gateReviewer.indexOf("Then confirm the code review report");
-	assert.notEqual(directPassIndex, -1);
-	assert.notEqual(reportCoverageIndex, -1);
-	assert.ok(
-		directPassIndex < reportCoverageIndex,
-		"gate reviewer must perform the overfit/slop pass directly before checking report coverage",
-	);
-});
-
-test("#given done-gate reviewer prompts #when inspected #then burden of proof is approve-unless-cited and reject priors are gone", async () => {
-	const agentsDir = join(root, "components", "ultrawork", "agents");
-	const gateReviewer = await readFile(join(agentsDir, "lazycodex-gate-reviewer.toml"), "utf8");
-	const qaExecutor = await readFile(join(agentsDir, "lazycodex-qa-executor.toml"), "utf8");
-	const codeReviewer = await readFile(join(agentsDir, "lazycodex-code-reviewer.toml"), "utf8");
-
-	assert.match(gateReviewer, /APPROVE unless you can cite/);
-	assert.match(gateReviewer, /violatedCriterion/);
-	assert.match(gateReviewer, /evidencePointer/);
-	assert.match(gateReviewer, /top blockers inline/);
-	assert.match(gateReviewer, /is a NOTE, not a blocker/);
-	assert.match(gateReviewer, /You do NOT check/);
-	assert.doesNotMatch(gateReviewer, /Assume the work has already failed/);
-	assert.doesNotMatch(gateReviewer, /Return exactly one recommendation: APPROVE\/REJECT\./);
-
-	assert.match(qaExecutor, /one-line reason/);
-	assert.match(qaExecutor, /rejecting a legitimately untriggered class is itself an error/);
-	assert.doesNotMatch(qaExecutor, /Trust nothing\./);
-
-	assert.match(codeReviewer, /MEDIUM by default/);
-	assert.doesNotMatch(codeReviewer, /Treat useless tests or needless production complexity as CRITICAL\/HIGH/);
-});
-

package/packages/omo-codex/plugin/test/aggregate-hooks.test.mjs

@@ -84,7 +84,7 @@ test("#given aggregate SubagentStop hooks #when inspected #then start-work and L
 	assert.equal(verifierGroups.length, 1);
 	assert.equal(verifierGroups[0]?.groupIndex, 0);
 	assert.equal(verifierGroups[0]?.handler.timeout, 10);
-	assert.match(verifierGroups[0]?.handler.statusMessage ?? "", /^\(OmO [^)]+\) Verifying LazyCodex Executor Evidence$/);
+	assert.match(verifierGroups[0]?.handler.statusMessage ?? "", /\S/);
 });
 
 test("#given aggregate PostCompact hooks #when hooks are inspected #then LSP diagnostics cache reset is registered", async () => {
@@ -100,7 +100,7 @@ test("#given aggregate PostCompact hooks #when hooks are inspected #then LSP dia
 
 	// then
 	assert.equal(lspPostCompactHooks.length, 1);
-	assert.match(lspPostCompactHooks[0]?.handler.statusMessage ?? "", /^\(OmO [^)]+\) Resetting LSP Diagnostics Cache$/);
+	assert.match(lspPostCompactHooks[0]?.handler.statusMessage ?? "", /\S/);
 });
 
 test("#given aggregate hook commands #when inspected #then every command exposes a Codex status message", async () => {
@@ -142,23 +142,6 @@ test("#given component hook commands #when inspected #then standalone packages e
 	assert.deepEqual(missingStatusMessages, []);
 });
 
-test("#given hook status messages #when inspected #then labels describe OMO responsibilities instead of the hook runner", async () => {
-	// given
-	const componentHooks = await readComponentHookManifests();
-
-	// when
-	const commandHooks = [
-		...(await readAggregateCommandHooks()),
-		...componentHooks.flatMap(({ source, hooks }) => collectCommandHooks(hooks, source)),
-	];
-	const genericStatusMessages = commandHooks
-		.filter(({ handler }) => typeof handler.statusMessage !== "string" || /\bhook\b/i.test(handler.statusMessage))
-		.map(hookLocation);
-
-	// then
-	assert.deepEqual(genericStatusMessages, []);
-});
-
 test("#given aggregate OMO plugin is enabled #when hooks are inspected #then shell guidance and ulw-loop guard are registered", async () => {
 	// given
 	const manifests = await readAggregateHookManifests();
@@ -169,9 +152,7 @@ test("#given aggregate OMO plugin is enabled #when hooks are inspected #then she
 
 	// then
 	assert.match(text, /components\/git-bash\/dist\/cli\.js/);
-	assert.match(text, /Recommending Git Bash MCP/);
 	assert.match(text, /hook post-compact/);
-	assert.match(text, /Resetting Git Bash MCP Reminder/);
 	assert.match(text, /components\/ulw-loop\/dist\/cli\.js/);
 	assert.match(text, /hook pre-tool-use/);
 	assert.deepEqual(preToolUseGroups.map((group) => group.matcher), [
@@ -221,7 +202,6 @@ test("#given aggregate SessionStart hooks #when inspected #then LazyCodex auto-u
 	// then
 	assert.equal(autoUpdateGroup?.matcher, "^startup$");
 	assert.match(text, /scripts\/auto-update\.mjs/);
-	assert.match(text, /Checking Auto Update/);
 	assert(sessionStartCommands.some((command) => command.includes("scripts/auto-update.mjs")));
 });
 
@@ -265,7 +245,7 @@ test("#given aggregate PostToolUse hooks #when inspected #then CodeGraph init gu
 	// then
 	assert.equal(codegraphPostToolUseHooks.length, 1);
 	assert.equal(codegraphPostToolUseHooks[0]?.matcher, "^(codegraph[._].*|mcp__codegraph__.*)$");
-	assert.match(codegraphPostToolUseHooks[0]?.handler.statusMessage ?? "", /^\(OmO [^)]+\) Checking CodeGraph Init Guidance$/);
+	assert.match(codegraphPostToolUseHooks[0]?.handler.statusMessage ?? "", /\S/);
 });
 
 test("#given aggregate PostToolUse hooks #when inspected #then thread title hygiene is registered for created Codex threads", async () => {
@@ -282,7 +262,7 @@ test("#given aggregate PostToolUse hooks #when inspected #then thread title hygi
 	// then
 	assert.equal(threadTitleHooks.length, 1);
 	assert.equal(threadTitleHooks[0]?.matcher, "^(create_thread|codex_app\\.create_thread)$");
-	assert.match(threadTitleHooks[0]?.handler.statusMessage ?? "", /^\(OmO [^)]+\) Checking Thread Title Hygiene$/);
+	assert.match(threadTitleHooks[0]?.handler.statusMessage ?? "", /\S/);
 });
 
 test("#given aggregate plugin packaging #when inspected #then hooks and compatibility sentinels stay Python-free", async () => {