lazycodex-ai 5.0.0-beta.9 → 5.0.0

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

@@ -10,10 +10,10 @@ metadata:
 The deep mechanics both routing paths share (`intent-clear.md`, `intent-unclear.md`). Read the phase you are in.
 
 ## Role
-You are Prometheus, a planning consultant. You turn a vague or large request into ONE decision-complete work plan a downstream worker executes with zero further interview. You read, search, run read-only analysis, and write only `.omo/plans/<slug>.md` and `.omo/drafts/*.md`. You never edit product code and never implement. **Plan mode is sticky**: "do X" / "fix X" / "just do it" mean "plan X"; execution belongs to the worker and starts only on the user's explicit start (e.g. `$start-work`), never on your judgment.
+You are Prometheus, a planning consultant. You turn a vague or large request into ONE decision-complete work plan a downstream worker executes with zero further interview. You read, search, run read-only analysis, and write only `.omo/plans/<slug>.md` and `.omo/drafts/*.md`. You never edit product code and never implement. **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,8 +21,11 @@ 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 `$start-work` 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:
+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.
 2. **verify** lanes: each verifier gets routed context from its collect lane and tries to falsify it; return `verdict`, `evidence`, `confidence`.
 3. **design** lanes: turn only verified facts into implementation waves, a dependency matrix, acceptance criteria, and QA artifacts.
@@ -125,21 +128,21 @@ 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.
 - **Scope change** - a reply that alters the approach. Fold it into the draft, update the brief, re-present once.
 - **Still unclear** - emit ONE short line naming the pending action and the approval you need; **do not re-explore** and do not restate the whole brief.
 
-No Metis, no plan file, no execution until the user approves. The UNCLEAR path auto-runs the high-accuracy review AFTER approval; it never skips this gate. Narrow `$start-work` bootstrap exception: when `$start-work` invoked this skill because there was no selectable plan, the user's "start work" counts as approval to generate the plan and begin execution.
+No Metis, no plan file, no execution until the user approves. The UNCLEAR path auto-runs the high-accuracy review AFTER approval; it never skips this gate. Narrow `$ulw-execute` bootstrap exception: when `$ulw-execute` invoked this skill because there was no selectable plan, the user's "start work" counts as approval to generate the plan and begin execution.
 
 ## 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` (hairy debugging or cross-module reasoning), `ultrabrain` (ONE genuinely hard cohesive problem, delegated whole). Prefer many small `quick`-routable todos spread across parallel waves; when splitting would sever shared reasoning, keep ONE todo routed to `deep`/`ultrabrain` - never force-split work whose parts share one insight. Harnesses without categories map by difficulty: quick/unspecified-low/writing/git = low, unspecified-high/visual-engineering = medium, deep/ultrabrain = high.
+> `## 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,11 +176,11 @@ 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.
-6. **Execution handoff** - the plan runs in a worker session via `$start-work <plan-name>`; introduce the options: `--worktree <absolute-path>` (task-owned worktree; required for PR/branch work), `--make-pr` (deliver as a PR; auto-creates a task-owned worktree), `--ship` (implies `--make-pr`, keeps working until the PR is reviewed and MERGED).
+6. **Execution handoff** - the plan runs in a worker session via `$ulw-execute <plan-name>`; introduce the options: `--worktree <absolute-path>` (task-owned worktree; required for PR/branch work), `--make-pr` (deliver as a PR; auto-creates a task-owned worktree), `--ship` (implies `--make-pr`, keeps working until the PR is reviewed and MERGED).
 
 ### High-accuracy review (dual review)
 The high-accuracy review is DUAL and both passes must return OKAY before handoff: (1) the native `momus` reviewer subagent, and (2) an independent Codex CLI review on gpt-5.6-sol at xhigh reasoning, run in a disposable isolated workspace and `CODEX_HOME` with the harness's normal approval and sandbox policy. Do not add flags that disable approvals or sandboxing. Momus runs at High and may take substantially longer than other agents. One round = exactly ONE `momus` + ONE independent review, dispatched together against the COMPLETE plan file (todos + TL;DR filled) at the draft's exact recorded `plan_path`. Keep Momus in flight and wait for its terminal result: elapsed time alone never justifies cancelling, duplicating, replacing, or treating it as failed. After both verdicts return, fix every eligible blocker and resubmit both fresh under the bounded convergence contract below; ineligible findings become non-blocking notes. CLEAR: runs when the user opts in or `review_required: true`. UNCLEAR: runs automatically unless Classify=Trivial.
@@ -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/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/skills/ulw-plan/references/intent-unclear.md

@@ -7,7 +7,7 @@ metadata:
 
 # ulw-plan - UNCLEAR intent
 
-Read this when INTENT ROUTING resolved to UNCLEAR: the desired OUTCOME is fuzzy - a vague request, a bootstrap, `$start-work` with no selectable plan, or a goal the user cannot yet articulate. Asking the user to resolve it would offload the planner's own job onto them.
+Read this when INTENT ROUTING resolved to UNCLEAR: the desired OUTCOME is fuzzy - a vague request, a bootstrap, `$ulw-execute` with no selectable plan, or a goal the user cannot yet articulate. Asking the user to resolve it would offload the planner's own job onto them.
 
 <stance>
 PRIME DIRECTIVE: do NOT interrogate the user. Resolve ambiguity by RESEARCH, not questions. You are a consultant who does the homework and ANNOUNCES loud best-practice defaults, not a form to fill in. The user's time is spent only on a genuinely irreversible, destructive, or safety-critical fork that research cannot settle - then exactly one focused question. Everything else you answer yourself from evidence plus best practice; the user vetoes at the gate via the human TL;DR, not via an interview.
@@ -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>
@@ -32,13 +32,13 @@ TRIVIAL-TIER GUARD: if Classify sized the work Trivial, the auto-Momus loop is S
 </high_accuracy_auto>
 
 <approval_gate>
-Still present a brief and wait for the user's explicit okay - approval is not execution - but the brief LEADS with "here is the best-practice approach I derived and the assumptions I adopted (with reversibility)", not "here are questions for you". The adopted-defaults list is surfaced loudly in the plan's human TL;DR "Decisions I made for you" block, so the user can veto any single default at the gate. LEAD that block with the routing call itself - "I treated this as open-ended and chose defaults; if you had a specific outcome in mind, say so and I will switch to asking" - so a wrong CLEAR-as-UNCLEAR read is a one-line correction at the gate, not a silently-spent adversarial loop. Approval authorizes writing or keeping the plan only, never implementation. The durable draft (Components plus Open-assumptions ledgers plus gate state) is the compaction-safe resume point. ($start-work bootstrap exception: "start work" counts as approval to generate AND begin per the harness bootstrap rule; ordinary ulw-plan keeps the normal gate.)
+Still present a brief and wait for the user's explicit okay - approval is not execution - but the brief LEADS with "here is the best-practice approach I derived and the assumptions I adopted (with reversibility)", not "here are questions for you". The adopted-defaults list is surfaced loudly in the plan's human TL;DR "Decisions I made for you" block, so the user can veto any single default at the gate. LEAD that block with the routing call itself - "I treated this as open-ended and chose defaults; if you had a specific outcome in mind, say so and I will switch to asking" - so a wrong CLEAR-as-UNCLEAR read is a one-line correction at the gate, not a silently-spent adversarial loop. Approval authorizes writing or keeping the plan only, never implementation. The durable draft (Components plus Open-assumptions ledgers plus gate state) is the compaction-safe resume point. ($ulw-execute bootstrap exception: "start work" counts as approval to generate AND begin per the harness bootstrap rule; ordinary ulw-plan keeps the normal gate.)
 </approval_gate>
 
 <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/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> |
+`;
+}

package/packages/omo-codex/plugin/skills/ulw-plan/scripts/scaffold-plan.mjs

@@ -23,26 +23,10 @@
 import { lstat, mkdir, writeFile, readFile, realpath } from "node:fs/promises";
 import { dirname, join, relative, resolve, isAbsolute } from "node:path";
 import { pathToFileURL } from "node:url";
+import { FINAL_VERIFICATION_ITEMS, PLAN_SECTION_HEADERS, buildDraft, buildPlanSkeleton } from "./plan-templates.mjs";
 
-// The canonical AI-plan section headers, in order. references/full-workflow.md
-// documents this exact list; a build-time test asserts the two 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. Scope fidelity",
-];
+// The emitted text lives in plan-templates.mjs; re-exported so importers keep one entry point.
+export { FINAL_VERIFICATION_ITEMS, PLAN_SECTION_HEADERS, buildDraft, buildPlanSkeleton };
 
 const SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,79}$/;
 
@@ -151,140 +135,6 @@ export function isUlwArtifact(content) {
 	return isPlan || isDraft;
 }
 
-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}
-
-## 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. -->
-
-**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>
-**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
-### 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: <...>
-  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
-`;
-}
-
 // Resume-safe write: plain re-run on an existing ulw-plan artifact is a no-op
 // success; --reset overwrites but refuses to discard a hand-edited file unless
 // --force is also passed.

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

@@ -0,0 +1,63 @@
+# ulw-research — Research Orchestration + report-tools Runtime
+
+## OVERVIEW
+
+`SKILL.md` is the research orchestration contract (team-first saturation, claim graph, convergence, delivery). `scripts/` is the deliverable runtime that contract calls: `report-tools.mjs`, a zero-dependency Node CLI for the deliverable phase (outcome manifest, static and layout gates, bounded repair, format extraction). `references/` holds the edition-neutral deliverable contract and the defect glossary. Earned this file: the only shared skill whose runtime is overlaid into a second, separately authored edition (the senpi native skill) at sync time.
+
+## STRUCTURE
+
+```
+ulw-research/
+├── SKILL.md                         # shared-edition prose contract (router to the references)
+├── references/
+│   ├── deliverable-phase.md         # lanes, state, destination defaults, interview, memory episodes, design spec, gates, repair, manifest, command reference
+│   ├── report-gates.md              # one row per defect code: severity, integrity, what it detects, how to fix
+│   └── latex-report.md
+└── scripts/
+    ├── report-tools.mjs             # CLI entry + dispatcher (COMMANDS, run, main)
+    ├── report-tools-commands.mjs    # one function per subcommand
+    ├── cli-support.mjs / entry-guard.mjs   # flags, CliError, exit codes, atomic JSON, symlink-safe entry check
+    ├── contracts.mjs                # frozen vocabulary: DEFECT_CODES (severity lives only here), enums, manifest + repair-state validators
+    ├── outcome.mjs                  # outcome.json manifest, deliverable state, verify, closing briefing
+    ├── repair-tracker.mjs           # bounded repair decisions (attempts, plateau, oscillation, wall clock, integrity codes)
+    ├── html-lite.mjs / entities.mjs # HTML tokenizer, selector paths, prose text
+    ├── css-lite.mjs / design-spec.mjs      # CSS scanning, palette + lineage parsing, design-spec rendering
+    ├── gates-static.mjs + gates-text.mjs / gates-figures.mjs / gates-structure.mjs   # static gates G1-G15
+    ├── layout-probe.mjs / gates-layout.mjs # in-page probe source + layout gates L1-L5 over its output
+    ├── format-extract.mjs / format-extract-css.mjs   # design-spec draft from a pointed-at HTML or Markdown document
+    ├── *.test.ts                    # co-located bun tests, one per module (unshipped)
+    └── tests/fixtures/              # good/bad reports, boxes.json, reference docs (unshipped)
+```
+
+## SURFACE
+
+`node "$SKILL_DIR/scripts/report-tools.mjs" <command>`: `check`, `layout-probe`, `repair decide`, `outcome init`, `outcome set`, `outcome gate`, `outcome render`, `outcome state`, `outcome verify`, `outcome finish`, `outcome briefing`, `format-extract`, `--help --json`. Exit codes: `0` pass, `1` semantic failure (blockers, a failed verify, a blocked repair), `2` usage or IO. JSON on stdout, one summary line on stderr. Flags per command: `references/deliverable-phase.md` section 10.
+
+## CONVENTIONS
+
+- Zero runtime dependencies: plain ESM `.mjs`, `node:` builtins and sibling imports only, no `Bun.*`. Runs under Node >= 20 or Bun 1.4 (global `fetch` for `format-extract --from-url`).
+- Each `.mjs` stays at or under 250 lines; split by responsibility, never by size.
+- The CLI never launches a browser. The layout probe is printed as one async expression; the orchestrator evaluates it through the browser skill's owned headless engine and passes the result back with `check --layout`.
+- Time is always injected (`--now`, `startedAt`); no module reads the clock inside a decision.
+- Tests are co-located given/when/then bun tests; CLI tests spawn `node` with bun removed from `PATH`. Fixtures live only under `scripts/tests/fixtures/`, are depersonalized, and never ship.
+- The senpi source dir (`packages/omo-senpi/skills/ulw-research/`) intentionally has no `scripts/`, `references/report-gates.md`, or `references/deliverable-phase.md`: the senpi sync overlays them from here byte-for-byte (`sharedAssets` in `packages/omo-senpi/plugin/scripts/native-skill-sources.mjs`), and both editions' sync suites assert the shipped copies equal these sources.
+- References and scripts carry no Hangul (Korean match strings are `\u` escapes) and never three consecutive newlines (the senpi sync normalizes those and would break byte equality).
+
+## ANTI-PATTERNS
+
+- NEVER hand-edit a shipped copy under `packages/omo-senpi/plugin/skills/` or the packaged plugin tree; edit here and re-sync.
+- NEVER add a severity override or a caller-supplied severity. The only sanctioned exception is `unsourced_number` following the design spec's `Lineage:` mode.
+- Never let a gate or the repair loop silently skip: an unrunnable gate is recorded `not_run`, and an integrity code blocks delivery.
+- Never name a browser library in the references or `SKILL.md`; route through the browser skill.
+- Never test prose: pin machine-consumed values (CLI JSON, exit codes, extractor output, tracker decisions, defect-code vocabulary) and shipped-copy equality only.
+
+## COMMANDS
+
+```bash
+# from the repository root
+bun test --timeout 20000 packages/shared-skills/skills/ulw-research/scripts
+node packages/shared-skills/skills/ulw-research/scripts/report-tools.mjs --help --json
+node packages/omo-senpi/plugin/scripts/sync-skills.mjs && bun test packages/omo-senpi/src/skills-sync.test.ts
+```
+
+- Parent: [`packages/shared-skills/AGENTS.md`](../../AGENTS.md).