oh-my-opencode 4.19.0 → 4.19.2

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

@@ -1,6 +1,6 @@
 ---
 name: debugging
-description: "MUST USE for any real runtime debugging across ANY language or binary — crashes, silent failures, wrong responses, stuck processes, memory leaks, async misbehavior, unexplained timing, reverse engineering. Runs a hypothesis-driven loop: form ≥3 hypotheses, investigate in parallel, after 2 failed rounds spawn Oracles from orthogonal angles, confirm root cause, lock with a failing test, fix minimally, QA by actually USING the system, scrub artifacts. The actual HOW lives in `references/` — READ THEM. Triggers: 'debug this', 'why is X not working', 'hanging', 'attach a debugger', 'reverse engineer', 'pwndbg', 'gdb', 'lldb', 'node inspect', 'tsx debug', 'pdb', 'dlv', 'delve', 'rust-gdb', 'set a breakpoint', 'context window exploded', 'why is the response empty', 'attach the debugger', 'debug it', 'why is this happening', 'trace this bug', 'reproduce and fix', 'silent failure', 'HTTP 200 but empty', 'why did it stop', 'inspect the binary', 'reverse engineering', 'playwright'."
+description: "MUST USE for any real runtime debugging across ANY language or binary — crashes, silent failures, wrong responses, stuck processes, memory leaks, async misbehavior, unexplained timing, reverse engineering. Runs a hypothesis-driven loop: form ≥3 hypotheses, investigate in parallel, after 2 failed rounds spawn Oracles from orthogonal angles, confirm root cause, lock with a failing test, fix minimally, QA by actually USING the system, scrub artifacts. The actual HOW lives in `references/` — READ THEM. Triggers: 'debug this', 'why is X not working', 'hanging', 'attach a debugger', 'reverse engineer', 'pwndbg', 'gdb', 'lldb', 'node inspect', 'tsx debug', 'pdb', 'dlv', 'delve', 'rust-gdb', 'set a breakpoint', 'context window exploded', 'why is the response empty', 'why is this happening', 'trace this bug', 'reproduce and fix', 'silent failure', 'HTTP 200 but empty', 'why did it stop', 'inspect the binary', 'playwright', 'flaky test', 'fails intermittently', 'passes in isolation', 'only fails in CI'."
 ---
 
 # Debugging
@@ -84,6 +84,7 @@ These are not phases — read them when the situation calls for them:
 
 | Situation | Reference |
 |---|---|
+| The failure is intermittent — fails sometimes, a different test each run, passes in isolation, or only fails in CI | 📖 **[references/methodology/03-flaky-triage.md](references/methodology/03-flaky-triage.md)** — read BEFORE Phase 2; the failure signature usually collapses the search space in one round |
 | You cannot run the actual operation (paid API, blocked network, missing hardware) but still need runtime evidence | 📖 **[references/methodology/partial-runtime-evidence.md](references/methodology/partial-runtime-evidence.md)** |
 | You're about to declare an extraction / audit / reverse-engineering task done and want a skeptical pass | 📖 **[references/methodology/partial-runtime-evidence.md#verification-oracle-pattern-for-non-debug-tasks](references/methodology/partial-runtime-evidence.md#verification-oracle-pattern-for-non-debug-tasks)** (Verification Oracle is *not* the same as Oracle Triple — read the file) |
 

package/packages/omo-codex/plugin/skills/debugging/references/methodology/03-flaky-triage.md

@@ -0,0 +1,47 @@
+# Intermittent / Flaky Failure Triage
+
+Read this when a failure does not reproduce on every run — "fails sometimes", "a different test each run", "passes in isolation", "only fails in CI". Do not enter the hypothesis loop blind: **intermittence itself is evidence.** This triage usually collapses the search space in one round, before Phase 2 hypothesis formation.
+
+---
+
+## Step 1 — Capture the failure signature (three cheap reruns)
+
+Run these before forming any hypothesis. Journal each result.
+
+| Rerun | Command shape | Question it answers |
+|---|---|---|
+| Same scope, same command | exactly what just failed | Does the SAME test fail again, or a different one? |
+| Failing test in isolation | single file / test filter | Does it pass alone? |
+| Full scope on a quiet machine | stop concurrent builds, suites, background agents first | Does the whole suite go green when nothing else runs? |
+| (When order is suspect) shuffled | `-shuffle=on` / `pytest-randomly` / runner's random seed | Does a specific order reproduce it? Record the seed. |
+
+## Step 2 — Read the signature
+
+| Signature | Dominant hypothesis | Next move |
+|---|---|---|
+| Same test fails intermittently, everywhere | Real race in the code under test, or an async test bug (fixed sleep, unawaited promise, poll-for-time) | Standard phase loop from `02-investigate.md`; reproduce deterministically by subscribing to the completion event or injecting a clock |
+| **A different test/file each run; each passes in isolation; quiet machine is green** | **Environment contention between concurrent runs — not the code** | Step 3 checklist |
+| Always the same test, but only in the full suite; isolation green | Test-order dependence / fixture leak (unreset module state, leaked env var, shared singleton) | Bisect with the shuffle seed; find the test that leaks, fix its teardown |
+| Fails only on CI, never locally | Resource ceilings (slower disk/CPU → timeouts), different parallelism defaults, container clock | Reproduce locally under constraint (`taskset`, low `--maxWorkers`); raise the *signal* not the sleep |
+| Green on plain rerun of the same commit | Still a flake — classify it with this table before ignoring it; an unclassified flake is a hidden bug report | Step 1 again with journaling |
+
+## Step 3 — Concurrent-run contention checklist
+
+The classic modern cause: **two checkouts or worktrees of the same repo — or one checkout plus a background agent — running suites at the same time while sharing a global mutable resource.** Multi-agent workstations make this the default failure mode, not an exotic one. Check each:
+
+- **Shared tmp roots** — a sandbox/cache dir derived from a *fixed* tmpdir path (`$TMPDIR/<project>-fixed-name`) instead of a per-run `mktemp`. Both runs read/write the same tree; the loser sees half-deleted state.
+- **Fixed ports** — hardcoded listen ports in test servers. Two suites race to bind; the loser gets 404/ECONNREFUSED mid-run, in whichever file happened to be running.
+- **Global env / config mutation** — tests writing process-external state (dotfiles, shared config, global env) the other run reads.
+- **Shared containers / databases** — same-named containers, same schema, same volume.
+- **Caches and locks** — package-manager caches, lockfiles, `.git` index contention.
+
+Evidence to capture while it is live: `lsof -i :<port>` during the failure window, a listing of the shared tmp path, a process list showing the concurrent runners.
+
+## Step 4 — Fix policy
+
+- **Environment contention** → fix the **test infrastructure**, never the individual test: namespace every suite-global resource per run — `mktemp` for roots, port `0`/ephemeral allocation, unique container names. The bar: *two checkouts of this repo running the suite concurrently must not interfere.* (The programming skill's test-isolation rules own this bar.)
+- **Order dependence** → find the leaking fixture via the recorded shuffle seed; reset at teardown; re-run shuffled until the seed class is clean.
+- **Real race** → normal phase loop (`02-investigate.md` onward); the fix ships with a failing-first test that reproduces deterministically.
+- **Forbidden regardless of cause**: retry wrappers around the test, enlarged sleeps, `.retry(N)`, quarantining, or deleting the test. Each one buries a bug report.
+
+A flake you classified but did not fix is a **finding to report**, not to hide: journal the signature, the evidence, and the classification, and say it in your final report.

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

@@ -102,7 +102,7 @@ Mocks are a last resort, not a default. The priority order:
 - **Accurate**: the test fails for the bug it names, and only that bug. No incidental coupling to format, ordering, whitespace, or unrelated fields. Assert on the *contract*, not on the dump.
 - **Efficient**: the whole unit suite runs in < 30 seconds on a developer laptop. The whole integration suite in < 5 minutes. If you cross those budgets, profile and split — fast tests run on every save, slow ones run on push.
 - **Deterministic**: no `sleep`, no wall-clock dependence, no order dependence (`-shuffle=on`, pytest-randomly, vitest random seed). Inject a `Clock`. Subscribe to the event, do not poll for it. Time-based flake is a bug, not a test issue.
-- **Isolated**: every test starts from a known fixture and tears down. `t.TempDir()`, `t.Setenv()`, transactional rollback for DB tests. Two tests passing individually but failing together is a fixture leak — fix it immediately.
+- **Isolated**: every test starts from a known fixture and tears down. `t.TempDir()`, `t.Setenv()`, transactional rollback for DB tests. Two tests passing individually but failing together is a fixture leak — fix it immediately. Isolation extends **across processes**: suite-global resources — sandbox/cache roots under a fixed tmpdir path, hardcoded listen ports, container names — are namespaced per run (`mktemp`, port `0`/ephemeral, unique names) so that two checkouts or worktrees of the repo running the suite concurrently cannot interfere. A fixed shared path that works on a single-checkout machine is a flake generator on a multi-agent workstation, and its signature is "a different test fails each run".
 
 ### Prompt tests: NEVER assert prose
 
@@ -113,6 +113,7 @@ Assert ONLY what a machine consumes:
 - the builder's routing decision — `expect(getPromptSource(model)).toBe("gpt-5-6")`, never the sentence that routing produces
 - a structural token the runtime dispatches on — a tool name, a tag like `<agent-identity>`, a parsed frontmatter field
 - the conditional the code enforces — skill loaded → tool present; `verbose=false` → directive absent
+- a routing-bearing trigger fragment inside a parsed frontmatter `description` that a router (code or an LLM skill-picker) dispatches on — pin the *minimal fragment that carries the routing decision*, never the surrounding style prose. Such pins are what let a later rewrite change every sentence around them while proving the routing contract survived.
 
 If no machine consumes the text, there is no seam: write NO test and say so in the PR; review guards prose. When you DELEGATE test-writing, hand the child the behavior the test must distinguish ("fails if override precedence breaks"), never a ready-made assertion string, prompt fragment, or marker to copy — a prescribed mechanism that is wrong gets implemented faithfully, and the error ships with a green suite.
 
@@ -234,6 +235,15 @@ Logging is part of the code you ship, and it has iron rules of its own: levels c
 
 ---
 
+## DEPENDENCY UPGRADES — CROSS-CUTTING RULES
+
+- **`0.x` minor = major.** Semver promises nothing below 1.0: treat `0.N → 0.N+1` as a breaking upgrade — read the changelog, build, and run the full suite before trusting it. A required field appearing in a public options type is a routine `0.x` "minor".
+- **Version literals live outside the manifest.** Before committing a bump, grep the repo for the old version string: Dockerfiles pinning a global CLI, CI workflows, docs, and contract tests all carry copies. A bump that updates only the package manifest ships a split-brain deploy.
+- **Pin-parity contract tests are a pattern, not a nuisance.** A small test asserting the lockfile-resolved version equals the deploy artifact's pin (Dockerfile, image tag) turns silent drift into a red test. If the project has one, update it deliberately; if the bump reveals unguarded drift, add the test with the bump.
+- **Never hand-merge a lockfile.** On conflict, take either side whole and regenerate with the package manager — the resolver owns that file, not you.
+
+---
+
 ## MANDATORY POST-WRITE REVIEW LOOP
 
 **This runs EVERY time you finish writing or substantively editing code, before you claim the task is done.** No exceptions.

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

@@ -56,9 +56,11 @@ Log where the system decides something, not where it does something:
 - **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:
+Never log inside pure functions, utilities, or private helpers — callers with context log outcomes; internals stay silent. The 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.
+- **Answering the caller is not logging.** Converting a failure into a response — an HTTP 5xx body, an SSE error event, an error string returned to an LLM as a tool result, a non-zero exit code — satisfies the caller and leaves operations blind. This is the dominant finding when error paths are audited: the caller got an answer, the on-call got nothing. Every path that converts a failure into a caller-facing signal logs that failure exactly once, at the layer that handles it. When conversion layers stack, mark the error as logged at the handling layer (a symbol/flag on the error object) so outer catch-all handlers skip it — one incident, one line.
+- **Expected feedback returned to the caller is not an event.** Validation results delivered as a normal response — including tool output an LLM agent consumes ("string not found", lint findings, a sandbox-boundary notice) — are response content, not anomalies. Log only the genuine I/O and subprocess failures behind them, and security rejections.
 - **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.
@@ -69,6 +71,7 @@ Never log inside pure functions, utilities, or private helpers — callers with
 - **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.
+- **Payload content belongs to the tracing channel, not the log stream.** In LLM/agent systems, user messages, model responses, and tool outputs are captured by the tracing product (turn recorder, trace exporter); a log line carries a hash, a length, and at most a short excerpt for correlation. Dumping conversation content into logs bloats the store and leaks data the log pipeline was never hardened for.
 - **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
@@ -79,6 +82,8 @@ Never log inside pure functions, utilities, or private helpers — callers with
 | 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 |
+| Failure converted to a caller response (5xx body, SSE error, LLM tool-error string, exit code) with no log | The caller got an answer; operations got nothing |
+| Logging expected validation feedback that is returned to the caller | Response content, not an event — buries real failures |
 | 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 |

package/packages/omo-codex/plugin/skills/programming/scripts/typescript/check-no-excuse-rules.ts

@@ -19,6 +19,10 @@
  * Usage:
  *   bun run scripts/check-no-excuse-rules.ts <file-or-dir>...
  *
+ * The `typescript` package is resolved from the caller project (process.cwd()),
+ * not from this script's location, so the script works when executed from an
+ * installed skill-cache path (e.g. ~/.codex/...) against a project checkout.
+ *
  * Exit codes:
  *   0 - no violations
  *   1 - violations found
@@ -26,9 +30,41 @@
  */
 
 import fs from "node:fs"
+import { createRequire } from "node:module"
 import path from "node:path"
 import process from "node:process"
-import ts from "typescript"
+import type * as tsTypes from "typescript/unstable/ast"
+
+type TsApiModule = typeof import("typescript/unstable/async")
+type TsAstModule = typeof import("typescript/unstable/ast")
+type TsModule = {
+  readonly api: TsApiModule
+  readonly ast: TsAstModule
+}
+
+function loadTypescriptFromCaller(): TsModule {
+  // A static import resolves from this script's installed skill-cache path
+  // instead of the caller project. Resolve each TypeScript 7 API subpath from
+  // the caller so the script uses the project it audits.
+  const callerRequire = createRequire(path.join(process.cwd(), "no-excuse-anchor.cjs"))
+  try {
+    const api: Partial<TsApiModule> = callerRequire("typescript/unstable/async")
+    const ast: Partial<TsAstModule> = callerRequire("typescript/unstable/ast")
+    if (typeof api.API === "function" && typeof ast.isAsExpression === "function") {
+      return { api: api as TsApiModule, ast: ast as TsAstModule }
+    }
+  } catch { // no-excuse-ok: catch
+    // fall through to the clear error below
+  }
+  console.error(
+    `error: cannot resolve "typescript" from the caller project (${process.cwd()}). ` +
+      "Install it in the project being checked (e.g. `bun add -d typescript`) and re-run.",
+  )
+  process.exit(2)
+}
+
+const typescript = loadTypescriptFromCaller()
+const ts = typescript.ast
 
 type RuleId =
   | "no-any-assertion"
@@ -95,29 +131,50 @@ function discoverFiles(inputs: string[]): string[] {
   return files
 }
 
-function getLineText(sourceFile: ts.SourceFile, line: number): string {
+function getLineText(sourceFile: tsTypes.SourceFile, line: number): string {
   const lineStarts = sourceFile.getLineStarts()
   const start = lineStarts[line]
   const end = line + 1 < lineStarts.length ? lineStarts[line + 1] : sourceFile.getEnd()
   return sourceFile.text.slice(start, end)
 }
 
-function analyzeFile(filePath: string): Violation[] {
+async function parseSourceFiles(filePaths: readonly string[]): Promise<ReadonlyMap<string, tsTypes.SourceFile>> {
+  const compiler = new typescript.api.API({ cwd: process.cwd() })
+  try {
+    const snapshot = await compiler.updateSnapshot({ openFiles: [...filePaths] })
+    try {
+      const sourceFiles = await Promise.all(filePaths.map(async (filePath) => {
+        const project = await snapshot.getDefaultProjectForFile(filePath)
+        const sourceFile = await project?.program.getSourceFile(filePath)
+        if (!sourceFile) {
+          throw new Error(`TypeScript did not parse ${filePath}`)
+        }
+        return [filePath, sourceFile] as const
+      }))
+      return new Map(sourceFiles)
+    } finally {
+      await snapshot.dispose()
+    }
+  } finally {
+    await compiler.close()
+  }
+}
+
+function analyzeFile(filePath: string, sourceFile: tsTypes.SourceFile): Violation[] {
   const source = fs.readFileSync(filePath, "utf-8")
-  const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true)
   const violations: Violation[] = []
 
-  function pos(node: ts.Node): { line: number; column: number } {
+  function pos(node: tsTypes.Node): { line: number; column: number } {
     const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile))
     return { line: line + 1, column: character + 1 }
   }
 
-  function lineHasOptOut(node: ts.Node): boolean {
+  function lineHasOptOut(node: tsTypes.Node): boolean {
     const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile))
     return OPT_OUT_RE.test(getLineText(sourceFile, line))
   }
 
-  function visit(node: ts.Node): void {
+  function visit(node: tsTypes.Node): void {
     // ── as any / as unknown ──
     if (ts.isAsExpression(node)) {
       const typeText = node.type.getText(sourceFile)
@@ -221,7 +278,7 @@ function analyzeFile(filePath: string): Violation[] {
       }
     }
 
-    ts.forEachChild(node, visit)
+    node.forEachChild(visit)
   }
 
   visit(sourceFile)
@@ -252,7 +309,7 @@ function formatViolation(v: Violation): string {
   return `${v.filePath}:${v.line}:${v.column}: [${v.ruleId}] ${v.message}`
 }
 
-function main(): void {
+async function main(): Promise<void> {
   const args = process.argv.slice(2)
   if (args.length === 0) {
     console.error("usage: check-no-excuse-rules.ts <file-or-dir>...")
@@ -265,7 +322,14 @@ function main(): void {
     process.exit(2)
   }
 
-  const violations = files.flatMap((f) => analyzeFile(f))
+  const sourceFiles = await parseSourceFiles(files)
+  const violations = files.flatMap((filePath) => {
+    const sourceFile = sourceFiles.get(filePath)
+    if (!sourceFile) {
+      throw new Error(`TypeScript did not parse ${filePath}`)
+    }
+    return analyzeFile(filePath, sourceFile)
+  })
 
   if (violations.length === 0) {
     console.log(`No violations in ${files.length} file(s).`)
@@ -279,4 +343,4 @@ function main(): void {
   process.exit(1)
 }
 
-main()
+await main()

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

@@ -45,11 +45,21 @@ Execute a Prometheus work plan until every top-level checkbox is complete. This
 ## Usage
 
 ```text
-$start-work [plan-name] [--worktree <absolute-path>]
+$start-work [plan-name] [--worktree <absolute-path>] [--make-pr] [--ship]
 ```
 
 - `plan-name` (optional): a full or partial file stem under `.omo/plans/`.
 - `--worktree` (required for PR/branch work; otherwise optional): the task-owned git worktree path.
+- `--make-pr` (optional): deliver the work as a pull request. IMPLIES worktree mode: when `--worktree` is absent, create a task-owned worktree (`git worktree add <absolute-path> <base-branch>`) before implementation and record it as `worktree_path`. On completion, push the branch and open a reviewer-readable PR, then hand off with the PR URL - merge only if the user asks.
+- `--ship` (optional): full delivery lifecycle; implies `--make-pr`. After the PR opens, stay on the job until it is MERGED: watch CI and review gates, fix failures and address feedback from the worktree (fresh QA evidence for behavior changes), merge per the repository's merge policy, then remove the worktree and sync `.omo/` state back.
+
+## Goal and todo discipline (MANDATORY)
+
+Do ALL of this immediately after the plan is selected, BEFORE the first implementation dispatch. Skipping any step is a defect.
+
+1. **Set the goal, in detail.** When a goal tool is available (`create_goal`), call it with a DETAILED objective: the plan name and path, the concrete end state, the phase and task counts, the delivery mode (direct, `--make-pr`, or `--ship`), and how completion will be verified. One work session = one goal. No goal tool -> record the same objective as the first ledger entry.
+2. **Register every phase and task as todos.** Mirror the plan into the todo/plan tool of your harness: one phase per plan wave, one todo per column-zero checkbox (including the final verification wave). Register ALL of them up front - never keep tasks in memory only.
+3. **Keep them current at every moment.** Mark a todo in_progress when its work dispatches and done immediately after its verification passes. Never batch-complete at the end, never execute work that is not a registered todo; discovered work is appended as a todo before it runs. The todo list, Boulder state, and plan checkboxes must always tell the same story.
 
 ## Phase 1: Select the plan
 
@@ -92,7 +102,7 @@ Write `.omo/boulder.json` before implementation starts. Prefix session ids with
 }
 ```
 
-For PR/branch work, `--worktree` is mandatory before implementation starts. Verify the path with `git worktree list --porcelain` or create it with `git worktree add <path> <branch-or-HEAD>`, then store the absolute path as `worktree_path`. All edits, commands, tests, and evidence capture must run inside that worktree.
+For PR/branch work, a task-owned worktree is mandatory before implementation starts: pass `--worktree`, or use `--make-pr`/`--ship`, which auto-create one. Verify the path with `git worktree list --porcelain` or create it with `git worktree add <path> <branch-or-HEAD>`, then store the absolute path as `worktree_path`. All edits, commands, tests, and evidence capture must run inside that worktree.
 
 ## Phase 3: Execute the next checkbox
 

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

@@ -411,13 +411,18 @@ Procedure (NON-NEGOTIABLE):
    2-attempt stop rule below) — do not loop further.
 
 # Commits
-Atomic, Conventional Commits (`<type>(<scope>): <imperative>` — feat /
-fix / refactor / test / docs / chore / build / ci / perf). One logical
-change per commit; each commit builds + tests green on its own. No WIP
-on the final branch. If a plan file exists, final commit footer:
-`Plan: .omo/plans/<slug>.md`. Do NOT auto-`git commit` unless the user
-requested or preauthorised this session — default is stage + draft
-message + present for approval.
+Commit frequently: one atomic commit per verified increment (RED→GREEN
++ its evidence), never one end-of-run omnibus; each commit builds +
+tests green on its own; no WIP on the final branch.
+BEFORE composing each message, read the history and mimic it: run
+`git log --oneline -20` plus `git log -5 -- <touched paths>` and match
+the observed convention — subject shape, scope names, message language,
+body style, and typical commit size. Default to Conventional Commits
+(`<type>(<scope>): <imperative>` — feat / fix / refactor / test / docs /
+chore / build / ci / perf) only where history shows no stronger local
+convention. If a plan file exists, final commit footer:
+`Plan: .omo/plans/<slug>.md`. Skip committing only when the user forbade
+commits this session — then stage + draft the message instead.
 
 # Constraints
 - Every behavior change needs a failing-first proof captured BEFORE

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

@@ -20,6 +20,7 @@ This skill is intentionally compact. The full workflow lives in `references/full
 ## Non-Negotiables
 
 - Use the ulw-loop CLI state under `.omo/ulw-loop`; do not hand-edit goal state.
+- Register goals up front (`omo ulw-loop create-goals`, then `create_goal` from the printed handoff) and mirror every atomic step into the live `update_plan` checklist: one ultra-granular step per action, exactly one in_progress, transitions marked the instant they happen.
 - After any compaction or context loss, re-read brief + goals + ledger FIRST plus `omo ulw-loop status --json`, then resume; never re-plan from scratch.
 - If `omo ulw-loop create-goals` says the existing aggregate is already complete, start unrelated new work with a fresh `--session-id <new-id>` instead of steering or forcing the completed default state. Use `--force` only to intentionally overwrite completed evidence.
 - Every success criterion needs observable evidence from a real surface: a channel (terminal/TUI via the xterm.js web terminal, HTTP, browser, computer-use) or, for CLI- or data-shaped criteria, an auxiliary surface (CLI stdout, DB diff, parsed config dump).
@@ -31,7 +32,7 @@ This skill is intentionally compact. The full workflow lives in `references/full
 - Track spawned agent names locally. Use `wait_agent` for mailbox signals, not proof of completion. A timeout only means no new mailbox update arrived. Treat a running child as alive.
 - While children run, surface the active subagent count, agent names, and latest `WORKING:` phase.
 - Fallback only when the child is completed without the deliverable, ack-only after `followup_task`, explicitly `BLOCKED:`, or no longer running. Then record inconclusive and respawn a smaller `fork_turns: "none"` task with the missing deliverable.
-- Use `git-master` for git-tracked edits: inspect recent and touched-path commit history, then commit each verified work unit atomically in the repository's observed language, scope, and message style with only that unit's files staged.
+- Use `git-master` for git-tracked edits: inspect recent and touched-path commit history, then commit each verified work unit atomically in the repository's observed language, scope, and message style with only that unit's files staged. Never carry verified units into a later omnibus commit.
 
 ## Codex Tool Mapping
 

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

@@ -113,9 +113,9 @@ If `ULW_LOOP_CLI` is empty, open the durable notepad first, record the missing C
 
 Run one form:
 ```sh
-omo ulw-loop create-goals --brief "<brief>" --json
-omo ulw-loop create-goals --brief-file <path> --json
-cat <brief> | omo ulw-loop create-goals --from-stdin --json
+omo ulw-loop create-goals --brief "<brief>" [--validation-batch-json <json-or-path>] --json
+omo ulw-loop create-goals --brief-file <path> [--validation-batch-json <json-or-path>] --json
+cat <brief> | omo ulw-loop create-goals --from-stdin [--validation-batch-json <json-or-path>] --json
 ```
 If the existing aggregate is already complete, do not steer or force the
 completed default state for unrelated new work. Start a fresh run with
@@ -145,7 +145,7 @@ Read pending goals, criteria IDs, current ledger head, blockers, and aggregate C
 Loop per goal. Cap at 5 cycles per goal. Cap identical same-criterion failures at 3.
 
 ### Acquire Next Goal
-1. Run `omo ulw-loop complete-goals --json` and read the handoff, including criteria.
+1. Run `omo ulw-loop complete-goals --json` and read the handoff, including criteria. After the first goal starts, a successful complete checkpoint normally prints the next goal instruction directly; use `complete-goals` as the manual fallback/resume path.
 2. Call `get_goal` and inspect active Codex state.
 3. Apply this table exactly:
 
@@ -177,7 +177,7 @@ Loop per goal. Cap at 5 cycles per goal. Cap identical same-criterion failures a
 ### Goal Completion
 1. Non-final aggregate goal: confirm every `essential` criterion is `pass`; non-essential criteria may remain pending. Final aggregate goal: confirm every criterion across the whole plan is `pass`.
 2. Call `get_goal` for a fresh snapshot.
-3. Run `omo ulw-loop checkpoint --goal-id <id> --status complete --evidence "<criteria evidence summary>" --codex-goal-json <snapshot> --json`.
+3. Run `omo ulw-loop checkpoint --goal-id <id> --status complete --evidence "<criteria evidence summary>" --codex-goal-json <snapshot> --json`; on success it auto-starts and prints the next eligible goal unless `--no-advance` is passed.
 4. If blocked or failed, checkpoint with `--status blocked` or `--status failed` and include diagnosis evidence.
 5. If this is the final goal, run the final quality gate first and pass `--quality-gate-json`.
 
@@ -219,7 +219,9 @@ Use steering only for structured evidence-backed mutation. Reject natural-langua
 | annotate_ledger | Audit-only note | `--evidence`, `--rationale` |
 | mark_blocked_superseded | Old story replaced by new evidence | `--goal-id`, `--replacements?`, `--evidence`, `--rationale` |
 
-Command form: `omo ulw-loop steer --kind <kind> [<kind-specific-fields>] --evidence "<...>" --rationale "<...>" --json`.
+Command form: `omo ulw-loop steer --kind <kind> [<kind-specific-fields>] --evidence "<...>" --rationale "<...>" --json`. For multiple evidence-backed plan-shape changes discovered together, pass `--proposals-json <json-or-path>` with an array of proposals; the batch applies atomically or rejects without partial plan mutation.
+
+Validation batches are optional aggregate-mode review boundaries declared at create time with `--validation-batch-json`. A batch-final member requires all other members resolved, all member criteria pass, and a member-spanning quality gate; split/supersede steering keeps batch membership updated.
 Structured prompt directives accepted: `OMO_ULW_LOOP_STEER: { ... }`, `omo.ulw-loop.steer: {...}`, `omo ulw-loop steer: {...}`.
 
 ## Constraints

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

@@ -13,11 +13,30 @@ You are **Prometheus**, a planning consultant. You turn a vague or large request
 
 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.
 
+## MANDATORY OPENING ANNOUNCEMENT
+
+The FIRST user-visible line of the turn that activates this skill MUST be exactly:
+
+`ULW-PLAN MODE ENABLED!`
+
+If another active mode mandates its own first line (ultrawork does), print that line first and this marker on the next line - both contracts stay satisfied.
+
+Directly under the marker, before any exploration, state the working contract once, in your own words, carrying ALL of these commitments:
+
+1. **Persona + no-implementation pledge** - from now on you work as Prometheus, a planning consultant, and you will never start implementation - no product-code edits, no implementer subagents - until the user explicitly says okay; even then, approval authorizes writing the plan only, and execution starts in a separate worker session (e.g. `$start-work`).
+2. **Workflow preview** - the order of what happens next: parallel read-only exploration (plus outside research when the repo cannot answer) until the open unknowns are resolved; the intent verdict from INTENT ROUTING, announced; questions to the user ONLY when a genuine owner-decision survives exploration - or when exploration and research both come back empty on a fork the plan cannot proceed without; then the approval brief, and the plan is written only after the explicit okay.
+
+Example opening (adapt the wording, keep every commitment):
+
+> ULW-PLAN MODE ENABLED!
+> From now on I am working as Prometheus, a planning consultant. I will not start any implementation until you explicitly say okay - and approval authorizes writing the plan only; execution starts separately (e.g. `$start-work`).
+> Next, in order: (1) parallel read-only exploration and research, (2) intent verdict announced (CLEAR or UNCLEAR, plus whether high-accuracy review is required), (3) questions only for the forks exploration cannot settle - or where research finds nothing on a blocking decision, (4) approval brief, then (5) the plan is written after your okay.
+
 ## INTENT ROUTING - pick ONE intent reference
 
 **Review modifiers are a gate trigger, not a style cue.** If the user says "high accuracy", "ultra high accuracy", "고정밀", "deep review", or equivalent - in ANY turn, even appended to a follow-up question and even after the plan already exists - set `review_required: true` in the draft: the dual high-accuracy review (native `momus` + the independent Codex CLI review) is now REQUIRED before handoff, and if the plan already exists you run it this same turn. Answering the current question more carefully does NOT satisfy it. This does NOT choose CLEAR/UNCLEAR and does NOT suppress interview.
 
-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.
+After grounding, make ONE judgment, record `intent: clear|unclear` plus `review_required`, **ANNOUNCE both to the user in one line**, then load ONE intent reference (you ALSO read `references/full-workflow.md` for the shared mechanics - see below). The test keys on whether the desired **OUTCOME** is clear, NOT on request length. This verdict line and the opening announcement above are the two mandatory user-visible signals of a planning session - it tells the user whether they will be interviewed and whether high-accuracy review is already requested; never skip either.
 
 > "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."
@@ -89,5 +108,5 @@ Roles: `explorer` (internal patterns/conventions/tests), `librarian` (external d
 
 ## Stop rules
 
-- Plan file exists, template filled, every todo has references + acceptance + QA + commit, dependency matrix consistent, and any required high-accuracy receipts are 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. **Never begin execution yourself.**
+- Plan file exists, template filled, every todo has references + acceptance + QA + commit, dependency matrix consistent, and any required high-accuracy receipts are recorded: present the handoff explanation (Phase 4 delivery format in `references/full-workflow.md`), then (CLEAR without `review_required`) ask the start-or-high-accuracy question, or (CLEAR with `review_required` / UNCLEAR) report the review result - and stop. **Never begin execution yourself.**
 - Brief presented and `status: awaiting-approval` recorded: wait. Do not re-explore unless the user changes scope.

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

@@ -168,6 +168,17 @@ Runs in parallel; ALL must APPROVE; surface results and wait for the user's expl
 - 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 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.
 
+### Handoff explanation (the mandatory shape of every plan summary)
+
+Every "present the plan summary/brief" above delivers THIS structure, in the user's language, derived from the finished plan file (COUNT the rows - never estimate):
+
+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).
+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.
 
@@ -212,6 +223,6 @@ If your tool list has a flat `spawn_agent` with a required `task_name` instead o
 Roles: `explorer`, `librarian`, `metis`, `momus`. Spawn long plan/reviewer agents in the background; between waits, back off — double the timeout up to ~5 minutes — instead of spinning short cycles. Require the child to send `WORKING: <task> - <phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A wait timeout only means no new mailbox update arrived; treat a running child as alive. Fall back only when the child completed without the deliverable, is ack-only after followup, explicitly `BLOCKED:`, or no longer running; then respawn a smaller `fork_context: false` job. Close each agent after integrating its result.
 
 ## Stop rules
-- Plan file exists, template filled, every todo has references + acceptance + QA + commit, dependency matrix consistent, 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.
+- Plan file exists, template filled, every todo has references + acceptance + QA + commit, dependency matrix consistent, and any required high-accuracy receipts recorded: present the handoff explanation (Phase 4 format), then (CLEAR without `review_required`) ask the start-or-high-accuracy question, or (CLEAR with `review_required` / UNCLEAR) report the review result - and stop. Execution belongs to the worker, never to you.
 - Brief presented and `status: awaiting-approval` recorded: wait. Do not re-explore unless the user changes scope.
 - Two research waves with no new useful facts: stop exploring, present the brief.

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

@@ -30,7 +30,7 @@ CLEARANCE CHECK after each turn: objective defined? scope IN/OUT explicit? appro
 </interview>
 
 <approval_and_deliver>
-Run the durable approval gate (mechanics in `full-workflow.md`): present the brief once with findings (paths), the approach, and EVERY surviving owner-decision as an explicit question with your recommended option (a skipped one resolves to that default); then wait for the user's explicit okay. If "start now, or review first?" would be your ONLY question, you have defaulted forks you should have surfaced - list them first. After approval: scaffold the files, run mandatory Metis, APPEND the todos, fill the human TL;DR last. Then either run the dual high-accuracy review if `review_required: true`, or present the summary and ask ONE question - start work now, or run the dual high-accuracy review first? Never pick for the user when review was not requested; never begin execution.
+Run the durable approval gate (mechanics in `full-workflow.md`): present the brief once with findings (paths), the approach, and EVERY surviving owner-decision as an explicit question with your recommended option (a skipped one resolves to that default); then wait for the user's explicit okay. If "start now, or review first?" would be your ONLY question, you have defaulted forks you should have surfaced - list them first. After approval: scaffold the files, run mandatory Metis, APPEND the todos, fill the human TL;DR last. Then either run the dual high-accuracy review if `review_required: true`, or present the handoff explanation (full-workflow.md Phase 4 format) and ask ONE question - start work now, or run the dual high-accuracy review first? Never pick for the user when review was not requested; never begin execution.
 </approval_and_deliver>
 
 <worked_example>

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

@@ -52,7 +52,7 @@ const lazycodexAgentInvariants = new Map([
 		"plan.toml",
 		{
 			model: "gpt-5.6-sol",
-			effort: "max",
+			effort: "high",
 			includes: [/strategic planning consultant/i, /\.omo\/plans\/<slug>\.md/, /never implements/i],
 		},
 	],
@@ -67,8 +67,8 @@ const lazycodexAgentInvariants = new Map([
 	[
 		"lazycodex-worker-medium.toml",
 		{
-			model: "gpt-5.6-luna",
-			effort: "max",
+			model: "gpt-5.6-terra",
+			effort: "high",
 			includes: [/EVIDENCE_RECORDED: <path>/, /medium-difficulty/i, /smallest correct change/i],
 		},
 	],
@@ -76,23 +76,23 @@ const lazycodexAgentInvariants = new Map([
 		"lazycodex-worker-high.toml",
 		{
 			model: "gpt-5.6-sol",
-			effort: "max",
+			effort: "medium",
 			includes: [/EVIDENCE_RECORDED: <path>/, /high-difficulty/i, /smallest correct change/i],
 		},
 	],
 	[
 		"lazycodex-clone-fidelity-reviewer.toml",
 		{
-			model: "gpt-5.6-sol",
-			effort: "xhigh",
+			model: "gpt-5.6-terra",
+			effort: "high",
 			includes: [/recommendation/, /blockers/, /\.omo\/evidence\/<goal>-clone-fidelity\.md/],
 		},
 	],
 	[
 		"lazycodex-code-reviewer.toml",
 		{
-			model: "gpt-5.6-sol",
-			effort: "xhigh",
+			model: "gpt-5.6-terra",
+			effort: "medium",
 			includes: [/codeQualityStatus/, /recommendation/, /<attemptDir>\/<goalId>-code-review\.md/, /currentAttemptDir/],
 		},
 	],
@@ -108,7 +108,7 @@ const lazycodexAgentInvariants = new Map([
 		"lazycodex-gate-reviewer.toml",
 		{
 			model: "gpt-5.6-sol",
-			effort: "high",
+			effort: "low",
 			includes: [/APPROVE\/REJECT/, /blockers/, /<attemptDir>\/<goalId>-gate-review\.md/, /currentAttemptDir/],
 		},
 	],

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

@@ -225,6 +225,32 @@ test("#given aggregate SessionStart hooks #when inspected #then LazyCodex auto-u
 	assert(sessionStartCommands.some((command) => command.includes("scripts/auto-update.mjs")));
 });
 
+test("#given aggregate SessionStart hooks #when inspected #then cold-start-prone hooks carry 15s timeout headroom", async () => {
+	// given
+	const manifests = await readAggregateHookManifests();
+
+	// when
+	const sessionStartHooks = manifests
+		.filter(({ hooks }) => hooks.hooks.SessionStart)
+		.flatMap(({ source, hooks }) =>
+			hooks.hooks.SessionStart.flatMap((group) =>
+				group.hooks.map((handler) => ({ source, command: handler.command, timeout: handler.timeout })),
+			),
+		);
+	const coldStartHooks = sessionStartHooks.filter(
+		({ command }) =>
+			command.includes("components/telemetry/dist/cli.js") ||
+			command.includes("scripts/auto-update.mjs") ||
+			command.includes("components/codegraph/dist/cli.js"),
+	);
+
+	// then
+	assert.equal(coldStartHooks.length, 3);
+	for (const hook of coldStartHooks) {
+		assert.equal(hook.timeout, 15, `${hook.source} must carry timeout 15 for cold-start headroom`);
+	}
+});
+
 test("#given aggregate PostToolUse hooks #when inspected #then CodeGraph init guidance is registered for CodeGraph tools", async () => {
 	// given
 	const commandHooks = await readAggregateCommandHooks();