{"record":{"id":"4e6c1a2cf1c95a43","repo":"Yeachan-Heo/oh-my-codex","slug":"no-ultragoal-plan-found-at-reporelative-cwd-pat","errorCode":null,"errorMessage":"No ultragoal plan found at ${repoRelative(cwd, path)}. Run `omx ultragoal create-goals ...` first.","messagePattern":"No ultragoal plan found at (.+?)\\. Run `omx ultragoal create-goals \\.\\.\\.` first\\.","errorType":"exception","errorClass":"UltragoalError","httpStatus":null,"severity":"error","filePath":"src/ultragoal/artifacts.ts","lineNumber":988,"sourceCode":"    await handle.close().catch(() => undefined);\n    await rm(lockPath, { force: true }).catch(() => undefined);\n  }\n}\n\nasync function appendLedger(cwd: string, entry: UltragoalLedgerEntry): Promise<void> {\n  await mkdir(ultragoalDir(cwd), { recursive: true });\n  const path = ultragoalLedgerPath(cwd);\n  await appendFile(path, `${JSON.stringify(entry)}\\n`);\n}\n\n/** Pure plan read: no durable writes, no migration. */\nasync function readUltragoalPlanFile(cwd: string): Promise<UltragoalPlan> {\n  const path = ultragoalGoalsPath(cwd);\n  let raw: string;\n  try {\n    raw = await readFile(path, 'utf-8');\n  } catch {\n    throw new UltragoalError(`No ultragoal plan found at ${repoRelative(cwd, path)}. Run \\`omx ultragoal create-goals ...\\` first.`);\n  }\n  const parsed = JSON.parse(raw) as UltragoalPlan;\n  if (parsed.version !== 1 || !Array.isArray(parsed.goals)) {\n    throw new UltragoalError(`Invalid ultragoal plan at ${repoRelative(cwd, path)}.`);\n  }\n  return parsed;\n}\n\n/**\n * Pure, lock-free plan read for read-only surfaces such as\n * `omx ultragoal status`: never migrates, never writes, and is therefore safe\n * for Team workers. Durable legacy migration only happens through\n * readUltragoalPlan or the mutators, under the mutation lock and authority gate.\n */\nexport async function readUltragoalPlanSnapshot(cwd: string): Promise<UltragoalPlan> {\n  return readUltragoalPlanFile(cwd);\n}\n","sourceCodeStart":970,"sourceCodeEnd":1006,"githubUrl":"https://github.com/Yeachan-Heo/oh-my-codex/blob/3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2/src/ultragoal/artifacts.ts#L970-L1006","documentation":"The ultragoal plan file (.ultragoal goals artifact) could not be read from disk. This library stores the ultragoal plan as a JSON artifact in the repo, and any command that needs an existing plan (add goal, steer, finalize, etc.) first reads it; if readFile fails (missing file, unreadable path, wrong cwd), this error is thrown.","triggerScenarios":"Calling any ultragoal API/command that assumes an existing plan (e.g. addUltragoalGoal, steering, finalize) in a repo/cwd where `omx ultragoal create-goals ...` was never run, or where the ULTRAGOAL_DIR artifact was deleted or the cwd is not the repo root the plan was created in.","commonSituations":"Fresh clone or CI checkout without the committed .ultragoal artifact; running the CLI from a subdirectory so the relative plan path doesn't resolve; accidentally .gitignore-ing or deleting the plan file; running in a temp/worktree directory.","solutions":["Run `omx ultragoal create-goals ...` in the repo root to create the plan","Verify you are running from the same repo/cwd the plan was created in (check the path in the error message)","Check whether the plan file exists at the reported path (ls .ultragoal) and restore it from git history if it was deleted","If running in CI, ensure the step that generates/commits the ultragoal plan runs before plan-dependent steps"],"exampleFix":"# before\nomx ultragoal add-goal --objective \"ship it\"   # throws 1170\n\n# after\nomx ultragoal create-goals --brief \"...\"       # creates the plan first\nomx ultragoal add-goal --objective \"ship it\"","handlingStrategy":"validation","validationCode":"import { pathExists } from 'fs-extra';\n// or: import { existsSync } from 'node:fs';\nconst hasPlan = await pathExists(ultragoalGoalsPath(cwd));\nif (!hasPlan) await createUltragoalPlan(cwd, { brief });","typeGuard":null,"tryCatchPattern":"try { await addUltragoalGoal(cwd, opts); } catch (e) { if (e instanceof UltragoalError && /No ultragoal plan found/.test(e.message)) { await createUltragoalPlan(cwd, { brief }); } else throw e; }","preventionTips":["Always run create-goals as the first step of any pipeline that later reads the plan","Run commands from the repo root so relative artifact paths resolve","Commit the .ultragoal artifact so fresh checkouts have it"],"tags":["ultragoal","missing-artifact","cli","filesystem"],"backgroundTag":"missing-required-file","analyzedSha":"3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2","analyzedAt":"2026-08-27T22:18:39.783Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}