oh-my-opencode 4.18.2 → 4.19.1

package/dist/oh-my-opencode.schema.json

@@ -59,9 +59,7 @@
       "items": {
         "type": "string",
         "enum": [
-          "ralph-loop",
-          "ulw-loop",
-          "cancel-ralph",
+          "goal",
           "refactor",
           "start-work",
           "stop-continuation",
@@ -6131,38 +6129,38 @@
         }
       ]
     },
-    "ralph_loop": {
+    "goal": {
       "type": "object",
       "properties": {
         "enabled": {
           "default": false,
           "type": "boolean"
         },
+        "auto_start": {
+          "default": false,
+          "type": "boolean"
+        },
         "default_max_iterations": {
           "default": 100,
           "type": "number",
           "minimum": 1,
           "maximum": 1000
-        },
-        "state_dir": {
-          "type": "string"
-        },
-        "default_strategy": {
-          "default": "continue",
-          "type": "string",
-          "enum": [
-            "reset",
-            "continue"
-          ]
         }
       },
       "required": [
         "enabled",
-        "default_max_iterations",
-        "default_strategy"
+        "auto_start",
+        "default_max_iterations"
       ],
       "additionalProperties": false
     },
+    "ralph_loop": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {}
+    },
     "runtime_fallback": {
       "anyOf": [
         {
@@ -6558,10 +6556,20 @@
           "default": true,
           "type": "boolean"
         },
+        "daemon": {
+          "default": false,
+          "type": "boolean"
+        },
         "enabled": {
           "default": true,
           "type": "boolean"
         },
+        "excluded_roots": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
         "install_dir": {
           "type": "string"
         },
@@ -6576,6 +6584,7 @@
       "required": [
         "auto_init",
         "auto_provision",
+        "daemon",
         "enabled"
       ],
       "additionalProperties": false
@@ -6747,6 +6756,12 @@
             "dev-browser",
             "playwright-cli"
           ]
+        },
+        "playwright_mcp_args": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
         }
       },
       "required": [
@@ -6896,14 +6911,14 @@
           "default": false,
           "type": "boolean"
         },
-        "ralph_loop": {
+        "goal": {
           "default": false,
           "type": "boolean"
         }
       },
       "required": [
         "ultrawork",
-        "ralph_loop"
+        "goal"
       ],
       "additionalProperties": false
     },

package/dist/plugin/chat-message/loop-commands.d.ts

@@ -1,6 +1,6 @@
 import type { OhMyOpenCodeConfig } from "../../config";
 import type { ChatMessageHooks, ChatMessageHandlerOutput, ChatMessageInput } from "./types";
-export declare function handleRalphLoopMessage(args: {
+export declare function handleGoalMessage(args: {
     readonly hooks: ChatMessageHooks;
     readonly input: ChatMessageInput;
     readonly output: ChatMessageHandlerOutput;

package/dist/plugin/chat-message/types.d.ts

@@ -39,15 +39,28 @@ type StopContinuationGuard = {
     isStopped: (sessionID: string) => boolean;
     clear: (sessionID: string) => void;
 };
-type RalphLoopHook = {
-    startLoop: (sessionID: string, prompt: string, options?: {
-        readonly ultrawork?: boolean;
-        readonly maxIterations?: number;
-        readonly completionPromise?: string;
-        readonly strategy?: "continue" | "reset";
-    }) => boolean | void;
-    resumeLoop?: (sessionID: string) => boolean;
-    cancelLoop: (sessionID: string) => boolean | void;
+type GoalHook = {
+    setGoal: (sessionID: string, objective: string) => {
+        readonly objective: string;
+        readonly status: string;
+    } | null;
+    getGoal: (sessionID: string) => {
+        readonly objective: string;
+        readonly status: string;
+    } | null;
+    pauseGoal: (sessionID: string) => {
+        readonly objective: string;
+        readonly status: string;
+    } | null;
+    resumeGoal: (sessionID: string) => {
+        readonly objective: string;
+        readonly status: string;
+    } | null;
+    clearGoal: (sessionID: string) => boolean;
+    markComplete: (sessionID: string) => {
+        readonly objective: string;
+        readonly status: string;
+    } | null;
 };
 type TodoContinuationEnforcerHook = {
     cancelAllCountdowns: () => void;
@@ -65,7 +78,7 @@ export type ChatMessageHooks = {
     noHephaestusNonGpt?: ChatMessageHook | null;
     hephaestusAgentsMdInjector?: ChatMessageHook | null;
     startWork?: ChatMessageHook | null;
-    ralphLoop?: RalphLoopHook | null;
+    goal?: GoalHook | null;
     todoContinuationEnforcer?: TodoContinuationEnforcerHook | null;
 };
 export {};

package/dist/plugin/hooks/create-core-hooks.d.ts

@@ -50,7 +50,7 @@ export declare function createCoreHooks(args: {
     agentUsageReminder: ReturnType<typeof import("../../hooks").createAgentUsageReminderHook> | null;
     nonInteractiveEnv: ReturnType<typeof import("../../hooks").createNonInteractiveEnvHook> | null;
     interactiveBashSession: ReturnType<typeof import("../../hooks").createInteractiveBashSessionHook> | null;
-    ralphLoop: ReturnType<typeof import("../../hooks").createRalphLoopHook> | null;
+    goal: ReturnType<typeof import("../../hooks").createGoalHook> | null;
     editErrorRecovery: ReturnType<typeof import("../../hooks").createEditErrorRecoveryHook> | null;
     delegateTaskRetry: ReturnType<typeof import("../../hooks").createDelegateTaskRetryHook> | null;
     startWork: ReturnType<typeof import("../../hooks").createStartWorkHook> | null;

package/dist/plugin/hooks/create-session-hooks.d.ts

@@ -3,7 +3,8 @@ import type { BackgroundManager } from "../../features/background-agent";
 import type { ModelFallbackControllerAccessor } from "../../hooks/model-fallback";
 import type { ModelCacheState } from "../../plugin-state";
 import type { PluginContext } from "../types";
-import { createSessionNotification, createThinkModeHook, createModelFallbackHook, createAnthropicContextWindowLimitRecoveryHook, createAutoUpdateCheckerHook, createCodegraphBootstrapHook, createAstGrepSgProvisionHook, createAgentUsageReminderHook, createNonInteractiveEnvHook, createInteractiveBashSessionHook, createRalphLoopHook, createEditErrorRecoveryHook, createDelegateTaskRetryHook, createTaskResumeInfoHook, createStartWorkHook, createPrometheusMdOnlyHook, createSisyphusJuniorNotepadHook, createNoSisyphusGptHook, createNoHephaestusNonGptHook, createHephaestusAgentsMdInjectorHook, createQuestionLabelTruncatorHook, createPreemptiveCompactionHook, createRuntimeFallbackHook, createLegacyPluginToastHook } from "../../hooks";
+import { createSessionNotification, createThinkModeHook, createModelFallbackHook, createAnthropicContextWindowLimitRecoveryHook, createAutoUpdateCheckerHook, createCodegraphBootstrapHook, createAstGrepSgProvisionHook, createAgentUsageReminderHook, createNonInteractiveEnvHook, createInteractiveBashSessionHook, createEditErrorRecoveryHook, createDelegateTaskRetryHook, createTaskResumeInfoHook, createStartWorkHook, createPrometheusMdOnlyHook, createSisyphusJuniorNotepadHook, createNoSisyphusGptHook, createNoHephaestusNonGptHook, createHephaestusAgentsMdInjectorHook, createQuestionLabelTruncatorHook, createPreemptiveCompactionHook, createRuntimeFallbackHook, createLegacyPluginToastHook } from "../../hooks";
+import { createGoalHook } from "../../hooks/goal";
 export type SessionHooks = {
     preemptiveCompaction: ReturnType<typeof createPreemptiveCompactionHook> | null;
     sessionNotification: ReturnType<typeof createSessionNotification> | null;
@@ -16,7 +17,7 @@ export type SessionHooks = {
     agentUsageReminder: ReturnType<typeof createAgentUsageReminderHook> | null;
     nonInteractiveEnv: ReturnType<typeof createNonInteractiveEnvHook> | null;
     interactiveBashSession: ReturnType<typeof createInteractiveBashSessionHook> | null;
-    ralphLoop: ReturnType<typeof createRalphLoopHook> | null;
+    goal: ReturnType<typeof createGoalHook> | null;
     editErrorRecovery: ReturnType<typeof createEditErrorRecoveryHook> | null;
     delegateTaskRetry: ReturnType<typeof createDelegateTaskRetryHook> | null;
     startWork: ReturnType<typeof createStartWorkHook> | null;

package/dist/plugin/hooks/create-transform-hooks.d.ts

@@ -1,7 +1,6 @@
 import type { OhMyOpenCodeConfig } from "../../config";
 import type { MonitorManager } from "../../features/monitor";
 import type { PluginContext } from "../types";
-import type { RalphLoopHook } from "../../hooks/ralph-loop";
 import { createClaudeCodeHooksHook, createKeywordDetectorHook, createMonitorStatusInjectorHook, createTeamMailboxInjector, createTeamModeStatusInjector, createToolPairValidatorHook } from "../../hooks";
 import { createContextInjectorMessagesTransformHook } from "../../features/context-injector";
 export type TransformHooks = {
@@ -18,6 +17,5 @@ export declare function createTransformHooks(args: {
     pluginConfig: OhMyOpenCodeConfig;
     isHookEnabled: (hookName: string) => boolean;
     safeHookEnabled?: boolean;
-    ralphLoop?: RalphLoopHook | null;
     monitorManager?: MonitorManager;
 }): TransformHooks;

package/dist/plugin/stop-continuation.d.ts

@@ -5,8 +5,8 @@ type StopContinuationHooks = {
     readonly todoContinuationEnforcer?: {
         readonly cancelAllCountdowns: () => void;
     } | null;
-    readonly ralphLoop?: {
-        readonly cancelLoop: (sessionID: string) => boolean | void;
+    readonly goal?: {
+        readonly clearGoal: (sessionID: string) => boolean;
     } | null;
 };
 export declare function stopContinuation(args: {

package/dist/shared/omo-process-sweep.d.ts

@@ -0,0 +1,18 @@
+import { sweepCodegraphZombies, sweepOrphanedLspDaemonProxies, sweepStaleLspDaemonVersions } from "@oh-my-opencode/utils/process-sweep";
+export interface OmoFamilySweepOptions {
+    readonly log?: (message: string) => void;
+}
+export interface OmoFamilySweeps {
+    readonly sweepCodegraph: typeof sweepCodegraphZombies;
+    readonly sweepLspProxies: typeof sweepOrphanedLspDaemonProxies;
+    readonly sweepStaleLspDaemons: typeof sweepStaleLspDaemonVersions;
+}
+export declare function sweepCodegraphZombiesBestEffort(options: OmoFamilySweepOptions, sweep?: typeof sweepCodegraphZombies): Promise<void>;
+export declare function sweepOrphanedLspDaemonProxiesBestEffort(options: OmoFamilySweepOptions, sweep?: typeof sweepOrphanedLspDaemonProxies): Promise<void>;
+export declare function sweepStaleLspDaemonVersionsBestEffort(options: OmoFamilySweepOptions, sweep?: typeof sweepStaleLspDaemonVersions): Promise<void>;
+/**
+ * Runs all three omo sweep families concurrently. NEVER rejects: each family
+ * is wrapped best-effort so a sweep failure can only produce a log line, not
+ * a startup failure. Callers fire-and-forget the returned promise.
+ */
+export declare function sweepOmoFamiliesBestEffort(options?: OmoFamilySweepOptions, sweeps?: OmoFamilySweeps): Promise<void>;

package/dist/shared/system-directive.d.ts

@@ -34,7 +34,6 @@ export declare function hasSystemReminder(text: string): boolean;
 export declare function removeSystemReminders(text: string): string;
 export declare const SystemDirectiveTypes: {
     readonly TODO_CONTINUATION: "TODO CONTINUATION";
-    readonly RALPH_LOOP: "RALPH LOOP";
     readonly BOULDER_CONTINUATION: "BOULDER CONTINUATION";
     readonly DELEGATION_REQUIRED: "DELEGATION REQUIRED";
     readonly SINGLE_TASK_ONLY: "SINGLE TASK ONLY";

package/dist/skills/programming/scripts/typescript/check-no-excuse-rules.test.ts

@@ -0,0 +1,87 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test"
+import { spawnSync } from "node:child_process"
+import { copyFileSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs"
+import { createRequire } from "node:module"
+import { tmpdir } from "node:os"
+import { dirname, join } from "node:path"
+
+// Regression for lazycodex#111: the script must resolve `typescript` from the
+// caller project (cwd), not from the script's own location, so it works when
+// executed from an installed `~/.codex/...` skill cache.
+
+const scriptSource = join(import.meta.dir, "check-no-excuse-rules.ts")
+const repoRequire = createRequire(import.meta.url)
+const typescriptPackageDir = dirname(repoRequire.resolve("typescript/package.json"))
+
+let tempRoot = ""
+let cachedScript = ""
+let callerDir = ""
+let callerWithoutTypescriptDir = ""
+
+function runNoExcuse(cwd: string, target: string) {
+	return spawnSync(process.execPath, ["--no-install", cachedScript, target], {
+		cwd,
+		encoding: "utf8",
+		timeout: 60_000,
+	})
+}
+
+describe("#given the no-excuse script is executed from an installed ~/.codex-style skill cache", () => {
+	beforeAll(() => {
+		// given a cache copy of the script outside any project, and two caller projects:
+		// one providing node_modules/typescript, one without typescript at all
+		tempRoot = mkdtempSync(join(tmpdir(), "no-excuse-cache-repro-"))
+		const cacheDir = join(tempRoot, ".codex", "skills", "programming", "scripts", "typescript")
+		mkdirSync(cacheDir, { recursive: true })
+		cachedScript = join(cacheDir, "check-no-excuse-rules.ts")
+		copyFileSync(scriptSource, cachedScript)
+
+		callerDir = join(tempRoot, "caller-project")
+		mkdirSync(join(callerDir, "node_modules"), { recursive: true })
+		symlinkSync(typescriptPackageDir, join(callerDir, "node_modules", "typescript"), "junction")
+		writeFileSync(join(callerDir, "clean.ts"), "export const answer: number = 42\n")
+		writeFileSync(join(callerDir, "violating.ts"), "const x = foo as any\nexport default x\n")
+
+		callerWithoutTypescriptDir = join(tempRoot, "caller-without-typescript")
+		mkdirSync(callerWithoutTypescriptDir, { recursive: true })
+		writeFileSync(join(callerWithoutTypescriptDir, "clean.ts"), "export const answer: number = 42\n")
+	})
+
+	afterAll(() => {
+		rmSync(tempRoot, { recursive: true, force: true })
+	})
+
+	// A generous timeout: the first run does a cold TypeScript program load in a
+	// spawned subprocess, which can exceed bun test's 5s default on a cold cache
+	// (matches the 60s spawnSync ceiling). This bounds the subprocess, it does not
+	// wait on wall-clock time as behavior.
+	test("#when the caller project provides typescript #then it resolves the caller's typescript and exits 0", () => {
+		// when no-excuse runs from the cache copy against the caller project
+		const result = runNoExcuse(callerDir, "clean.ts")
+
+		// then the caller's own typescript is used and the clean file passes
+		expect(result.error).toBeUndefined()
+		expect(result.status).toBe(0)
+		expect(result.stdout).toContain("No violations in 1 file(s).")
+	}, 60_000)
+
+	test("#when a checked file violates the rules #then violations are still reported with exit 1", () => {
+		// when no-excuse runs against a file containing `as any`
+		const result = runNoExcuse(callerDir, "violating.ts")
+
+		// then the existing CLI behavior is unchanged
+		expect(result.error).toBeUndefined()
+		expect(result.status).toBe(1)
+		expect(result.stderr).toContain("[no-any-assertion]")
+	}, 60_000)
+
+	test("#when the caller project genuinely lacks typescript #then it fails with a clear error and exit 2", () => {
+		// when no-excuse runs from a caller project with no local typescript
+		const result = runNoExcuse(callerWithoutTypescriptDir, "clean.ts")
+
+		// then it reports the resolution problem instead of crashing mid-analysis
+		expect(result.error).toBeUndefined()
+		expect(result.status).toBe(2)
+		expect(result.stderr).toContain('cannot resolve "typescript" from the caller project')
+	}, 60_000)
+})

package/dist/skills/programming/scripts/typescript/check-no-excuse-rules.ts

@@ -19,6 +19,10 @@
  * Usage:
  *   bun run scripts/check-no-excuse-rules.ts <file-or-dir>...
  *
+ * The `typescript` package is resolved from the caller project (process.cwd()),
+ * not from this script's location, so the script works when executed from an
+ * installed skill-cache path (e.g. ~/.codex/...) against a project checkout.
+ *
  * Exit codes:
  *   0 - no violations
  *   1 - violations found
@@ -26,9 +30,35 @@
  */
 
 import fs from "node:fs"
+import { createRequire } from "node:module"
 import path from "node:path"
 import process from "node:process"
-import ts from "typescript"
+import type * as tsTypes from "typescript"
+
+type TsModule = typeof import("typescript")
+
+function loadTypescriptFromCaller(): TsModule {
+  // A static `import ts from "typescript"` resolves from this script's location —
+  // an installed skill-cache path (e.g. ~/.codex/...) with no node_modules of its
+  // own — and fails even when the checked project has typescript. Resolve from the
+  // caller project (cwd) instead. When the caller has no local typescript, Bun
+  // falls back to a version-only stub from its global install cache instead of
+  // throwing, so the loaded module's API shape is verified as well.
+  const callerRequire = createRequire(path.join(process.cwd(), "no-excuse-anchor.cjs"))
+  try {
+    const loaded: Partial<TsModule> = callerRequire("typescript")
+    if (typeof loaded.createSourceFile === "function") return loaded as TsModule
+  } catch { // no-excuse-ok: catch
+    // fall through to the clear error below
+  }
+  console.error(
+    `error: cannot resolve "typescript" from the caller project (${process.cwd()}). ` +
+      "Install it in the project being checked (e.g. `bun add -d typescript`) and re-run.",
+  )
+  process.exit(2)
+}
+
+const ts: TsModule = loadTypescriptFromCaller()
 
 type RuleId =
   | "no-any-assertion"
@@ -95,7 +125,7 @@ function discoverFiles(inputs: string[]): string[] {
   return files
 }
 
-function getLineText(sourceFile: ts.SourceFile, line: number): string {
+function getLineText(sourceFile: tsTypes.SourceFile, line: number): string {
   const lineStarts = sourceFile.getLineStarts()
   const start = lineStarts[line]
   const end = line + 1 < lineStarts.length ? lineStarts[line + 1] : sourceFile.getEnd()
@@ -107,17 +137,17 @@ function analyzeFile(filePath: string): Violation[] {
   const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true)
   const violations: Violation[] = []
 
-  function pos(node: ts.Node): { line: number; column: number } {
+  function pos(node: tsTypes.Node): { line: number; column: number } {
     const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile))
     return { line: line + 1, column: character + 1 }
   }
 
-  function lineHasOptOut(node: ts.Node): boolean {
+  function lineHasOptOut(node: tsTypes.Node): boolean {
     const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile))
     return OPT_OUT_RE.test(getLineText(sourceFile, line))
   }
 
-  function visit(node: ts.Node): void {
+  function visit(node: tsTypes.Node): void {
     // ── as any / as unknown ──
     if (ts.isAsExpression(node)) {
       const typeText = node.type.getText(sourceFile)

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

@@ -13,35 +13,58 @@ You are **Prometheus**, a planning consultant. You turn a vague or large request
 
 Outcome-first: explore a lot, ask few sharp questions - or none, when the intent is fuzzy (see routing) - and stop the moment the plan is done.
 
+## MANDATORY OPENING ANNOUNCEMENT
+
+The FIRST user-visible line of the turn that activates this skill MUST be exactly:
+
+`ULW-PLAN MODE ENABLED!`
+
+If another active mode mandates its own first line (ultrawork does), print that line first and this marker on the next line - both contracts stay satisfied.
+
+Directly under the marker, before any exploration, state the working contract once, in your own words, carrying ALL of these commitments:
+
+1. **Persona + no-implementation pledge** - from now on you work as Prometheus, a planning consultant, and you will never start implementation - no product-code edits, no implementer subagents - until the user explicitly says okay; even then, approval authorizes writing the plan only, and execution starts in a separate worker session (e.g. `$start-work`).
+2. **Workflow preview** - the order of what happens next: parallel read-only exploration (plus outside research when the repo cannot answer) until the open unknowns are resolved; the intent verdict from INTENT ROUTING, announced; questions to the user ONLY when a genuine owner-decision survives exploration - or when exploration and research both come back empty on a fork the plan cannot proceed without; then the approval brief, and the plan is written only after the explicit okay.
+
+Example opening (adapt the wording, keep every commitment):
+
+> ULW-PLAN MODE ENABLED!
+> From now on I am working as Prometheus, a planning consultant. I will not start any implementation until you explicitly say okay - and approval authorizes writing the plan only; execution starts separately (e.g. `$start-work`).
+> Next, in order: (1) parallel read-only exploration and research, (2) intent verdict announced (CLEAR or UNCLEAR, plus whether high-accuracy review is required), (3) questions only for the forks exploration cannot settle - or where research finds nothing on a blocking decision, (4) approval brief, then (5) the plan is written after your okay.
+
 ## INTENT ROUTING - pick ONE intent reference
 
 **Review modifiers are a gate trigger, not a style cue.** If the user says "high accuracy", "ultra high accuracy", "고정밀", "deep review", or equivalent - in ANY turn, even appended to a follow-up question and even after the plan already exists - set `review_required: true` in the draft: the dual high-accuracy review (native `momus` + the independent Oracle review) is now REQUIRED before handoff, and if the plan already exists you run it this same turn. Answering the current question more carefully does NOT satisfy it. This does NOT choose CLEAR/UNCLEAR and does NOT suppress interview.
 
-After grounding, make ONE judgment, record `intent: clear|unclear` plus `review_required`, **ANNOUNCE both to the user in one line**, then load ONE intent reference (you ALSO read `references/full-workflow.md` for the shared mechanics - see below). The test keys on whether the desired **OUTCOME** is clear, NOT on request length. The announcement is the user's first signal of whether they will be interviewed and whether high-accuracy review is already requested - never skip it.
+After grounding, make ONE judgment, record `intent: clear|unclear` plus `review_required`, **ANNOUNCE both to the user in one line**, then load ONE intent reference (you ALSO read `references/full-workflow.md` for the shared mechanics - see below). The test keys on whether the desired **OUTCOME** is clear, NOT on request length. This verdict line and the opening announcement above are the two mandatory user-visible signals of a planning session - it tells the user whether they will be interviewed and whether high-accuracy review is already requested; never skip either.
 
 > "Intent: **CLEAR**, review required - you specified the endpoint and asked for high accuracy. I will ask only the genuine forks, then run the high-accuracy review after approval."
 > "Intent: **UNCLEAR**, review required - 'make auth better' is open-ended and you asked for high accuracy. I will choose best-practice defaults, then run the high-accuracy review automatically."
 
 - **OVERRIDE - explicit ask wins:** if the user explicitly asks to be questioned or interviewed ("ask me", "interview me", "why aren't you asking me" - in any language), route **CLEAR**, run the interview, and turn the adopt-default filter OFF: the user has claimed the forks, so every surviving one is ASKED, not defaulted. This beats the OUTCOME test below, even on a fuzzy brief.
 - **CLEAR** - the user knows the outcome; the only open items are preferences/tradeoffs the repo cannot answer (genuine owner-decisions). Read **`references/intent-clear.md`**: ask the surviving forks with WHY, run the normal approval gate, and offer high-accuracy review only when `review_required` is false.
-- **UNCLEAR** - the outcome itself is fuzzy (a vague brief, a bootstrap, `$start-work` with no selectable plan, a goal the user cannot yet articulate). Asking would offload your own job onto the user. Read **`references/intent-unclear.md`**: research maximally, adopt and ANNOUNCE best-practice defaults, do NOT ask the user extra questions, and run high-accuracy review AUTOMATICALLY (unless Classify sized the work Trivial).
+- **UNCLEAR** - the outcome itself is fuzzy (a vague brief, a bootstrap, `$start-work` with no selectable plan, a goal the user cannot yet articulate). Asking would offload your own job onto the user. Read **`references/intent-unclear.md`**: research maximally, adopt and ANNOUNCE best-practice defaults, do NOT ask the user extra questions, and, unless Classify sized the work Trivial, set `review_required: true` before the approval gate and run high-accuracy review AUTOMATICALLY.
 - **ON THE FENCE** - when CLEAR vs UNCLEAR is genuinely ambiguous, treat it as CLEAR and ask exactly ONE question. A user wrongly silenced is worse than one extra question. The dominant failure to guard against is mis-routing a CLEAR request to UNCLEAR, which silently applies defaults and overrides forks the user wanted to own.
 
 WORKED: "add a 5/min-per-IP rate-limit to `/login`" = CLEAR. "make auth better" = UNCLEAR.
 
 Both intent paths ALSO read **`references/full-workflow.md`** for the shared mechanics - the plan template, the final verification wave, the APPEND protocol, and the full delegation/wait syntax. Read the phase you are in.
 
-## RUN THE SCRIPT - do not hand-build the plan files
+## RUN THE SCRIPT - do not hand-build artifacts
 
-Before writing any plan or draft by hand, RUN:
+As soon as `<slug>` and intent are known, before recording draft state, RUN:
 
 ```
-node "<skill-root>/scripts/scaffold-plan.mjs" <slug> [--clear|--unclear]
+node "<skill-root>/scripts/scaffold-plan.mjs" <slug> [--clear|--unclear] --draft-only [--review-required]
 ```
 
-(Replace `<skill-root>` with this skill's own directory; `bun` is an accepted substitute for `node`.) It creates `.omo/drafts/<slug>.md` (your durable, compaction-safe resume point) and `.omo/plans/<slug>.md` (skeleton with the human `## TL;DR (For humans)` block on top and every plan header below). Then **APPEND** task batches into the marked `## Todos` region with edit/apply_patch - **never rewrite the script-emitted headers**. This replaces ~10 manual file writes and guarantees the human-readable summary always leads the plan.
+(Replace `<skill-root>` with this skill's own directory; `bun` is accepted.) This creates only `.omo/drafts/<slug>.md`, the compaction-safe resume point; it does not create a plan before approval. Include `--review-required` when an explicit modifier requires review or the classified route is non-Trivial UNCLEAR, so the first durable write contains the complete pending review request. After approval, rerun without `--draft-only` to create `.omo/plans/<slug>.md`, then **APPEND** task batches into `## Todos` - never rewrite script-emitted headers.
+
+Both invocations are resume-safe no-ops for artifacts already present. Do NOT hand-build them; use `--reset` only for a structural reset (`--reset --force` discards edits). If a same-named non-artifact file exists, choose another slug.
+
+## Plan artifact producer contract
 
-Run it ONCE at plan generation. A plain re-run on an existing plan is a safe no-op - it never overwrites your appended todos - so resuming after compaction cannot crash the turn or clobber the plan. Do NOT hand-build these files; if a structural reset is ever needed, use `--reset` (and `--reset --force` to discard hand edits). If it refuses because a same-named NON-artifact file exists, pick a different `<slug>` - do NOT `--reset` over a human file you did not create.
+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; and repair the plan before handoff if any check fails.
 
 ## Universal invariants (hold on every path)
 
@@ -58,7 +81,7 @@ Run it ONCE at plan generation. A plain re-run on an existing plan is a safe no-
 
 ## Approval gate
 
-When exploration is exhausted and the unknowns are answered, record the gate in the draft (`status: awaiting-approval`, the pending action `write .omo/plans/<slug>.md`, the approach), present a short brief once, then **wait for the user's explicit okay**. Read their next reply as a decision (approve / scope-change / still-unclear). Full gate mechanics: `references/full-workflow.md`.
+When exploration is exhausted and the unknowns are answered, record the gate in the draft (`status: awaiting-approval`, approach, and the next workflow action), present a short brief once, then **wait for the user's explicit okay**. Approval authorizes plan creation only; any already-required review runs afterward under its existing authorization. Full mechanics: `references/full-workflow.md`.
 
 ## Delegation (OpenCode-native)