oh-my-opencode 4.16.3 → 4.17.1

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

@@ -23,17 +23,15 @@ Run each criterion's real-surface proof yourself through the channel that faithf
 3. **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 use Chrome to drive the REAL page; if unavailable, use agent-browser. Capture action log + screenshot path. Never downgrade a browser-facing criterion.
 4. **Computer use** — for desktop/GUI apps, drive the running app via OS automation (computer-use, AppleScript, xdotool, etc.); capture action log + screenshot.
 
-For TUI visual QA, render the terminal through the real xterm.js web terminal and
-screenshot it - NEVER a `tmux capture-pane` dump (it degrades color and wide-glyph
-width). In this repo run `node script/qa/web-terminal-visual-qa.mjs --command
-"<cmd>" --input "{Enter}" --evidence-dir <dir>` (live pty + xterm.js in Chrome;
-`--from-file` replays a raw stream) and record `terminal.png`, `terminal.txt`, and
-`metadata.json`. Mandatory when a PR or review must inspect the terminal screen.
+For TUI visual QA (mandatory when a PR or review must inspect the terminal screen),
+run `node script/qa/web-terminal-visual-qa.mjs --command "<cmd>" --input "{Enter}"
+--evidence-dir <dir>` (live pty + xterm.js in Chrome; `--from-file` replays a raw
+stream) and record `terminal.png`, `terminal.txt`, and `metadata.json`.
 
 Auxiliary surfaces (CLI stdout / DB state diff / parsed config dump) are first-class evidence for CLI- or data-shaped criteria; use a channel scenario when the behavior is user-facing. `--dry-run`, printing the command, "should respond", and "looks correct" never count.
 
 ## Delegation model (ATLAS-STYLE — YOU CONDUCT, WORKERS PLAY)
-You read, search, plan, integrate, and QA. You DELEGATE every code edit, test write, bug fix, and QA execution to a right-sized `multi_agent_v1.spawn_agent` worker, then verify what comes back. Fan out independent tasks in PARALLEL in one response; serialize only on a NAMED dependency (one task consumes another's output or edits the same file).
+You read, search, plan, integrate, and QA. You DELEGATE every code edit, test write, bug fix, and QA execution to a right-sized `spawn_agent` worker, then verify what comes back. Fan out independent tasks in PARALLEL in one response; serialize only on a NAMED dependency (one task consumes another's output or edits the same file). Tool names here are MultiAgentV2 (gpt-5.6 sol/terra); on v1 models (gpt-5.5, gpt-5.6-luna) use the `multi_agent_v1.*` equivalents in the skill's Codex Tool Mapping.
 
 Size each worker to the task. Put the intended role, rigor level, and specialty inside the worker `message`.
 
@@ -44,21 +42,24 @@ Size each worker to the task. Put the intended role, rigor level, and specialty
 | Deep debugging / race / perf / subtle cross-module reasoning | `TASK: act as a deep debugging worker. ...` |
 | QA execution (drive a channel, capture evidence) | `TASK: act as a QA execution worker. ...` |
 | Read-only codebase search | `TASK: act as an explorer. ...` |
+| Implementation — pick the tier by change SIZE: LOW small (one-file fix, boilerplate) / MEDIUM mid-sized (standard feature, a few files) / HIGH large (new module, cross-module, concurrency/security/migration, or a big complex problem with one clear goal) | `TASK: act as a <low|medium|high>-difficulty implementation worker. ...` + `agent_type: "lazycodex-worker-<low|medium|high>"` when exposed |
 | External library / docs research | `TASK: act as a librarian. ...` |
 | Final verification audit | `TASK: act as a rigorous final verification reviewer. ...` |
 
 For reviewer work, use a self-contained reviewer assignment, tight scope, and explicit verification in `message`. Never spawn a context-only child for review.
 
+Difficulty is orthogonal to LIGHT/HEAVY rigor. Tier roles bind via `agent_type` (v1); the deployed v2 spawn schema omits it — state the tier inside `message` there.
+
 Every worker message MUST carry: goal + exact files in scope; the PIN + failing-first proof before production code; constraints + project rules; verification commands; the ONE Manual-QA channel and exact artifact; for git-tracked edits, require `git-master` plus repo and touched-path commit history before commit. Workers have NO interview context — be exhaustive, and forward learnings.
 
 Codex subagent reliability:
-- Start every `multi_agent_v1.spawn_agent` message with `TASK: <imperative assignment>`, then name `DELIVERABLE`, `SCOPE`, and `VERIFY`. State that it is an executable assignment, not a context handoff.
-- Use `fork_context: false` unless full history is truly required; paste only the context the child needs. Full-history forks can make the child continue old parent context instead of the delegated task.
-- Plan and reviewer agents may run for a long time; spawn them in the background, keep doing independent root work, and poll with short `multi_agent_v1.wait_agent` cycles. Never use a single long blocking wait for them.
+- Start every `spawn_agent` message with `TASK: <imperative assignment>`, then name `DELIVERABLE`, `SCOPE`, and `VERIFY`. State that it is an executable assignment, not a context handoff.
+- Use `fork_turns: "none"` (v1: `fork_context: false`) unless full history is truly required; paste only the context the child needs. Full-history forks can make the child continue old parent context instead of the delegated task.
+- Plan and reviewer agents may run for a long time; spawn them in the background and keep doing independent root work. Between `wait_agent` calls, back off — double the timeout up to ~5 minutes — instead of spinning short cycles.
 - For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long reading, testing, or review passes, and `BLOCKED: <reason>` only when it cannot progress.
 - While any child is active, keep the parent visibly alive with active subagent count, agent names, latest `WORKING:` phase, and whether the parent is waiting for mailbox updates.
-- Track spawned agent names locally. Use `multi_agent_v1.wait_agent` for mailbox signals, not proof of completion. A timeout only means no new mailbox update arrived. Treat a running child as alive.
-- Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running. Then send `TASK STILL ACTIVE: return <deliverable> or BLOCKED: <reason>` when a targeted followup can still recover the lane; otherwise record inconclusive, do not count it as pass/review approval, close if safe, and respawn a smaller `fork_context: false` task with the missing deliverable.
+- 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.
+- Fallback only when the child is completed without the deliverable, ack-only after `followup_task`, explicitly `BLOCKED:`, or no longer running. Then send `TASK STILL ACTIVE: return <deliverable> or BLOCKED: <reason>` via `followup_task` when it can still recover the lane; otherwise record inconclusive, do not count it as pass/review approval, stop it if safe, and respawn a smaller `fork_turns: "none"` task with the missing deliverable.
 
 ## Artifacts
 - `.omo/ulw-loop/brief.md`: original brief and durable constraints.
@@ -126,12 +127,12 @@ Write state through the CLI path. Do not hand-edit state files.
 Gather context BEFORE planning with parallel `explorer` / `librarian` workers plus your own read-only tools.
 First survey available skills: read every loosely-relevant skill's description, deliberately choose which this work uses, and prefer applying genuinely-relevant skills over working raw.
 Then run tier triage per goal — rigor (LIGHT/HEAVY below) and shape (`delivery` default, or `research` when the deliverable is a cited answer, not an artifact) — and record both in an `annotate_ledger` steering entry. Default is LIGHT — a narrow change inside existing layers. Take HEAVY only on a fact you can point to: a new module / abstraction / domain model; auth, security, or session; an external integration; a DB schema or migration; concurrency, transaction boundaries, or cache invalidation; a cross-domain refactor; or the user signaled care or demanded review. When unsure, take HEAVY; upgrade the moment a HEAVY fact surfaces, never downgrade mid-run.
-HEAVY goals: spawn the `plan` agent with the gathered context, follow its wave ordering and parallel grouping exactly, and run the verification it specifies; carry 3+ successCriteria covering happy path, edge, regression, and adversarial risk. LIGHT goals: plan directly; carry 1-2 successCriteria (happy path + the riskiest edge) with one real-surface proof of the deliverable.
+Planning depends on unresolved design uncertainty, not the rigor tier: after discovery, spawn the `plan` agent only when unclear boundaries, competing decompositions, or uncertain dependency ordering remain; otherwise plan directly, including for HEAVY goals with a known procedure. HEAVY goals carry 3+ successCriteria covering happy path, edge, regression, and adversarial risk. LIGHT goals carry 1-2 successCriteria (happy path + the riskiest edge) with one real-surface proof of the deliverable.
 Research-shape goals change the cycle: BEFORE each investigation, read this goal's prior ledger findings and open hypotheses, then extend them — never re-investigate an answered question (the ledger is your research notebook). Record findings via `annotate_ledger` with their source (`file:line`, command output, doc URL) as `--evidence`. Track hypotheses as `HYPOTHESIS[id]: <claim> | status: open`, flipped to `confirmed`/`refuted` only on an observed source. A research criterion passes on a cited answer — skip QA-channel, cleanup, and commit, but keep source-observability (never "looks correct"). Keep hypotheses inside the user's stated question; a scope-widening one is an `add_subgoal` proposal you surface, never silent creep. For a `research`-shape goal you MAY load `ulw-research` without hesitation — otherwise explicit-request-only, a research-shape goal IS that explicit demand. Research-only: never for a `delivery` goal. It composes with the librarian routing above — `ulw-research` for saturation (many parallel sources, recursive expansion), a single `librarian` for one lookup.
 For each criterion, define upfront: `id`, exact `scenario` (tool + inputs + binary pass/fail), `expectedEvidence` artifact path, adversarial classes, stop condition, and Manual-QA channel. Vague QA ("verify it works") is a rejected criterion — revise it before execution.
 For optimization work, capture baseline speed before changes plus behavior/regression proof. Every attempt records speed, behavior/regression, and the keep/revert/iterate decision.
 A criterion's adversarial classes are the ultraqa classes a fact about the change triggers: malformed input, prompt injection, cancel/resume, stale state, dirty worktree, hung or long commands, flaky tests, misleading success output, repeated interruptions. Record untriggered classes as not-applicable in one line.
-Use channel-table evidence verbs (tmux transcript, curl status+body, screenshot, action log, CLI stdout, DB diff, parsed config dump) — not vibes.
+Use channel-table evidence verbs — not vibes.
 
 **Plan for maximum parallelism (HEAVY goals).** Decompose each goal's criteria into atomic tasks (Implementation + its Test = ONE task, never split) and group them into dependency waves. Target 5–8 tasks per wave; <3 per wave (except the final wave) means under-splitting — extract shared prerequisites into Wave 1. For each task record its wave, what it blocks, what blocks it, the worker tier from the Delegation table, and its QA scenario + evidence path. Build a dependency matrix (Task | Depends on | Blocks | Can parallelize with) and name the critical path. Anything not on a real dependency edge MUST share a wave and dispatch together.
 Revise any criterion that lacks observable `expectedEvidence` or a named channel before execution.
@@ -159,14 +160,14 @@ Loop per goal. Cap at 5 cycles per goal. Cap identical same-criterion failures a
 ### Per-Criterion Cycle
 1. PLAN: read `criterion.scenario`, `criterion.expectedEvidence`, prior ledger entries, and safety bounds. Identify which tasks in the current wave are independent.
 2. Register atomic todos via `update_plan` — one ultra-granular step per action, `path: <action> for <criterion> - verify by <check>`. Call `update_plan` on every transition (start → `in_progress`, finish → `completed`); exactly one `in_progress`, mark completed immediately, never batch, never let the rendered plan lag behind reality.
-3. DELEGATE-IN-PARALLEL: dispatch every independent task in the wave at once via right-sized `multi_agent_v1.spawn_agent` workers (Delegation table). Each worker captures evidence failing-first: when the task touches EXISTING behavior, PIN it FIRST — a characterization test that asserts the current observable behavior and PASSES on the unchanged code, as rigorous as the new-behavior scenario (exact inputs, exact observable, exact assertion). Then RED through the cheapest faithful channel — a unit test where a seam exists, an integration/e2e test where the behavior lives in wiring, or the criterion's scenario captured failing when no test seam exists — failing for the RIGHT reason (no syntax/import error). A test that mirrors its implementation (mock-call assertions, pinned constants, cannot fail under plausible regression) is not evidence; use the scenario as the failing proof instead. Then the SMALLEST GREEN change; before GREEN work that depends on external review, PR, issue, or branch state, refresh current branch/PR/issue state, preserve existing ordering/policy, and separate compatibility detection from policy changes unless the goal explicitly asks to change policy. A GREEN far larger than the criterion implies means the proof was too coarse — instruct a split. Serialize only on a NAMED dependency.
+3. DELEGATE-IN-PARALLEL: dispatch every independent task in the wave at once via right-sized `spawn_agent` workers (Delegation table). Each worker captures evidence failing-first: when the task touches EXISTING behavior, PIN it FIRST — a characterization test that asserts the current observable behavior and PASSES on the unchanged code, as rigorous as the new-behavior scenario (exact inputs, exact observable, exact assertion). Then RED through the cheapest faithful channel — a unit test where a seam exists, an integration/e2e test where the behavior lives in wiring, or the criterion's scenario captured failing when no test seam exists — failing for the RIGHT reason (no syntax/import error). A test that mirrors its implementation (mock-call assertions, pinned constants, cannot fail under plausible regression) is not evidence; use the scenario as the failing proof instead. **When the target is PROSE (a prompt, `SKILL.md`, rule, or markdown/instruction file), the "observable behavior" is NOT the wording** — never pin sentences, phrase presence/absence, or word/char counts. PIN only a value a MACHINE consumes (a parsed frontmatter field, a sentinel token a hook greps, the doc's JSON sample run through its real validator), or guard two shipped copies with one `toBe` equality; a pure-prose change with no machine consumer has NO seam, so ship it on review + Manual-QA-by-read with NO automated test (a text grep there is pretend-coverage, not a RED proof). Then the SMALLEST GREEN change; before GREEN work that depends on external review, PR, issue, or branch state, refresh current branch/PR/issue state, preserve existing ordering/policy, and separate compatibility detection from policy changes unless the goal explicitly asks to change policy. A GREEN far larger than the criterion implies means the proof was too coarse — instruct a split. Serialize only on a NAMED dependency.
 4. INTEGRATE + CRITICAL SELF-QA + GIT CHECKPOINT (EVERY WORKER RETURN): do NOT trust the worker's report. Read the diff yourself, re-run its tests, and run LSP diagnostics on the changed files. Treat "done" as a claim to disprove. If the diff drifts, the test is hollow, or evidence is missing, RESPAWN the worker with the specific failure context. Once the work unit is verified, use `git-master` before staging: inspect recent repository commits and touched-path history to infer commit language, Conventional Commit scope, message shape, and unit size. Stage only that unit's files and commit in the observed style; do not carry verified work forward into a later omnibus commit. If no git-tracked files changed or committing is unsafe, record the no-commit reason as evidence. Forward every finding/learning to subsequent workers.
-5. EXECUTE-AS-SCENARIO: ACTUALLY run the Manual-QA scenario the criterion named (channel table above). Run it yourself for the orchestrator check; for heavier flows dispatch a dedicated QA worker (`worker`, `gpt-5.6-sol`, `xhigh`) whose ONLY job is to drive the channel and write the artifact to the named evidence path. If the scenario FAILS, respawn the implementing worker with the captured failure — do not hand-patch around it.
+5. EXECUTE-AS-SCENARIO: ACTUALLY run the Manual-QA scenario the criterion named (channel table above). Run it yourself for the orchestrator check; for heavier flows dispatch a dedicated QA execution worker (`lazycodex-worker-medium` by default; `lazycodex-worker-high` when the QA flow itself is hard) whose ONLY job is to drive the channel and write the artifact to the named evidence path. If the scenario FAILS, respawn the implementing worker with the captured failure — do not hand-patch around it.
 6. CAPTURE: collect the observable artifact path: transcript, stdout, screenshot, assertion, status+body, diff, or parsed dump. No artifact written at the evidence path — not done; record BLOCKED and respawn QA.
-7. CLEAN (PAIRED, NEVER SKIP): tear down every runtime artifact step 5 spawned BEFORE recording — server PIDs (`kill`, verify `kill -0` fails), `tmux` sessions (`tmux kill-session -t ulw-qa-<criterion>`; confirm `tmux ls`), browser / Playwright contexts (`.close()`), containers (`docker rm -f`), bound ports (`lsof -i :<port>` empty), temp sockets / files / dirs (`rm -rf` the `mktemp` paths), QA-only env vars, AND `multi_agent_v1.close_agent` on every finished worker. Register each teardown as its own todo the moment the QA spawns the resource (scripts, tmux assets, browsers / agent-browser sessions, PIDs, ports) so none is forgotten. Embed a one-line cleanup receipt in the evidence string, e.g. `cleanup: killed 12345; tmux kill-session ulw-qa-foo; rm -rf /tmp/ulw.aB12cD; multi_agent_v1.close_agent w-3`. Missing receipt → record BLOCKED, not PASS.
-8. RECORD exactly one result:
-   - PASS: `omo ulw-loop record-evidence --goal-id <id> --criterion-id <id> --status pass --evidence "<observable> | <cleanup receipt>" --json`
-   - FAIL: `omo ulw-loop record-evidence --goal-id <id> --criterion-id <id> --status fail --evidence "<observable> | <cleanup receipt>" --notes "<diagnosis>" --json`
+7. CLEAN (PAIRED, NEVER SKIP): tear down every runtime artifact step 5 spawned BEFORE recording — server PIDs (`kill`, verify `kill -0` fails), `tmux` sessions (`tmux kill-session -t ulw-qa-<criterion>`; confirm `tmux ls`), browser / Playwright contexts (`.close()`), containers (`docker rm -f`), bound ports (`lsof -i :<port>` empty), temp sockets / files / dirs (`rm -rf` the `mktemp` paths), QA-only env vars, AND close every finished worker (v1 `close_agent`; on V2 finished workers end on their own — `interrupt_agent` any still running). Register each teardown as its own todo the moment the QA spawns the resource (scripts, tmux assets, browsers / agent-browser sessions, PIDs, ports) so none is forgotten. Embed a one-line cleanup receipt in the evidence string, e.g. `cleanup: killed 12345; tmux kill-session ulw-qa-foo; rm -rf /tmp/ulw.aB12cD; interrupt_agent w-3`. Missing receipt → record BLOCKED, not PASS.
+8. RECORD one result immediately from the artifact you just wrote — never from memory or a later turn — stamping the capture commit `$(git rev-parse --short HEAD)` into the evidence:
+   - PASS: `omo ulw-loop record-evidence --goal-id <id> --criterion-id <id> --status pass --evidence "<observable> @<short-sha> | <cleanup receipt>" --json`
+   - FAIL: `omo ulw-loop record-evidence --goal-id <id> --criterion-id <id> --status fail --evidence "<observable> @<short-sha> | <cleanup receipt>" --notes "<diagnosis>" --json`
    - BLOCKED: `omo ulw-loop record-evidence --goal-id <id> --criterion-id <id> --status blocked --evidence "<observable>" --notes "<safety/blocker/leftover-state>" --json`
 9. If actual does not match expected, diagnose, respawn the right-sized worker with the failure context to fix minimally, and rerun the SAME criterion (including a fresh cleanup).
 10. After 3 same-criterion failures, exit the goal with diagnosis.
@@ -183,9 +184,10 @@ Loop per goal. Cap at 5 cycles per goal. Cap identical same-criterion failures a
 ## Final Quality Gate
 Trigger only for the final aggregate goal after every criterion in every goal is `pass`.
 1. Run targeted verification for changed behavior.
-2. Run Manual-QA for every criterion; confirm each artifact exists and is non-empty.
-3. Spawn final reviewers with `fork_context: false`: code review, QA review, gate review. Include original brief, goals, desired outcome, and diff.
-4. Treat timeout, missing deliverable, ack-only, `BLOCKED:`, or inconclusive review as a blocker. Fix, rerun affected verification/Manual-QA, and repeat review.
+2. FREEZE first — no more edits or rebases. At the frozen `git rev-parse HEAD`, re-run Manual-QA for any PASS criterion whose stamped commit is not HEAD, so every criterion is proven at HEAD; each artifact exists and is non-empty.
+3a. Spawn lazycodex-code-reviewer and lazycodex-qa-executor in parallel (`fork_context: false` on v1; `fork_turns: "none"` on v2) with brief, goals, desired outcome, diff, evidence; wait for BOTH and confirm their report artifacts exist on disk.
+3b. Only then spawn lazycodex-gate-reviewer with those artifact paths.
+4. Treat timeout, missing deliverable, ack-only, `BLOCKED:`, or inconclusive review as a blocker. Any fix restarts the freeze at the new HEAD: re-run ONLY the proofs it invalidated and stamp the fresh output — never regenerate all evidence or relabel stale output to HEAD — re-review the delta at most TWICE; then record-review-blockers (step 5) and surface to the user.
 5. If review remains blocked, run `omo ulw-loop record-review-blockers --goal-id <id> --title "<...>" --objective "<...>" --evidence "<review findings>" --codex-goal-json <snapshot> --json`.
 6. If clean, checkpoint final completion:
 ```sh
@@ -201,7 +203,7 @@ omo ulw-loop checkpoint --goal-id <id> --status complete --evidence "<e2e eviden
   "criteriaCoverage":{"totalCriteria":3,"passCount":3,"originalIntent":"User wanted artifact-backed completion.","desiredOutcome":"Behavior ships with review and QA evidence.","userOutcomeReview":"Result matches brief and goals.","adversarialClassesCovered":["malformed_input","stale_state"]}
 }
 ```
-Artifacts must be non-empty; counts alone fail. LIGHT without adversarial class records `"adversarialClassesCovered": ["none-applicable: <reason>"]`.
+Artifacts must be non-empty; counts alone fail. LIGHT without adversarial class records `"adversarialClassesCovered": ["none-applicable: <reason>"]`; untriggered adversarialCases may use verdict `not_applicable` + `reason`; WATCH passes, notes surfaced.
 
 ## Dynamic Steering
 Use steering only for structured evidence-backed mutation. Reject natural-language steering requests.
@@ -222,18 +224,18 @@ Structured prompt directives accepted: `OMO_ULW_LOOP_STEER: { ... }`, `omo.ulw-l
 ## Constraints
 1. NEVER call `update_goal` mid-aggregate; only on final story after the quality gate passes.
 2. NEVER call `create_goal` when `get_goal` shows a different active goal.
-3. NEVER mark `criterion.status == "pass"` without captured observable evidence in `record-evidence`.
+3. Evidence is bound to the commit it was captured at; a later fix, rebase, or merge invalidates it — re-run the QA at the current HEAD and re-record. NEVER mark PASS from memory, and NEVER relabel, pin, refresh, or regenerate prior output to a moved HEAD.
 4. NEVER bypass the criteria gate: non-final aggregate completion requires all essential criteria; final aggregate completion requires all criteria across the whole plan.
 5. Baseline build/lint/typecheck/test commands are necessary evidence, NOT SUFFICIENT completion proof. Criteria coverage with observable evidence is the gate.
 6. Treat `.omo/ulw-loop/ledger.jsonl` as the durable audit trail; checkpoint after every success or failure.
 7. Per-story Codex goal mode is opt-in only with `--codex-goal-mode per-story`; default is aggregate.
 8. Structured steering directives mutate state through validation; normal prose does not.
-9. Evidence MUST be observable from the real surface: tmux transcript, curl status+body, Browser plugin action result or browser/Playwright assertion, CLI stdout, DB state diff, parsed config dump.
+9. Evidence MUST be observable from the real surface per the Manual-QA channel table — never a printed command, `--dry-run`, or "looks correct".
 10. Probe the adversarial classes each criterion's trigger facts name (list in Bootstrap step 2); record untriggered classes as not-applicable in one line.
 11. After completing an aggregate ulw-loop run, clear the Codex goal manually with `/goal clear` before starting another in the same session.
 12. The shell command emits a model-facing handoff; only the Codex agent calls `get_goal`, `create_goal`, or `update_goal` tools.
-13. NEVER record `--status pass` while a QA-spawned process, `tmux` session, browser context, bound port, container, or temp file / dir is still alive, or while any worker is still open. The evidence string MUST include the cleanup receipt. Leftover runtime state = BLOCKED, not PASS.
-14. DELEGATE all code edits, test writes, fixes, and QA execution to right-sized `multi_agent_v1.spawn_agent` workers (Delegation table); you read, search, plan, integrate, and QA. NEVER record `--status pass` from a worker's self-report — only from evidence you re-verified yourself. Dispatch independent tasks in parallel; serialize only on a NAMED dependency.
+13. NEVER record PASS while any QA-spawned process, `tmux` session, browser context, bound port, container, temp path, or open worker is still alive; the evidence MUST carry the cleanup receipt. Leftover state = BLOCKED.
+14. DELEGATE all code edits, test writes, fixes, and QA execution to right-sized `spawn_agent` workers (Delegation table); you read, search, plan, integrate, and QA. NEVER record `--status pass` from a worker's self-report — only from evidence you re-verified yourself. Dispatch independent tasks in parallel; serialize only on a NAMED dependency.
 15. Every verified work unit that touched git-tracked files must leave either an atomic `git-master`-style commit hash or explicit no-commit blocker evidence before the next unit starts.
 
 ## Stop Rules

package/packages/omo-codex/plugin/components/ulw-loop/src/checkpoint.ts

@@ -1,3 +1,4 @@
+import { ulwLoopAttemptEvidenceDir } from "./paths.js";
 import { existsSync, statSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
@@ -136,12 +137,13 @@ function buildLedger(
 	codexGoal: unknown,
 	aggregateCompletion: UlwLoopAggregateCompletion | undefined,
 ): UlwLoopLedgerEntry {
+	const watch = qualityGate?.codeReview.codeQualityStatus === "WATCH";
 	const entry: UlwLoopLedgerEntry = {
 		at: now,
 		kind: ledgerKind(args.status, goal, aggregateCompletion),
 		goalId: goal.id,
 		status: goal.status,
-		evidence: args.evidence,
+		evidence: watch ? `${args.evidence} | codeQuality=WATCH: ${qualityGate.codeReview.evidence}` : args.evidence,
 	};
 	if (codexGoal !== undefined) entry.codexGoal = codexGoal;
 	if (qualityGate !== undefined) entry.qualityGate = qualityGate;
@@ -221,6 +223,9 @@ export async function checkpointUlwLoop(
 				qualityGate = validateQualityGate(await readJsonInput(args.qualityGateJson, repoRoot), {
 					repoRoot,
 					fs: QUALITY_GATE_FS,
+					...(plan.evidenceLayoutVersion === 2
+						? { currentAttemptDir: ulwLoopAttemptEvidenceDir(goal.id, goal.attempt, scope) }
+						: {}),
 				});
 			goal.status = "complete";
 			goal.completedAt = now;

package/packages/omo-codex/plugin/components/ulw-loop/src/cli-subcommands.ts

@@ -14,7 +14,7 @@ import { parseSteeringProposal, printSteerResult } from "./cli-steering.js";
 import { buildCodexGoalInstruction } from "./codex-goal-instruction.js";
 import { recordEvidence } from "./evidence.js";
 import { isEssentialCriterion } from "./goal-status.js";
-import type { UlwLoopScope } from "./paths.js";
+import { type UlwLoopScope, ulwLoopAttemptEvidenceDir } from "./paths.js";
 import { addUlwLoopGoal, createUlwLoopPlan, startNextUlwLoop, summarizeUlwLoopPlan } from "./plan-crud.js";
 import { readUlwLoopPlan } from "./plan-io.js";
 import { recordFinalReviewBlockers } from "./review-blockers.js";
@@ -62,8 +62,19 @@ export async function createGoals(
 
 export async function status(repoRoot: string, json: boolean, scope?: UlwLoopScope): Promise<number> {
 	const plan = await readUlwLoopPlan(repoRoot, scope);
-	if (json) printJson({ ok: true, plan, summary: summarizeUlwLoopPlan(plan) });
-	else printStatus(plan);
+	if (json) {
+		const active = plan.goals.find((goal) => goal.id === plan.activeGoalId);
+		const currentAttemptDir =
+			plan.evidenceLayoutVersion === 2 && active
+				? ulwLoopAttemptEvidenceDir(active.id, active.attempt, scope)
+				: undefined;
+		printJson({
+			ok: true,
+			plan,
+			summary: summarizeUlwLoopPlan(plan),
+			...(currentAttemptDir === undefined ? {} : { currentAttemptDir }),
+		});
+	} else printStatus(plan);
 	return 0;
 }
 

package/packages/omo-codex/plugin/components/ulw-loop/src/cli.ts

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import { isUlwLoopSubcommand, ulwLoopCommand } from "./cli-commands.js";
 import { runPreToolUseGoalBudgetGuardCli, runUlwLoopHookCli } from "./codex-hook.js";
+import { runSpawnGuardCli } from "./spawn-guard.js";
+import { runStopResumeHookCli } from "./stop-resume-hook.js";
 
 const TOP_LEVEL_HELP =
 	"Usage:\n  omo ulw-loop <subcommand> [args]\n  omo hook user-prompt-submit [--with-ultrawork]  (Codex UserPromptSubmit hook)\n  omo help | --help | -h                          (this message)\n\nRun `omo ulw-loop help` for ulw-loop subcommands.\n";
@@ -25,6 +27,14 @@ async function main(): Promise<number> {
 			await runPreToolUseGoalBudgetGuardCli(process.stdin, process.stdout);
 			return 0;
 		}
+		if (sub === "stop") {
+			await runStopResumeHookCli(process.stdin, process.stdout);
+			return 0;
+		}
+		if (sub === "pre-tool-use-spawn") {
+			await runSpawnGuardCli(process.stdin, process.stdout);
+			return 0;
+		}
 		process.stderr.write(`[omo] unknown hook subcommand: ${sub ?? "(none)"}\n`);
 		return 1;
 	}

package/packages/omo-codex/plugin/components/ulw-loop/src/codex-goal-instruction.ts

@@ -52,6 +52,7 @@ function buildText(
 		"- Use the create_goal payload exactly as rendered: objective only.",
 		"- Goals are unlimited. Do not add numeric limits.",
 		...modeConstraintLines(mode, isFinal),
+		...evidenceLayoutLines(plan),
 		finalSection(plan, goal, isFinal, mode === "aggregate"),
 		...checkpointLines(plan, mode),
 		"",
@@ -103,6 +104,13 @@ function formatCriterionLine(criterion: UlwLoopSuccessCriterion): string {
 	return `-${remainingWork} [${criterion.id}] [${marker}] (${criterion.userModel}) ${criterion.scenario} — expect: ${criterion.expectedEvidence} — status: ${criterion.status}`;
 }
 
+function evidenceLayoutLines(plan: UlwLoopPlan): string[] {
+	if (plan.evidenceLayoutVersion !== 2) return [];
+	return [
+		"- Evidence layout v2: write every artifact for the active goal (QA matrix, review reports, receipts) under the current attempt directory — read currentAttemptDir from `omo ulw-loop status --json` (.omo/evidence/ulw/<session>/<goalId>/a<attempt>). The final checkpoint rejects quality-gate artifacts outside that directory.",
+	];
+}
+
 function finalSection(plan: UlwLoopPlan, goal: UlwLoopItem, isFinal: boolean, aggregate: boolean): string {
 	if (!isFinal)
 		return "- This is not the final ulw-loop story; do not run the final reviewer/manual-QA/gate-review quality gate yet.";
@@ -113,8 +121,11 @@ function finalSection(plan: UlwLoopPlan, goal: UlwLoopItem, isFinal: boolean, ag
 		"Final story — run mandatory quality gate before update_goal:",
 		"- Run targeted verification for changed behavior.",
 		"- Confirm every manualQa artifact path exists and has non-zero size.",
-		"- Spawn final reviewers with fork_context=false: lazycodex-code-reviewer, lazycodex-qa-executor, and lazycodex-gate-reviewer. Include the original brief, goal objectives, desired user-visible outcome, diff, and evidence.",
+		"- First spawn lazycodex-code-reviewer and lazycodex-qa-executor in parallel (fork_context: false on the v1 surface; fork_turns: \"none\" on v2). Include the original brief, goal objectives, desired user-visible outcome, diff, and evidence; wait for BOTH to return and confirm their report artifacts exist on disk (code-review report + manualQa matrix).",
+		"- Only then spawn lazycodex-gate-reviewer (same fork settings), passing those artifact paths.",
 		"- Require clean codeReview, manualQa, gateReview, iteration, and criteriaCoverage. criteriaCoverage must summarize originalIntent, desiredOutcome, and userOutcomeReview; counts alone are not approval.",
+		"- On a reviewer REJECT, fix only the cited blockers, rerun the affected verification/Manual-QA, and re-review the delta at most TWICE; if blockers remain, record them and surface to the user.",
+		"- If codeQualityStatus is WATCH, include the WATCH notes verbatim in your final user-facing message.",
 		"- If any reviewer is blocked/inconclusive or the quality gate is not clean, do not call update_goal. Record blocker work first:",
 		`  ${blockerCommand}`,
 		aggregate

package/packages/omo-codex/plugin/components/ulw-loop/src/domain-types.ts

@@ -57,6 +57,7 @@ export interface UlwLoopAggregateCompletion {
 
 export interface UlwLoopPlan {
 	version: 1;
+	evidenceLayoutVersion?: 2;
 	createdAt: string;
 	updatedAt: string;
 	briefPath: string;
@@ -94,7 +95,8 @@ export interface UlwLoopManualQaAdversarialCase {
 	readonly criterionRef: string;
 	readonly scenario: string;
 	readonly expectedBehavior: string;
-	readonly verdict: "passed";
+	readonly verdict: "passed" | "not_applicable";
+	readonly reason?: string;
 	readonly artifactRefs: readonly string[];
 }
 
@@ -102,7 +104,7 @@ export interface UlwLoopQualityGate {
 	readonly codeReview: {
 		readonly by: string;
 		readonly recommendation: "APPROVE";
-		readonly codeQualityStatus: "CLEAR";
+		readonly codeQualityStatus: "CLEAR" | "WATCH";
 		readonly reportPath: string;
 		readonly evidence: string;
 		readonly blockers: readonly [];

package/packages/omo-codex/plugin/components/ulw-loop/src/paths.ts

@@ -1,4 +1,4 @@
-import { join } from "node:path";
+import { isAbsolute, join, relative, sep } from "node:path";
 import { ULW_LOOP_BRIEF, ULW_LOOP_DIR, ULW_LOOP_GOALS, ULW_LOOP_LEDGER } from "./types.js";
 
 export interface UlwLoopScope {
@@ -71,3 +71,29 @@ export function repoRelative(absolutePath: string, repoRoot: string): string {
 		return absolutePath.slice(backslashPrefix.length).split("\\").join("/");
 	return absolutePath.split("\\").join("/");
 }
+
+// Both the status --json emitter and the checkpoint enforcement resolve the attempt dir through
+// this function; a second resolution path would let the gate reject its own advertised directory.
+export function ulwLoopAttemptEvidenceDir(goalId: string, attempt: number, scope?: UlwLoopScope): string {
+	const sessionId = normalizeUlwLoopSessionId(scope?.sessionId) ?? resolveUlwLoopSessionIdFromEnv() ?? "session";
+	return `.omo/evidence/ulw/${sessionId}/${goalId}/a${attempt}`;
+}
+
+interface AttemptPathApi {
+	relative(from: string, to: string): string;
+	isAbsolute(path: string): boolean;
+	readonly sep: string;
+}
+
+const PLATFORM_PATH_API: AttemptPathApi = { relative, isAbsolute, sep };
+
+export function isWithinAttemptDir(
+	absolutePath: string,
+	attemptRoot: string,
+	pathApi: AttemptPathApi = PLATFORM_PATH_API,
+): boolean {
+	const relativePath = pathApi.relative(attemptRoot, absolutePath);
+	if (relativePath === "") return true;
+	if (relativePath === ".." || relativePath.startsWith(`..${pathApi.sep}`)) return false;
+	return !pathApi.isAbsolute(relativePath);
+}

package/packages/omo-codex/plugin/components/ulw-loop/src/plan-crud.ts

@@ -75,6 +75,7 @@ export async function createUlwLoopPlan(
 		);
 		const plan: UlwLoopPlan = {
 			version: 1,
+			evidenceLayoutVersion: 2,
 			createdAt: now,
 			updatedAt: now,
 			briefPath: ulwLoopBriefRelativePath(scope),

package/packages/omo-codex/plugin/components/ulw-loop/src/quality-gate-verdicts.ts

@@ -0,0 +1,23 @@
+import { literal, invalid, textField } from "./quality-gate-fields.js";
+
+export function passedVerdict(value: unknown, field: string): "passed" {
+	if (value === "not_applicable") invalid(`${field} must not be not_applicable.`, field);
+	return literal(value, "passed", field);
+}
+
+export function codeQualityStatusField(value: unknown, field: string): "CLEAR" | "WATCH" {
+	if (value === "CLEAR" || value === "WATCH") return value;
+	invalid(`${field} must be CLEAR or WATCH.`, field);
+}
+
+export function adversarialVerdict(
+	row: Record<string, unknown>,
+	field: string,
+): { verdict: "passed" | "not_applicable"; reason?: string } {
+	const value = row["verdict"];
+	if (value === "passed") return { verdict: "passed" };
+	if (value === "not_applicable") {
+		return { verdict: "not_applicable", reason: textField(row["reason"], `${field}.reason`) };
+	}
+	invalid(`${field} must be passed or not_applicable with a reason.`, field);
+}

package/packages/omo-codex/plugin/components/ulw-loop/src/quality-gate.ts

@@ -1,4 +1,5 @@
 import { resolve } from "node:path";
+import { isWithinAttemptDir } from "./paths.js";
 import {
 	emptyBlockers,
 	invalid,
@@ -8,6 +9,7 @@ import {
 	stringArray,
 	textField,
 } from "./quality-gate-fields.js";
+import { adversarialVerdict, codeQualityStatusField, passedVerdict } from "./quality-gate-verdicts.js";
 import type {
 	UlwLoopManualQaArtifactKind,
 	UlwLoopManualQaArtifactRef,
@@ -36,6 +38,7 @@ export interface QualityGateFs {
 export interface ValidateQualityGateOptions {
 	readonly repoRoot: string;
 	readonly fs: QualityGateFs;
+	readonly currentAttemptDir?: string;
 }
 
 function reviewerRoleField<T extends string>(value: unknown, expected: T, field: string): T {
@@ -70,11 +73,6 @@ function kindField(value: unknown, field: string): UlwLoopManualQaArtifactKind {
 	invalid(`${field} must be a supported artifact kind.`, field);
 }
 
-function passedVerdict(value: unknown, field: string): "passed" {
-	if (value === "not_applicable") invalid(`${field} must not be not_applicable.`, field);
-	return literal(value, "passed", field);
-}
-
 function artifactCompatible(surface: UlwLoopManualQaSurface, kind: UlwLoopManualQaArtifactKind): boolean {
 	switch (surface) {
 		case "cli":
@@ -96,8 +94,15 @@ function checkFile(path: string, field: string, opts?: ValidateQualityGateOption
 	if (opts === undefined) return;
 	const absolute = resolve(opts.repoRoot, path);
 	if (!opts.fs.existsSync(absolute)) invalid(`${field} must point to an existing artifact.`, field);
-	const stat = opts.fs.statSync(absolute);
-	if (stat.size <= 0) invalid(`${field} must point to a non-empty artifact.`, field);
+	if (opts.fs.statSync(absolute).size <= 0) invalid(`${field} must point to a non-empty artifact.`, field);
+	if (opts.currentAttemptDir !== undefined) {
+		const attemptRoot = resolve(opts.repoRoot, opts.currentAttemptDir);
+		if (!isWithinAttemptDir(absolute, attemptRoot))
+			invalid(
+				`${field} (${path}) must point to an artifact from the current attempt (${opts.currentAttemptDir}).`,
+				field,
+			);
+	}
 }
 
 function artifactMap(refs: readonly UlwLoopManualQaArtifactRef[]): Map<string, UlwLoopManualQaArtifactRef> {
@@ -160,7 +165,7 @@ export function validateQualityGate(input: unknown, opts?: ValidateQualityGateOp
 		codeReview: {
 			by: reviewerRoleField(codeReview["by"], REVIEWER_ROLES.codeReview, "codeReview.by"),
 			recommendation: literal(codeReview["recommendation"], "APPROVE", "codeReview.recommendation"),
-			codeQualityStatus: literal(codeReview["codeQualityStatus"], "CLEAR", "codeReview.codeQualityStatus"),
+			codeQualityStatus: codeQualityStatusField(codeReview["codeQualityStatus"], "codeReview.codeQualityStatus"),
 			reportPath: codeReportPath,
 			evidence: textField(codeReview["evidence"], "codeReview.evidence"),
 			blockers: emptyBlockers(codeReview["blockers"], "codeReview.blockers"),
@@ -246,12 +251,14 @@ function parseAdversarialCases(
 			`manualQa.adversarialCases[${index}].artifactRefs`,
 			byId,
 		);
+		const verdictInfo = adversarialVerdict(row, `manualQa.adversarialCases[${index}]`);
 		return {
 			id: textField(row["id"], `manualQa.adversarialCases[${index}].id`),
 			criterionRef: textField(row["criterionRef"], `manualQa.adversarialCases[${index}].criterionRef`),
 			scenario: textField(row["scenario"], `manualQa.adversarialCases[${index}].scenario`),
 			expectedBehavior: textField(row["expectedBehavior"], `manualQa.adversarialCases[${index}].expectedBehavior`),
-			verdict: passedVerdict(row["verdict"], `manualQa.adversarialCases[${index}].verdict`),
+			verdict: verdictInfo.verdict,
+			...(verdictInfo.reason === undefined ? {} : { reason: verdictInfo.reason }),
 			artifactRefs: artifacts.map((artifact) => artifact.id),
 		};
 	});

package/packages/omo-codex/plugin/components/ulw-loop/src/spawn-guard.ts

@@ -0,0 +1,138 @@
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { PreToolUsePayload } from "./codex-hook.js";
+import { parsePreToolUsePayload } from "./codex-hook.js";
+import { isFinalRunCompletionCandidate } from "./goal-status.js";
+import { ulwLoopAttemptEvidenceDir, ulwLoopDir } from "./paths.js";
+import type { UlwLoopPlan } from "./types.js";
+
+// spawn_agent = v1; collaborationspawn_agent = the delimiter-free flattened v2
+// hook token from codex-rs hook_names.rs; collaboration.spawn_agent = the
+// dotted token observed live in the task-1 probe (hook-tool-tokens.txt).
+const SPAWN_TOOL_TOKENS = new Set(["spawn_agent", "collaborationspawn_agent", "collaboration.spawn_agent"]);
+const DEFAULT_FANOUT_LIMIT = 60;
+const GATE_MESSAGE_PATTERN = /lazycodex-gate-reviewer|final gate review/i;
+
+export function applySpawnGuards(payload: PreToolUsePayload): string {
+	if (payload.hook_event_name !== "PreToolUse" || !SPAWN_TOOL_TOKENS.has(payload.tool_name)) return "";
+	const stateDir = ulwLoopDir(payload.cwd, { sessionId: payload.session_id });
+	const plan = readPlan(join(stateDir, "goals.json"));
+	if (plan === null) return "";
+	const fanOutDenial = consumeFanOutBudget(stateDir);
+	if (fanOutDenial !== null) return deny(fanOutDenial);
+	const missingArtifact = missingGateArtifact(payload, plan);
+	if (missingArtifact !== null)
+		return deny(`spawn code-review + QA first; gate audits their artifacts: missing ${missingArtifact}`);
+	return "";
+}
+
+export async function runSpawnGuardCli(stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream): Promise<void> {
+	try {
+		const chunks: Buffer[] = [];
+		for await (const chunk of stdin) chunks.push(Buffer.from(chunk));
+		const payload = parsePreToolUsePayload(Buffer.concat(chunks).toString("utf8"));
+		if (payload === null) return;
+		const output = applySpawnGuards(payload);
+		if (output.length > 0) stdout.write(output);
+	} catch (error) {
+		if (error instanceof Error) return;
+	}
+}
+
+// Per-session spawn counter; depth/lineage tracking is descoped — this is a
+// total-volume backstop against fan-out explosions, not a recursion tracker.
+function consumeFanOutBudget(stateDir: string): string | null {
+	const counterPath = join(stateDir, "spawn-count.json");
+	const count = readCount(counterPath) + 1;
+	writeFileSync(counterPath, JSON.stringify({ count }));
+	const limit = fanOutLimit();
+	if (count <= limit) return null;
+	return `ulw-loop spawn fan-out cap reached (${count}/${limit}). Consolidate work into the agents already running, or raise OMO_SPAWN_FANOUT_LIMIT if this volume is intentional.`;
+}
+
+function missingGateArtifact(payload: PreToolUsePayload, plan: UlwLoopPlan): string | null {
+	if (!isGateReviewerSpawn(payload.tool_input)) return null;
+	const goal = plan.goals.find((candidate) => isFinalRunCompletionCandidate(plan, candidate));
+	if (goal === undefined || goal.status === "complete") return null;
+	if (!goal.successCriteria.every((criterion) => criterion.status === "pass")) return null;
+	const scope = { sessionId: payload.session_id } as const;
+	if (plan.evidenceLayoutVersion === 2) {
+		const attemptDir = ulwLoopAttemptEvidenceDir(goal.id, goal.attempt, scope);
+		for (const name of [`${goal.id}-code-review.md`, `${goal.id}-manual-qa.md`]) {
+			const relative = `${attemptDir}/${name}`;
+			if (!isNonEmptyFile(join(payload.cwd, relative))) return relative;
+		}
+		return null;
+	}
+	const flatReport = `.omo/evidence/${goal.id}-code-review.md`;
+	if (!isNonEmptyFile(join(payload.cwd, flatReport))) return flatReport;
+	// v1 manual-QA approximation: any other non-empty evidence file counts.
+	if (!hasOtherEvidenceFile(join(payload.cwd, ".omo", "evidence"), `${goal.id}-code-review.md`))
+		return `.omo/evidence/<any manual-QA artifact besides ${goal.id}-code-review.md>`;
+	return null;
+}
+
+function isGateReviewerSpawn(toolInput: unknown): boolean {
+	if (typeof toolInput !== "object" || toolInput === null) return false;
+	const record = toolInput as Record<string, unknown>;
+	const agentType = record["agent_type"];
+	if (typeof agentType === "string") return agentType === "lazycodex-gate-reviewer";
+	const message = record["message"];
+	return typeof message === "string" && GATE_MESSAGE_PATTERN.test(message);
+}
+
+function deny(reason: string): string {
+	return `${JSON.stringify({
+		hookSpecificOutput: {
+			hookEventName: "PreToolUse",
+			permissionDecision: "deny",
+			permissionDecisionReason: reason,
+			additionalContext: reason,
+		},
+	})}\n`;
+}
+
+function fanOutLimit(): number {
+	const raw = process.env["OMO_SPAWN_FANOUT_LIMIT"];
+	if (raw === undefined) return DEFAULT_FANOUT_LIMIT;
+	const parsed = Number.parseInt(raw, 10);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_FANOUT_LIMIT;
+}
+
+function isNonEmptyFile(path: string): boolean {
+	try {
+		return existsSync(path) && statSync(path).size > 0;
+	} catch (error) {
+		if (error instanceof Error) return false;
+		throw error;
+	}
+}
+
+function hasOtherEvidenceFile(evidenceDir: string, excludedName: string): boolean {
+	try {
+		return readdirSync(evidenceDir).some((name) => name !== excludedName && isNonEmptyFile(join(evidenceDir, name)));
+	} catch (error) {
+		if (error instanceof Error) return false;
+		throw error;
+	}
+}
+
+function readCount(counterPath: string): number {
+	try {
+		const parsed = JSON.parse(readFileSync(counterPath, "utf8")) as Record<string, unknown>;
+		return typeof parsed["count"] === "number" && parsed["count"] >= 0 ? parsed["count"] : 0;
+	} catch (error) {
+		if (error instanceof Error) return 0;
+		throw error;
+	}
+}
+
+function readPlan(goalsPath: string): UlwLoopPlan | null {
+	try {
+		return JSON.parse(readFileSync(goalsPath, "utf8")) as UlwLoopPlan;
+	} catch (error) {
+		if (error instanceof Error) return null;
+		throw error;
+	}
+}