oh-my-opencode 4.15.1 → 4.16.1

package/dist/skills/programming/references/logging.md

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

package/dist/skills/start-work/SKILL.md

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

package/dist/skills/ulw-plan/SKILL.md

@@ -9,18 +9,18 @@ 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, and not through a subagent: delegated implementation is still implementation. Execution belongs to a separate worker session that only the user starts (e.g. `$start-work`).
 
 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.
 
 ## INTENT ROUTING - pick ONE intent reference
 
-Before routing, parse review modifiers separately. If the user says "high accuracy", "ultra high accuracy", "고정밀", "deep review", or equivalent, set `review_required: true` in the draft. This does NOT choose CLEAR/UNCLEAR and does NOT suppress interview; it only makes the high-accuracy review gate required after the plan exists.
+**Review modifiers are a gate trigger, not a style cue.** If the user says "high accuracy", "ultra high accuracy", "고정밀", "deep review", or equivalent - in ANY turn, even appended to a follow-up question and even after the plan already exists - set `review_required: true` in the draft: the dual high-accuracy review (native `momus` + the independent Oracle review) is now REQUIRED before handoff, and if the plan already exists you run it this same turn. Answering the current question more carefully does NOT satisfy it. This does NOT choose CLEAR/UNCLEAR and does NOT suppress interview.
 
 After grounding, make ONE judgment, record `intent: clear|unclear` plus `review_required`, **ANNOUNCE both to the user in one line**, then load ONE intent reference (you ALSO read `references/full-workflow.md` for the shared mechanics - see below). The test keys on whether the desired **OUTCOME** is clear, NOT on request length. The announcement is the user's first signal of whether they will be interviewed and whether high-accuracy review is already requested - never skip it.
 
-> "Intent: **CLEAR**, review required — you specified the endpoint and asked for high accuracy. I will ask only the genuine forks, then run the high-accuracy review after approval."
-> "Intent: **UNCLEAR**, review required — 'make auth better' is open-ended and you asked for high accuracy. I will choose best-practice defaults, then run the high-accuracy review automatically."
+> "Intent: **CLEAR**, review required - you specified the endpoint and asked for high accuracy. I will ask only the genuine forks, then run the high-accuracy review after approval."
+> "Intent: **UNCLEAR**, review required - 'make auth better' is open-ended and you asked for high accuracy. I will choose best-practice defaults, then run the high-accuracy review automatically."
 
 - **OVERRIDE - explicit ask wins:** if the user explicitly asks to be questioned or interviewed ("ask me", "interview me", "why aren't you asking me" - in any language), route **CLEAR**, run the interview, and turn the adopt-default filter OFF: the user has claimed the forks, so every surviving one is ASKED, not defaulted. This beats the OUTCOME test below, even on a fuzzy brief.
 - **CLEAR** - the user knows the outcome; the only open items are preferences/tradeoffs the repo cannot answer (genuine owner-decisions). Read **`references/intent-clear.md`**: ask the surviving forks with WHY, run the normal approval gate, and offer high-accuracy review only when `review_required` is false.
@@ -67,7 +67,7 @@ Fan out read-only research before deciding. Every delegated prompt names TASK /
 task(subagent_type="explore", description="Map the implementation surface", prompt="TASK: act as an explorer. DELIVERABLE: ... SCOPE: ... VERIFY: ...")
 ```
 
-Roles: `explore` (internal patterns/conventions/tests), `librarian` (external docs/contracts), `metis` (gap analysis), `momus` (high-accuracy plan review). Full delegation/wait/fallback discipline is in `references/full-workflow.md`.
+Roles - the ONLY subagents you may spawn (all read-only, plus `oracle` for the high-accuracy review): `explore` (internal patterns/conventions/tests), `librarian` (external docs/contracts), `metis` (gap analysis), `momus` (high-accuracy plan review). Never dispatch with `category=` - categories spawn implementers - and never instruct a child to edit files. Full delegation/wait/fallback discipline is in `references/full-workflow.md`.
 
 ## Stop rules
 

package/dist/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 - directly or through a subagent. **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.
 
 ## 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.
@@ -36,7 +36,7 @@ Make ONE judgment and follow ONE reference. Review modifiers are not routing sig
 - CLEAR -> `intent-clear.md`: run the **two filters** on every candidate question; ask only surviving forks (owner-decisions), with WHY.
 - UNCLEAR -> `intent-unclear.md`: research maximally, adopt announced best-practice defaults, do not ask the user extra questions.
 
-If a draft/plan already exists and the user asks for high-accuracy review, high-accuracy planning, or to make the plan more accurate, do not reroute from scratch unless the scope changed. Load the draft, preserve its recorded `intent`, set `review_required: true`, update stale plan content if needed, then run the required review loop against the current plan.
+If a draft/plan already exists and the user says a review modifier - even appended to an otherwise unrelated follow-up question - or asks to make the plan more accurate, do not reroute from scratch unless the scope changed. Load the draft, preserve its recorded `intent`, set `review_required: true`, answer the question if one was asked, update stale plan content if needed, then run the required review loop against the current plan in that same turn. A more rigorous answer is not a substitute for the review.
 
 Both paths record `intent`, `review_required`, and decisions to `.omo/drafts/<slug>.md` as they go - long sessions outlive your context, and plan generation reads the draft, not your memory.
 
@@ -52,7 +52,7 @@ 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 `$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; execution then begins per the harness's start-work rule - never run by the planning agent itself.
 
 ## Phase 3 - Generate the plan (only after approval)
 1. RUN `node "<skill-root>/scripts/scaffold-plan.mjs" <slug> [--clear|--unclear]` (replace `<skill-root>` with this skill's own directory) to create the draft + the plan skeleton (human TL;DR on top, every header below). Run it ONCE here; a plain re-run on an existing plan is a safe no-op that preserves your appended todos, so resuming after compaction never crashes or clobbers. If it refuses because a same-named non-artifact file exists, pick a different `<slug>` rather than `--reset` over a human file you did not create. Never hand-build the skeleton.
@@ -82,10 +82,10 @@ Runs in parallel; ALL must APPROVE; surface results and wait for the user's expl
 ## Phase 4 - Deliver
 - CLEAR with `review_required: false`: present the plan summary, then ask ONE question and stop - start work now, or run a high-accuracy review first? Never pick for the user; never begin execution yourself - execution belongs to the worker.
 - CLEAR with `review_required: true`: run the high-accuracy review before delivery, record receipts, then present the plan summary and review result. Do not ask whether to run the review; the user already asked.
-- UNCLEAR: run Metis plus the high-accuracy review AUTOMATICALLY before presenting (unless Classify=Trivial), then present a brief that LEADS with the derived approach and the adopted defaults; still wait for the user's explicit okay.
+- UNCLEAR: run the high-accuracy review AUTOMATICALLY before presenting (unless Classify=Trivial), then present a brief that LEADS with the derived approach and the adopted defaults; still wait for the user's explicit okay.
 
 ### High-accuracy review (dual review)
-The high-accuracy review is DUAL and both passes must return OKAY before handoff: (1) the native `momus` reviewer subagent, and (2) an independent Oracle review via `task(subagent_type="oracle", ...)` on the strongest available reasoning model, in a fully isolated sub-session with normal approval and sandbox policy. Do not add flags that disable approvals or sandboxing. Fix every cited issue and resubmit BOTH fresh until each approves. CLEAR: runs when the user opts in or `review_required: true`. UNCLEAR: runs automatically unless Classify=Trivial.
+The high-accuracy review is DUAL and both passes must return OKAY before handoff: (1) the native `momus` reviewer subagent, and (2) an independent Oracle review via `task(subagent_type="oracle", ...)` on the strongest available reasoning model, in a fully isolated sub-session with normal approval and sandbox policy. Do not add flags that disable approvals or sandboxing. One round = exactly ONE `momus` + ONE independent review, dispatched together against the COMPLETE plan file (todos + TL;DR filled) - never a second `momus` while a round is in flight. After both verdicts return, fix every cited issue and resubmit both fresh until each approves. CLEAR: runs when the user opts in or `review_required: true`. UNCLEAR: runs automatically unless Classify=Trivial.
 
 The draft must record the native Momus session/result, the independent review session/result, and the fix/retry summary. Do not say "high-accuracy review completed" unless both receipts exist and both final verdicts are unconditional approval.
 
@@ -96,9 +96,9 @@ Every delegated prompt starts with `TASK:`, then DELIVERABLE / SCOPE / VERIFY; s
 task(subagent_type="explore", description="Map the implementation surface", prompt="TASK: act as an explorer. DELIVERABLE: ... SCOPE: ... VERIFY: ...")
 ```
 
-Roles: `explore`, `librarian`, `metis`, `momus`. Spawn long plan/reviewer agents in the background and poll with short waits through the OpenCode task surface; require the child to send `WORKING: <task> - <phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A timeout only means no new update arrived; treat a running child as alive. Fall back only when the child completed without the deliverable, is ack-only after followup, explicitly `BLOCKED:`, or no longer running; then respawn a smaller delegated job. Close each agent after integrating its result.
+Roles - the ONLY spawnable subagents (all read-only, plus `oracle` for the high-accuracy review): `explore`, `librarian`, `metis`, `momus`. Never dispatch with `category=` and never instruct a child to edit files. Spawn long plan/reviewer agents in the background and poll with short waits through the OpenCode task surface; require the child to send `WORKING: <task> - <phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A timeout only means no new update arrived; treat a running child as alive. Fall back only when the child completed without the deliverable, is ack-only after followup, explicitly `BLOCKED:`, or no longer running; then respawn a smaller delegated job. Close each agent after integrating its result.
 
 ## Stop rules
-- Plan file exists, template filled, every todo has references + acceptance + QA + commit, dependency matrix consistent: present the summary, ask the start-or-high-accuracy question (CLEAR) or lead with the best-practice brief (UNCLEAR), and stop. Execution belongs to the worker, never to you.
+- Plan file exists, template filled, every todo has references + acceptance + QA + commit, dependency matrix consistent, and any required high-accuracy receipts recorded: present the summary, then (CLEAR without `review_required`) ask the start-or-high-accuracy question, or (CLEAR with `review_required` / UNCLEAR) report the review result - and stop. Execution belongs to the worker, never to you.
 - Brief presented and `status: awaiting-approval` recorded: wait. Do not re-explore unless the user changes scope.
 - Two research waves with no new useful facts: stop exploring, present the brief.

package/dist/skills/ulw-plan/references/intent-unclear.md

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

package/dist/skills/ulw-research/ATTRIBUTION.md

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

package/dist/skills/ulw-research/SKILL.md

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

package/dist/skills/visual-qa/SKILL.md

@@ -57,32 +57,28 @@ For reference-fidelity work, repeat the capture and diff for every referenced vi
 
 ### TUI
 
-1. Capture plain text and an ANSI-preserving copy:
-
-```
-tmux capture-pane -p > capture.txt
-tmux capture-pane -e -p > capture-ansi.txt
-```
-
-2. When the TUI evidence will be attached to a PR or reviewed visually, render
-   the capture through the browser helper from the repository root:
+1. Render the TUI through the REAL xterm.js web terminal and screenshot it -
+   NEVER `tmux capture-pane`, which degrades truecolor and misaligns wide (CJK)
+   glyphs. Run the command in a real pty and capture the browser render from the
+   repository root:
 
 ```
 node script/qa/web-terminal-visual-qa.mjs --title "TUI Visual QA" \
-  --from-file capture.txt \
+  --command "<tui-command>" \
+  --input "{ArrowDown}" --input "{Enter}" \
   --evidence-dir .omo/evidence/<slug>/tui-web-terminal
 ```
 
-This produces `terminal.png`, `terminal.html`, `terminal.txt`,
-`terminal-ansi.txt`, and `metadata.json`. Treat this as the standard TUI visual
-artifact pattern for terminal screenshots. If the project is outside this repo,
-copy the same pattern: terminal capture -> browser-rendered page -> PNG +
-metadata with cleanup receipt.
+   Replay a saved raw stream with `--from-file <capture.ansi>` instead of
+   `--command`. This produces `terminal.png` (the true-color artifact),
+   `terminal.txt`, `terminal-ansi.txt`, and `metadata.json`. Treat this as the
+   standard TUI visual artifact pattern. Outside this repo, copy the pattern:
+   real pty -> xterm.js in a browser -> PNG + metadata with cleanup receipt.
 
-3. Run the check with the REAL terminal width and keep the JSON:
+2. Run the width check on the produced text and keep the JSON:
 
 ```
-node "$SKILL_DIR/scripts/visual-qa.mjs" tui-check capture.txt --cols <N>
+node "$SKILL_DIR/scripts/visual-qa.mjs" tui-check .omo/evidence/<slug>/tui-web-terminal/terminal.txt --cols <N>
 ```
 
 Key fields: `maxWidth`, `overflowLines[]`, `borderMisaligned`, `wideCharColumns[]`, `hasAnsi`.

package/dist/tools/skill/description-formatter.d.ts

@@ -3,5 +3,6 @@ import type { CommandInfo } from "../slashcommand/types";
 interface CombinedDescriptionOptions {
     includeSkills?: boolean;
 }
+export declare function deduplicatePathAliasedSkills(skills: SkillInfo[]): SkillInfo[];
 export declare function formatCombinedDescription(skills?: SkillInfo[], commands?: CommandInfo[], options?: CombinedDescriptionOptions): string;
 export {};

package/dist/tools/skill/description-formatter.test-support.d.ts

@@ -0,0 +1,9 @@
+import type { CommandInfo } from "../slashcommand/types";
+import type { SkillInfo } from "./types";
+export declare function makeSkill(name: string, description?: string, overrides?: Partial<SkillInfo>): SkillInfo;
+export declare function sharedSkill(name: string, description?: string): SkillInfo;
+export declare function builtinSharedSkill(name: string, description?: string): SkillInfo;
+export declare function localSkill(name: string, description?: string): SkillInfo;
+export declare function userSkill(name: string, description?: string): SkillInfo;
+export declare function opencodeNativeSkill(name: string, description?: string, location?: string): SkillInfo;
+export declare function makeCommand(name: string, description?: string, overrides?: Partial<CommandInfo>): CommandInfo;

package/dist/tools/skill/zauc-mocks-skill-tools/test-support.d.ts

@@ -0,0 +1,25 @@
+import type { ToolContext } from "@opencode-ai/plugin/tool";
+import type { LoadedSkill } from "../../../features/opencode-skill-loader/types";
+import type { CommandInfo } from "../../slashcommand/types";
+import type { SkillLoadOptions } from "../types";
+type SkillToolFactory = typeof import("../tools").createSkillTool;
+type TestSkillLoadOptions = Omit<SkillLoadOptions, "directory"> & {
+    readonly directory?: SkillLoadOptions["directory"];
+};
+export declare function createSkillTool(options?: TestSkillLoadOptions): ReturnType<SkillToolFactory>;
+export declare function createMockSkill(name: string, options?: {
+    readonly agent?: string;
+    readonly scope?: LoadedSkill["scope"];
+}): LoadedSkill;
+export declare function createMockSkillWithMcp(name: string, mcpServers: Record<string, unknown>): LoadedSkill;
+export declare function createMockCommand(name: string, scope: CommandInfo["scope"]): {
+    name: string;
+    path: string;
+    metadata: {
+        name: string;
+        description: string;
+    };
+    scope: import("../../slashcommand").CommandScope;
+};
+export declare const mockContext: ToolContext;
+export {};