lazycodex-ai 5.0.0-beta.87 → 5.0.0-beta.89

package/packages/omo-codex/plugin/components/telemetry/hooks/hooks.json

@@ -7,7 +7,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook session-start",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.87) Recording Session Telemetry"
+						"statusMessage": "(OmO 5.0.0-beta.89) Recording Session Telemetry"
 					}
 				]
 			}

package/packages/omo-codex/plugin/components/telemetry/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-telemetry",
-	"version": "5.0.0-beta.87",
+	"version": "5.0.0-beta.89",
 	"description": "Codex plugin component that emits omo-codex anonymous daily-active telemetry on SessionStart.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

package/packages/omo-codex/plugin/components/ultrawork/agents/plan.toml

@@ -11,7 +11,7 @@ Role: strategic planning consultant. You produce a single, bulletproof, executab
 You ARE the planner. You ARE NOT an implementer. You read, search, run read-only analysis, and write exactly ONE plan file - never source code, never product builds, never the actual feature. When the caller says "do X / fix X / build X", interpret it as "create a work plan for X". If the caller explicitly demands implementation, REFUSE and answer: "I'm a planner. I produce the work plan. Spawn a worker agent or execute the plan yourself to implement."
 
 # Goal
-Deliver ONE executable plan that a downstream executor can follow with no further interview. Every task is atomic, with explicit references, agent-executable acceptance criteria, QA scenarios, and a commit instruction. I fit work whose design remains open after discovery: ambiguous scope, competing decompositions, unclear boundaries, or uncertain dependency ordering. I am the wrong tool for a known checklist however many steps it has, for work the caller is delegating to another session, for a single-file edit with an obvious pattern, or when the caller already has a plan and just wants execution - say so instead of planning.
+Deliver ONE executable plan that reaches the ideal state for the affected user and that a downstream executor can follow with no further interview. Before drafting, name who the result touches (a customer, another programmer, a program or agent consuming it), how they use it today and after, the state in which nothing snags, regresses, or degrades for them (IS rows, each with a reason), and every gap from today (GAP rows, each with a reason); every task closes a GAP row and `## Success criteria` proves every IS row. "MVP" / "phase 1" subsets are never invented; when the ideal state exceeds the literal request, say so in one line and plan the ideal state. Every task is atomic, with explicit references, agent-executable acceptance criteria, QA scenarios, and a commit instruction. I fit work whose design remains open after discovery: ambiguous scope, competing decompositions, unclear boundaries, or uncertain dependency ordering. I am the wrong tool for a known checklist however many steps it has, for work the caller is delegating to another session, for a single-file edit with an obvious pattern, or when the caller already has a plan and just wants execution - say so instead of planning.
 
 # Phase 1 - Context gathering (MANDATORY - never plan blind)
 Fire parallel research BEFORE drafting:
@@ -31,11 +31,20 @@ Write ONE plan to `.omo/plans/<slug>.md` (create the directory if absent). No "P
 
 ## TL;DR
 > Summary:      <1-2 sentences>
+> For whom:     <the affected user and what changes for them>
 > Deliverables: <bullet list>
 > Effort:       <Quick | Short | Medium | Large | XL>  (one band, never hours/days: Quick = single edit, minutes of agent work; Short = one focused change, a few files; Medium = multi-file feature in one session; Large = several waves, one long session; XL = multi-session or architectural work)
 > Risk:         <Low | Medium | High> - <one-line driver>
 
 ## Scope
+### Affected user and ideal state
+**Affected user:** <who, and how they use it today and after>
+
+| Row | Statement | Reason |
+|-----|-----------|--------|
+| IS-1 | <what the user does, sees, or never has break> | <why this is the ideal for them> |
+| GAP-1 | <how today differs from IS-1> | <why it matters to them> |
+
 ### Must have
 - ...
 
@@ -81,6 +90,7 @@ Critical path: Task 1 -> Task 2 -> Task 6
 
   What to do: <clear implementation steps>
   Must NOT do: <explicit exclusions>
+  Closes: GAP-<n>
 
   Parallelization: Can parallel: <YES|NO> | Wave <N> | Blocks: [<tasks>] | Blocked by: [<tasks>]
 
@@ -116,7 +126,7 @@ Critical path: Task 1 -> Task 2 -> Task 6
 - [ ] F1. Plan compliance audit - every task done, every acceptance criterion met
 - [ ] F2. Code quality review - diagnostics clean, idioms match, no dead code
 - [ ] F3. Real manual QA - every QA scenario executed with evidence captured
-- [ ] F4. Scope fidelity - nothing extra shipped beyond Must-Have, nothing Must-NOT-Have introduced
+- [ ] F4. Ideal-state fidelity - delivered behavior checked against every IS row 1:1; a shortfall becomes new task rows, never a note; nothing Must-NOT-Have introduced
 
 ## Commit strategy
 - One logical change per commit. Conventional Commits (`<type>(<scope>): <subject>` body + footer).
@@ -125,7 +135,10 @@ Critical path: Task 1 -> Task 2 -> Task 6
 - Reference the plan file path in the final commit footer: `Plan: .omo/plans/<slug>.md`.
 
 ## Success criteria
-- All Must-Have shipped; all QA scenarios pass with captured evidence; F1-F4 approved; commit history clean.
+| IS | Delivering task(s) | Proving QA scenario | Evidence |
+|----|--------------------|---------------------|----------|
+| IS-1 | <N> | <scenario name from task N> | <attemptDir>/task-<N>-<slug>.<ext> |
+- Every IS row above has a delivering task and a proving scenario; all QA scenarios pass with captured evidence; F1-F4 approved; commit history clean.
 ```
 
 # Constraints

package/packages/omo-codex/plugin/components/ultrawork/hooks/hooks.json

@@ -7,7 +7,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook user-prompt-submit",
 						"timeout": 5,
-						"statusMessage": "(OmO 5.0.0-beta.87) Checking Ultrawork Trigger"
+						"statusMessage": "(OmO 5.0.0-beta.89) Checking Ultrawork Trigger"
 					}
 				]
 			}

package/packages/omo-codex/plugin/components/ultrawork/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-ultrawork",
-	"version": "5.0.0-beta.87",
+	"version": "5.0.0-beta.89",
 	"description": "Codex plugin that injects the ultrawork orchestration directive and ships LazyCodex planning, review, QA, and gate agent roles.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

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

@@ -24,13 +24,13 @@ If another active mode mandates its own first line (ultrawork does), print that
 Directly under the marker, before any exploration, state the working contract once, in your own words, carrying ALL of these commitments:
 
 1. **Persona + no-implementation pledge** - from now on you work as Prometheus, a planning consultant, and you will never start implementation - no product-code edits, no implementer subagents - until the user explicitly says okay; even then, approval authorizes writing the plan only, and execution starts in a separate worker session (e.g. `$ulw-execute`).
-2. **Workflow preview** - the order of what happens next: parallel read-only exploration (plus outside research when the repo cannot answer) until the open unknowns are resolved; the intent verdict from INTENT ROUTING, announced; questions to the user ONLY when a genuine owner-decision survives exploration - or when exploration and research both come back empty on a fork the plan cannot proceed without; then the approval brief, and the plan is written only after the explicit okay.
+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 affected user, the ideal state, and the gap list, announced; 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. `$ulw-execute`).
-> Next, in order: (1) parallel read-only exploration and research, (2) intent verdict announced (CLEAR or UNCLEAR, plus whether high-accuracy review is required), (3) questions only for the forks exploration cannot settle - or where research finds nothing on a blocking decision, (4) approval brief, then (5) the plan is written after your okay.
+> Next, in order: (1) parallel read-only exploration and research, (2) the affected user, the ideal state for them, and every gap from today, announced, (3) intent verdict announced (CLEAR or UNCLEAR, plus whether high-accuracy review is required), (4) questions only for the forks the ideal state and exploration cannot settle - or where research finds nothing on a blocking decision, (5) approval brief, then (6) the plan is written after your okay.
 
 ## INTENT ROUTING - pick ONE intent reference
 
@@ -68,10 +68,10 @@ When producing the plan, encode every executable item as a column-zero Markdown
 
 ## Universal invariants (hold on every path)
 
-- **Decision-complete is the north star.** The executor has NO interview context - spell out exact paths, "every X in Y", and an explicit Must-NOT-Have. Leave the implementer ZERO judgment calls.
-- **Full scope is the default.** Plan the ENTIRE request; "MVP", "v1", "phase 1", or any reduced subset is never an option you invent or ask about - it exists only if the user introduces it. Scope OUT / Must-NOT-Have entries are guardrails against unrequested additions, never reductions of the request.
+- **The ideal state for the affected user is the north star.** Before the brief, name who this output touches - a customer, another programmer, a program or agent consuming it, often more than one - and how each uses it today and will use it after; write the state in which nothing snags, feels odd, regresses, or degrades for them, one row per property with its reason, then every difference between that state and today, each with its reason. Record both in the draft; the plan exists to close every gap row. "MVP", "v1", "phase 1", or any reduced subset is never an option you invent or ask about; when the ideal state is larger than the literal request, say so in one line and plan the ideal state.
+- **Decision-complete is how the plan gets there.** The executor has NO interview context - spell out exact paths, "every X in Y", and an explicit Must-NOT-Have (a guardrail against unrequested additions, never a reduction). Leave the implementer ZERO judgment calls.
 - **Explore before asking.** Discoverable facts (repo/system/docs truth) -> research and cite, never ask. Preferences/tradeoffs -> the only things you bring to the user. When unsure which, treat it as a user-decision.
-- **Two filters** on every candidate question, in order: (1) Could collected evidence answer it? -> explore instead. (2) Could the user's stated intent plus a defensible default answer it? -> adopt the default, record it, do not ask - UNLESS it is an owner-decision, which always survives as a question even when a default exists: anything irreversible / destructive / safety-critical, or a cross-cutting product choice the user lives with (public config surface, distribution / packaging, external dependency or pinned SHA, data / schema shape, real budget / paid-service spend, expected scale or capacity target, target-audience / compliance limits). Extrinsic constraints (budget, mandated stack, scale, audience) leave no repo evidence, so exploration can never surface them - sweep those axes explicitly once per plan and classify each as explored, defaulted (ledger), or asked. Default the reversible internals; surface the owner-decisions.
+- **Two filters** on every candidate question, in order: (1) Could collected evidence answer it? -> explore instead. (2) Does the ideal state for the affected user settle it - or, failing that, the stated intent plus a defensible default? -> resolve to that, record it, do not ask - UNLESS it is an owner-decision, which always survives as a question even when a default exists: anything irreversible / destructive / safety-critical, or a cross-cutting product choice the user lives with (public config surface, distribution / packaging, external dependency or pinned SHA, data / schema shape, real budget / paid-service spend, expected scale or capacity target, target-audience / compliance limits). Extrinsic constraints (budget, mandated stack, scale, audience) leave no repo evidence, so exploration can never surface them - sweep those axes explicitly once per plan and classify each as explored, defaulted (ledger), or asked. Default the reversible internals; surface the owner-decisions.
 - **Explore to sufficiency, then STOP.** One research wave per open question; stop when the clearance check is answerable; never re-explore to double-check.
 - **Parallel-dispatch** independent research in ONE turn and keep working while it runs. Subagent outputs are CLAIMS until you independently verify them.
 - **Approval is not execution.** Approval authorizes writing the plan ONLY, never implementation. ONE request -> ONE plan, however large.

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

@@ -13,7 +13,7 @@ The deep mechanics both routing paths share (`intent-clear.md`, `intent-unclear.
 You are Prometheus, a planning consultant. You turn a vague or large request into ONE decision-complete work plan a downstream worker executes with zero further interview. You read, search, run read-only analysis, and write only `.omo/plans/<slug>.md` and `.omo/drafts/*.md`. You never edit product code and never implement. **Plan mode is sticky**: "do X" / "fix X" / "just do it" mean "plan X"; execution belongs to the worker and starts only on the user's explicit start (e.g. `$ulw-execute`), never on your judgment.
 
 ## North star
-A plan is decision-complete when the implementer needs ZERO judgment calls: every decision made, every ambiguity resolved, every pattern referenced with a concrete path. The executor has NO interview context - be exhaustive.
+The ideal state for the affected user: the plan closes every gap between how that user experiences the result today and the state in which nothing snags, feels odd, regresses, or degrades for them. Decision-complete is how the plan gets there - every decision made, every ambiguity resolved, every pattern referenced with a concrete path; the executor has NO interview context, so be exhaustive.
 
 ## Phase 0 - Classify
 Size interview depth: **Trivial** (single file, obvious) - one or two confirms, then propose. **Standard** (1-5 files, clear feature/refactor) - full explore + interview/research + Metis. **Architecture** (system design, 5+ modules, long-term impact) - deep explore + external research + the dynamic adversarial lanes (see `intent-unclear.md`).
@@ -21,6 +21,9 @@ Size interview depth: **Trivial** (single file, obvious) - one or two confirms,
 ## Phase 1 - Ground (explore before asking)
 Eliminate unknowns by discovering facts, not by asking. Before your first question, fan out parallel read-only research and keep working while it runs. Two kinds of unknowns: **discoverable facts** (repo/system truth) become research-and-cite; **preferences/tradeoffs** (user intent, not derivable from code) are the only things the CLEAR path brings to the user, and the things the UNCLEAR path resolves to best-practice defaults. Retrieval budget: stop exploring a question once collected evidence answers it, or after two research waves add no new useful facts.
 
+### Define the ideal state (before any question or brief)
+From the request and the evidence, name who this output touches - a customer, another programmer, a program or agent consuming it, often more than one - and how each uses it today and will use it after. Write the ideal state as rows, one per property with its reason: what they do, what they see, what never breaks for them. Then write the gap rows: every difference between that state and today, each with its reason. Record both in the draft's `## Affected user and ideal state` ledger. Every later fork is first held against these rows, every todo closes a gap row, and `## Success criteria` proves the ideal-state rows one by one.
+
 ### Dynamic workflow for architecture and bootstrap planning
 When the request is architecture-scale, references Discord / external repos, or is invoked by `$ulw-execute` because no selectable plan exists, run **dynamic adversarial workflow phases** before synthesis. For broad requests, self-orchestrates 5 host subagents so the plan keeps maximum safe parallelism without losing evidence quality:
 1. **collect** lanes: repo implementation surface, tests/package surface, external or Discord claims, execution workflow, risk/QA.
@@ -125,7 +128,7 @@ This gate is the only thing between a finished brief and the plan file, and the
 
 When exploration is exhausted and the unknowns are answered:
 1. Write the gate into `.omo/drafts/<slug>.md`: `status: awaiting-approval`, the approach, and the next workflow action from `pending_action_policy`. Approval authorizes only plan creation; a required review runs afterward because it was already requested or automatically required. This durable record is the loop guard - after compaction, resume here instead of re-exploring.
-2. Present the brief once: what you found (key facts with paths), each remaining ambiguity with your recommended option (CLEAR) or each adopted default (UNCLEAR), and the approach you intend to plan.
+2. Present the brief once, leading with the affected user, the ideal-state rows, and the gap rows; then what you found (key facts with paths), each fork as resolved against the ideal state, each remaining owner-decision with your recommended option (CLEAR) or each adopted default (UNCLEAR), and the approach you intend to plan.
 
 Then read the user's next reply as a decision:
 - **Approval** - any reply after the brief that accepts the approach: "yes", "approve", "proceed", "write the plan", or answering the open ambiguities. The user's original request to "make/write a plan" starts planning; it is not this gate's approval. Approval authorizes exactly one thing: writing the plan file. It is **never authorization to implement** - you stay a planner.
@@ -136,10 +139,10 @@ No Metis, no plan file, no execution until the user approves. The UNCLEAR path a
 
 ## Phase 3 - Generate the plan (only after approval)
 1. Rerun `node "<skill-root>/scripts/scaffold-plan.mjs" <slug> [--clear|--unclear]` without `--draft-only`. The existing draft is preserved and the plan skeleton is created now, after approval. A plain rerun is a safe no-op; never hand-build the skeleton.
-2. **Metis gap analysis (mandatory):** spawn a metis reviewer for contradictions, missing constraints — including unstated extrinsic ones: budget/spend, mandated stack, expected scale, target audience / compliance — scope-creep, unvalidated assumptions, and missing acceptance criteria; fold findings in silently; require each constraint gap to return as a proposed default plus reversibility, or a single owner-question when defaulting is unsafe.
+2. **Metis gap analysis (mandatory):** spawn a metis reviewer for contradictions, affected users the ideal state forgot, gap rows no todo closes, missing constraints — including unstated extrinsic ones: budget/spend, mandated stack, expected scale, target audience / compliance — scope-creep, unvalidated assumptions, and missing acceptance criteria; fold findings in silently; require each constraint gap to return as a proposed default plus reversibility, or a single owner-question when defaulting is unsafe.
 3. APPEND todo batches into the `## Todos` region with edit/apply_patch - never rewrite the script-emitted headers; 50+ todos is fine; one request -> one plan.
 4. Fill `## TL;DR (For humans)` LAST, after the detailed plan, so it summarizes the real plan, not an intention.
-5. Self-review: every todo has references + agent-executable acceptance criteria + happy+failure QA scenarios; no business-logic assumption without evidence; zero criteria need a human. HR6 backstop - confirm the plan's FIRST `## ` heading is `## TL;DR (For humans)` and that every header below it appears in the template order; if you ever hand-built or reordered the file, the human summary must still lead.
+5. Self-review: every gap row is closed by at least one todo and every ideal-state row is proven by at least one QA scenario in `## Success criteria`; every todo has references + agent-executable acceptance criteria + happy+failure QA scenarios; no business-logic assumption without evidence; zero criteria need a human. HR6 backstop - confirm the plan's FIRST `## ` heading is `## TL;DR (For humans)` and that every header below it appears in the template order; if you ever hand-built or reordered the file, the human summary must still lead.
 
 ### Plan template (these are the headers the script emits - keep them verbatim)
 ```
@@ -154,14 +157,14 @@ No Metis, no plan file, no execution until the user approves. The UNCLEAR path a
 ## Commit strategy
 ## Success criteria
 ```
-> Target 5-8 todos per wave; fewer than 3 (except the final) means under-splitting. Implementation + Test = ONE todo. Each todo carries: exhaustive References (the executor has no interview context), agent-executable Acceptance criteria, happy + failure QA scenarios each with an evidence path, a Commit line, and a `Recommended task executor category:` line - the routing verdict the executor follows, with a one-line reason, in the omo category vocabulary: `quick` (mechanical / single-file - the default for every splittable piece), `unspecified-low` (small misc), `unspecified-high` (standard multi-file feature), `visual-engineering` (frontend/UI), `writing` (docs), `git` (git ops), `deep-low` (hairy debugging or cross-module reasoning the worker can settle from what it reads), `deep-high` (the same, when the central decision cannot be settled from evidence: a trade-off, a cross-package contract, or correctness argued from invariants), `ultrabrain` (ONE genuinely hard cohesive problem, delegated whole). Prefer many small `quick`-routable todos spread across parallel waves; when splitting would sever shared reasoning, keep ONE todo routed to `deep`/`ultrabrain` - never force-split work whose parts share one insight. Harnesses without categories map by difficulty: quick/unspecified-low/writing/git = low, unspecified-high/visual-engineering = medium, deep/ultrabrain = high.
+> `## Scope` opens with `### Affected user and ideal state` - the user, how they use the result, then the IS-n and GAP-n rows from the draft ledger - before Must have / Must NOT have; `## Success criteria` is the table mapping every IS row to its delivering todo(s), proving QA scenario, and evidence path. Target 5-8 todos per wave; fewer than 3 (except the final) means under-splitting. Implementation + Test = ONE todo. Each todo carries: exhaustive References (the executor has no interview context), agent-executable Acceptance criteria, happy + failure QA scenarios each with an evidence path, a Commit line, and a `Recommended task executor category:` line - the routing verdict the executor follows, with a one-line reason, in the omo category vocabulary: `quick` (mechanical / single-file - the default for every splittable piece), `unspecified-low` (small misc), `unspecified-high` (standard multi-file feature), `visual-engineering` (frontend/UI), `writing` (docs), `git` (git ops), `deep-low` (hairy debugging or cross-module reasoning the worker can settle from what it reads), `deep-high` (the same, when the central decision cannot be settled from evidence: a trade-off, a cross-package contract, or correctness argued from invariants), `ultrabrain` (ONE genuinely hard cohesive problem, delegated whole). Prefer many small `quick`-routable todos spread across parallel waves; when splitting would sever shared reasoning, keep ONE todo routed to `deep`/`ultrabrain` - never force-split work whose parts share one insight. Harnesses without categories map by difficulty: quick/unspecified-low/writing/git = low, unspecified-high/visual-engineering = medium, deep/ultrabrain = high.
 
 ## Plan artifact producer contract
 
 When producing the plan, encode every executable item as a column-zero Markdown task row: implementation rows MUST match `- [ ] N. <title>` (where `N` is a positive decimal integer), and final-verifier rows MUST match `- [ ] F<number>. <title>`. Prose headings, numbered paragraphs, and ordinary bullets are not task substitutes and MUST NOT be counted as implementation or final-verifier tasks. Before handoff, run a structural self-check over the plan: verify that every implementation row and final-verifier row is column-zero, matches its required grammar, and appears in the intended `## Todos` or `## Final verification wave` section; verify that no prose heading or bullet is being used as a task; verify that every implementation row carries a nested `Recommended task executor category:` line (final-verifier rows default to `unspecified-high` when unannotated); and repair the plan before handoff if any check fails.
 
 ### Final verification wave (after ALL todos)
-Runs in parallel; ALL must APPROVE; surface results and wait for the user's explicit okay before declaring complete: F1 plan compliance audit, F2 code quality review, F3 real manual QA, F4 scope fidelity.
+Runs in parallel; ALL must APPROVE; surface results and wait for the user's explicit okay before declaring complete: F1 plan compliance audit, F2 code quality review, F3 real manual QA, F4 ideal-state fidelity - the delivered behavior against every IS row, 1:1; a shortfall becomes new `- [ ] N.` rows, never a note.
 
 ## Phase 4 - Deliver
 - CLEAR with `review_required: false`: present the plan summary, then ask ONE question and stop - start work now, or run a high-accuracy review first? Never pick for the user; never begin execution yourself - execution belongs to the worker.
@@ -173,7 +176,7 @@ Runs in parallel; ALL must APPROVE; surface results and wait for the user's expl
 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.
+2. **Affected user and ideal state** - who the result touches and, from the plan's IS rows, what will exist or behave differently for them 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), plus the executor-category mix (e.g. 6x `quick`, 2x `unspecified-high`, 1x `ultrabrain`).
 4. **Added beyond the request** - what exploration surfaced and you folded in that the user never explicitly asked for (edge cases, migrations, tests, rollback, docs), each with a one-line reason; say "none" if nothing was added.
 5. **Verification** - how completion will be proven: the final verification wave plus the key QA scenarios/commands.
@@ -210,7 +213,7 @@ Every reviewer prompt must carry this intake contract with all angle-bracket val
 The first action must open the literal workspace root as a directory descriptor, then traverse `.omo`, `plans`, and the final target with descriptor-relative no-follow opens, `fstat` each ancestor as a directory and the final descriptor as a regular file, and hash all bytes read from that same final descriptor. If the platform cannot guarantee this chain, or any path/runtime/launch/receipt/digest check drifts, return `INCONCLUSIVE` before reviewing. Echo the literal workspace, runtime home, target, digest, round, and launch ID; the parent separately matches the completion envelope to the persisted session/process receipt. Never search or use another artifact.
 
 ### Bounded convergence (the review must terminate)
-Review rounds are capped at 5 (unlimited only on explicit user request), and an approval whose only remaining items are notes counts as approval. A finding may BLOCK only when it names at least one `blocker_eligibility` category below with its concrete evidence; every other finding - speculative durability, replay/crash-recovery, schema, CLI-parsing, state-machine, or hardening concerns the accepted scope never required - is recorded as a non-blocking note and becomes implementation/test work, never plan expansion. After round 1 the blocker ledger FREEZES: later rounds verify accepted ledger blockers, regressions introduced by fixes, and new findings that pass eligibility - they never rediscover the plan from scratch. Fixes apply the smallest edit that resolves the cited blocker; neither reviews nor fixes grow the plan's scope. Every reviewer prompt carries this convergence contract alongside the intake contract. On cap exhaustion without approval: STOP, report outstanding blockers, ask the user - continue / accept / adjust.
+Review rounds are capped at 5 (unlimited only on explicit user request), and an approval whose only remaining items are notes counts as approval. A finding may BLOCK only when it names at least one `blocker_eligibility` category below with its concrete evidence - an IS row no todo closes, no QA scenario proves, or the approach cannot reach for the named user is such a category; every other finding - speculative durability, replay/crash-recovery, schema, CLI-parsing, state-machine, or hardening concerns the accepted scope never required - is recorded as a non-blocking note and becomes implementation/test work, never plan expansion. After round 1 the blocker ledger FREEZES: later rounds verify accepted ledger blockers, regressions introduced by fixes, and new findings that pass eligibility - they never rediscover the plan from scratch. Fixes apply the smallest edit that resolves the cited blocker; neither reviews nor fixes grow the plan's scope. Every reviewer prompt carries this convergence contract alongside the intake contract. On cap exhaustion without approval: STOP, report outstanding blockers, ask the user - continue / accept / adjust.
 
 <!-- ulw-plan-review-convergence-contract -->
 ```json
@@ -223,7 +226,8 @@ Review rounds are capped at 5 (unlimited only on explicit user request), and an
     "existing_failing_regression",
     "reproducible_broken_flow",
     "concrete_security_data_loss_or_compatibility_risk",
-    "external_api_provider_or_release_contract_conflict"
+    "external_api_provider_or_release_contract_conflict",
+    "ideal_state_row_unmapped_or_unreachable_for_the_affected_user"
   ],
   "ineligible_finding_disposition": "non_blocking_note",
   "approval_with_notes_counts_as_approval": true,

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

@@ -20,13 +20,13 @@ Explore-before-asking. Dispatch parallel read-only research in one turn - intern
 <interview>
 TOPOLOGY LOCK first: from the request plus exploration, enumerate the 1-6 top-level components that can each succeed or fail independently, confirm them in ONE turn, and record them in the draft's Components ledger (id, one-line outcome, status, evidence path). Do NOT collapse to one component because the request looks small.
 
-Then the TWO FILTERS (full definition in SKILL.md): (1) evidence-answerable -> explore; (2) intent plus a defensible default -> adopt and record, EXCEPT owner-decisions (irreversible / destructive / safety-critical, or cross-cutting product choices), which always survive as questions.
+Then the TWO FILTERS (full definition in SKILL.md): (1) evidence-answerable -> explore; (2) the ideal state for the affected user - or, failing that, intent plus a defensible default - settles it -> resolve and record, EXCEPT owner-decisions (irreversible / destructive / safety-critical, or cross-cutting product choices), which always survive as questions.
 
 ASK WITH WHY: name what you explored, why it did not resolve, and which part of the plan forks on the answer. 1-3 narrow questions per turn, each with 2-4 options and your recommended default FIRST; a skipped question resolves to that default. Always confirm test strategy (TDD / tests-after / none - agent-executed QA is always included).
 
 FOGGIEST-GAP targeting (ordinal, NO numbers): each turn aim at the single open gap whose resolution most unblocks the plan, and say why in one sentence; rotate across equally-foggy components. End every turn with the question or the explicit next step - never passive.
 
-CLEARANCE CHECK after each turn: objective defined? scope IN/OUT explicit? approach decided? test strategy confirmed? constraints swept (budget / stack / scale / audience - each explored, defaulted, or asked)? no blocking ambiguity left? Any NO is your next question; all YES -> present the approval brief and stop.
+CLEARANCE CHECK after each turn: affected user named, ideal-state and gap rows recorded? objective defined? scope IN/OUT explicit? approach decided? test strategy confirmed? constraints swept (budget / stack / scale / audience - each explored, defaulted, or asked)? no blocking ambiguity left? Any NO is your next question; all YES -> present the approval brief and stop.
 </interview>
 
 <approval_and_deliver>
@@ -36,10 +36,9 @@ Run the durable approval gate (mechanics in `full-workflow.md`): present the bri
 <worked_example>
 Request: "add a 5/min-per-IP rate-limit to `/login`".
 1. Explore -> auth middleware at `src/auth/login.ts:40`, an existing limiter util at `src/util/rate-limit.ts`, Redis client at `src/redis.ts`.
-2. Topology lock (one turn): one active component - "login rate-limit".
-3. Two surviving forks, each asked WITH WHY:
-   - Storage backend (explored: repo already uses Redis; default = Redis; options Redis / in-memory / per-node) - why: persistence across nodes forks the design.
-   - Over-limit response (default = 429 + Retry-After; options 429 / 423 / silent drop) - why: client contract forks on it.
+2. Affected user and ideal state: a person signing in through a balancer that spreads them over several nodes; IS rows - one count per IP across nodes, an over-limit reply that says when to retry, a legitimate user never sees a reset or a silent drop. Topology lock (one turn): one active component - "login rate-limit".
+3. One fork the ideal state settles, recorded not asked: storage backend = Redis (one count across nodes; in-memory would reset per node). One surviving owner-decision, asked WITH WHY:
+   - Over-limit response (default = 429 + Retry-After; options 429 / 423 / silent drop) - why: a client contract the user lives with.
    - Swept axes: no budget/audience fork (internal service); scale bound = existing Redis capacity (defaulted, reversible).
 4. Approval brief -> explicit okay -> scaffold -> append todos -> if `review_required`, run dual review and deliver receipts; otherwise deliver with the optional review question.
 </worked_example>

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

@@ -20,7 +20,7 @@ TOPOLOGY LOCK still applies: enumerate the 1-6 independently-succeed/fail compon
 </research_protocol>
 
 <default_selection>
-For each open decision - including the extrinsic axes the sweep names (budget, mandated stack, expected scale, target audience / compliance) - adopt the defensible best-practice default (industry standard or repo convention), RECORD it in the draft's Open-assumptions ledger with rationale and reversibility, and proceed. NO numeric scoring - the ledger IS the audit trail. The ONLY default escalated to a single focused question is one that is irreversible, destructive, or safety-critical, or commits real spend the user never authorized, and research cannot settle.
+For each open decision - including the extrinsic axes the sweep names (budget, mandated stack, expected scale, target audience / compliance) - adopt the default the ideal state for the affected user demands (industry standard and repo convention are evidence for it, never the default itself), RECORD it in the draft's Open-assumptions ledger with rationale and reversibility, and proceed. NO numeric scoring - the ledger IS the audit trail. The ONLY default escalated to a single focused question is one that is irreversible, destructive, or safety-critical, or commits real spend the user never authorized, and research cannot settle.
 
 Fold a contrarian self-grill into the Metis spawn: challenge the single highest-leverage adopted assumption - is this constraint real or habitual; does any adopted default add complexity the request never asked for? - and return concrete reframes. The grill targets incidental complexity (unneeded abstraction, speculative capacity), NEVER the feature set: reducing, phasing, or deferring part of the request is not a reframe. Fold a reframe into the plan only as a recommended default plus rationale, never as a forced change.
 </default_selection>
@@ -38,7 +38,7 @@ Still present a brief and wait for the user's explicit okay - approval is not ex
 <worked_example>
 Request: "make auth better".
 1. Research waves -> current auth at `src/auth/*` and evidence for the requested improvement; best-practice baselines via librarian.
-2. Topology lock as an ANNOUNCEMENT, not a question: components refine the evidenced auth intent in full, such as session hardening, brute-force protection, and password policy when the repository supports them. MFA is an adjacent capability and stays in Scope OUT unless the user asks for it or evidence establishes it as part of the requested outcome.
+2. Affected user and ideal state, announced: the people who sign in and the operators who read auth logs; IS rows the evidence supports - a legitimate user is never locked out, brute force is stopped, a session is never reusable after a privilege change. Topology lock as an ANNOUNCEMENT, not a question: components refine the evidenced auth intent in full, such as session hardening, brute-force protection, and password policy when the repository supports them. MFA is an adjacent capability and stays in Scope OUT unless the user asks for it or evidence establishes it as part of the requested outcome.
 3. Adopted-defaults table (assumption | default | rationale | reversible?): bcrypt rounds 8 -> 12 (reversible), add 5/min-per-IP login limit (reversible), rotate session id on privilege change (reversible).
 4. Metis folded -> auto dual review (fix eligible gaps under the bounded convergence contract) -> brief LEADING with the approach and the defaults, surfaced in the human TL;DR for veto.
 </worked_example>

package/packages/omo-codex/plugin/components/ultrawork/skills/ulw-plan/scripts/plan-templates.mjs

@@ -0,0 +1,180 @@
+// plan-templates.mjs - the draft and plan skeleton text that scaffold-plan.mjs emits.
+//
+// Text only: no filesystem access, no path policy (scaffold-plan.mjs owns the write
+// boundary). Zero external dependencies so it runs byte-identically under `node` and `bun`.
+
+// The canonical AI-plan section headers, in order. references/full-workflow.md
+// documents this exact list; the two must never drift.
+export const PLAN_SECTION_HEADERS = [
+	"## TL;DR (For humans)",
+	"## Scope",
+	"## Verification strategy",
+	"## Execution strategy",
+	"## Todos",
+	"## Final verification wave",
+	"## Commit strategy",
+	"## Success criteria",
+];
+
+export const FINAL_VERIFICATION_ITEMS = [
+	"F1. Plan compliance audit",
+	"F2. Code quality review",
+	"F3. Real manual QA",
+	"F4. Ideal-state fidelity",
+];
+
+export function buildDraft(slug, intent, { reviewRequired = false } = {}) {
+	const assumptionsNote =
+		intent === "unclear"
+			? "Intent is UNCLEAR: research resolves ambiguity, defaults are adopted (not asked), and each is surfaced in the plan's human TL;DR for veto."
+			: "Record any default you adopt instead of asking, so the user can veto it at the gate.";
+	const reviewState = reviewRequired
+		? `review_required: true
+plan_path: .omo/plans/${slug}.md
+plan_sha256: null
+review_round_id: null
+pending-action: write and review .omo/plans/${slug}.md
+review:
+  momus:
+    status: pending
+    workspace_root: null
+    runtime_home: null
+    target: .omo/plans/${slug}.md
+    round_id: null
+    plan_sha256: null
+    launch_id: null
+    session: null
+    result: null
+  independent:
+    status: pending
+    workspace_root: null
+    runtime_home: null
+    target: .omo/plans/${slug}.md
+    round_id: null
+    plan_sha256: null
+    launch_id: null
+    session: null
+    result: null`
+		: `review_required: false
+pending-action: write .omo/plans/${slug}.md`;
+	return `---
+slug: ${slug}
+status: drafting
+intent: ${intent}
+${reviewState}
+approach: <fill: the approach you intend to plan>
+---
+
+# Draft: ${slug}
+
+## Affected user and ideal state
+<!-- Who this output touches (a customer, another programmer, a program or agent consuming it - often more than one) and how each uses it today and will use it after. -->
+<!-- IS-n | property of the ideal state: nothing snags, feels odd, regresses, or degrades for them | reason -->
+<!-- GAP-n | difference between IS-n and today | reason | closed by todo(s) -->
+
+## Components (topology ledger)
+<!-- Lock the SHAPE before depth. One row per top-level component that can succeed or fail independently. -->
+<!-- id | outcome (one line) | status: active|deferred | evidence path -->
+
+## Open assumptions (announced defaults)
+<!-- ${assumptionsNote} -->
+<!-- assumption | adopted default | rationale | reversible? -->
+
+## Findings (cited - path:lines)
+
+## Decisions (with rationale)
+
+## Scope IN
+
+## Scope OUT (Must NOT have)
+
+## Open questions
+
+## Approval gate
+status: drafting
+<!-- When exploration is exhausted and unknowns are answered, set status: awaiting-approval. -->
+<!-- That durable record is the loop guard: on a later turn read it and resume at the gate instead of re-running exploration. -->
+`;
+}
+
+export function buildPlanSkeleton(slug, intent) {
+	const decisionsLine =
+		intent === "unclear"
+			? "**Decisions I made for you:** <fill last - the best-practice defaults you adopted; the user vetoes any here>"
+			: "**Decisions to sanity-check:** <fill last - the few choices worth a human glance>";
+	return `# ${slug} - Work Plan
+
+## TL;DR (For humans)
+<!-- Fill this LAST, after the detailed plan below is written, so it summarizes the REAL plan. -->
+<!-- Plain English for a non-engineer: NO file paths, NO todo numbers, NO wave/agent/tool names. -->
+
+**Who this is for and what changes for them:** <fill last - the affected user and their experience after, 1-2 sentences>
+
+**What you'll get:** <fill last - deliverables in human terms, 1-2 sentences>
+
+**Why this approach:** <fill last - the one or two load-bearing decisions and why>
+
+**What it will NOT do:** <fill last - 1-3 plain lines mirroring Must NOT have>
+
+**Effort:** <Quick | Short | Medium | Large | XL>
+<!-- Effort is exactly ONE band, never hours/days. Quick = single edit, minutes of agent work; Short = one focused change, a few files; Medium = multi-file feature in one session; Large = several waves, one long session; XL = multi-session or architectural work. A written duration is rewritten to a band. -->
+**Risk:** <Low | Medium | High> - <one-line driver>
+${decisionsLine}
+
+Your next move: <fill - e.g. approve, or run a high-accuracy review>. Full execution detail follows below.
+
+---
+
+> TL;DR (machine): <1 line - effort, risk, deliverables>
+
+## Scope
+### Affected user and ideal state
+<!-- From the draft ledger: who this touches and how they use the result, then one IS row per property with its reason, then one GAP row per difference with its reason. Every todo below closes a GAP row; ## Success criteria proves every IS row. -->
+**Affected user:** <who, and how they use it today and after>
+
+| Row | Statement | Reason |
+| --- | --- | --- |
+| IS-1 | <what the user does, sees, or never has break> | <why this is the ideal for them> |
+| GAP-1 | <how today differs from IS-1> | <why it matters to them> |
+
+### Must have
+### Must NOT have (guardrails, anti-slop, scope boundaries)
+
+## Verification strategy
+> Zero human intervention - all verification is agent-executed.
+- Test decision: <TDD | tests-after | none> + framework
+- Evidence: <attemptDir>/task-<N>-${slug}.<ext> (attemptDir = currentAttemptDir from 'omo-agent-toolkit ulw-loop status --json', .omo/evidence/ulw/<session>/<goalId>/a<attempt>; outside ulw-loop use .omo/evidence/)
+
+## Execution strategy
+### Parallel execution waves
+> Target 5-8 todos per wave. Fewer than 3 (except the final) means you under-split.
+
+### Dependency matrix
+| Todo | Depends on | Blocks | Can parallelize with |
+| --- | --- | --- | --- |
+
+## Todos
+> Implementation + Test = ONE todo. Never separate.
+<!-- APPEND TASK BATCHES BELOW THIS LINE WITH edit/apply_patch - never rewrite the headers above. -->
+- [ ] 1. <title>
+  What to do / Must NOT do: <...>
+  Closes: GAP-<n>
+  Parallelization: Wave <N> | Blocked by: <...> | Blocks: <...>
+  References (executor has NO interview context - be exhaustive): <src/path:lines>
+  Acceptance criteria (agent-executable): <exact command or assertion>
+  QA scenarios (name the exact tool + invocation): happy + failure, Evidence <attemptDir>/task-1-${slug}.<ext>
+  Commit: <Y/N> | <type>(<scope>): <summary>
+
+## Final verification wave
+> Runs in parallel after ALL todos. ALL must APPROVE. Surface results and wait for the user's explicit okay before declaring complete.
+${FINAL_VERIFICATION_ITEMS.map((item) => `- [ ] ${item}`).join("\n")}
+
+## Commit strategy
+
+## Success criteria
+> One row per IS row. The plan is complete only when every IS row has a delivering todo and a proving QA scenario; F4 checks the delivered behavior against these rows 1:1, and a shortfall becomes new \`- [ ] N.\` rows, never a note.
+| IS | Delivering todo(s) | Proving QA scenario | Evidence |
+| --- | --- | --- | --- |
+| IS-1 | <N> | <scenario name from todo N> | <attemptDir>/task-<N>-${slug}.<ext> |
+`;
+}