ultragoal

Ultragoal — Sequential Multi-Story Objective-Pursuit Executor

Ultragoal decomposes a single OBJECTIVE into the Seven Slots and an auto-generated Story set, has the user review and bulk-approve that set in one pass, then dispatches the confirmed stories to sisyphus one story at a time, in sequence: the next story is never dispatched until the current story's per-story verdict is APPROVE. Only after every confirmed story is APPROVE does a single independent code-review run over the accumulated diff. sisyphus remains the sole executor throughout — ultragoal never delegates execution to another skill at runtime. Codex's native goal tools (create_goal/update_goal/get_goal) are model-callable tools, not skill dispatches, and calling them is not a violation of this invariant.

Scope invariant: review cannot enlarge the approved objective. Every repair must trace to an approved requirement or a regression caused by this pursuit, fit its boundaries, and respect its non-goals. Scope admission comes first; HIGH and MEDIUM findings route to bounded work, LOW findings remain notes-only, and excluded improvements never become work. See references/completion-gate.md for mandatory admission.

Design philosophy: autonomy is post-planning. Planning carries a single human gate — bulk approval of the auto-generated Story set; that gate runs UN-wrapped. The autonomy begins after planning, during the per-story pursuit loop. The single load-bearing invariant of the whole design: the loop never false-completes. Every state-write or verdict-write failure degrades toward continued pursuit of the current story or block — never toward a claimed completion.

Single-story degrade. When the objective decomposes to exactly one story, ultragoal collapses to a single-gate loop: set-stories --single auto-derives and auto-confirms the one story, a single Skill(skill: "sisyphus") dispatch runs, and the per-story advance gate and the final completion gate collapse into the same single check.

State CLI

The autonomous loop is gated by a session-keyed state file driven through the bundled CLI, kept in its own artifact namespace (ultragoal-state-/ultragoal-verdict-/ultragoal-codereview-). Reference it ONLY via the skill-dir variable, never CWD-relative:

bun ${CLAUDE_SKILL_DIR}/scripts/ultragoal-state.ts <subcommand> [options]

Subcommands used by this orchestrator:

Subcommand	Authority	Purpose
set --phase <planning|pursuing> [slot flags…]	orchestrator	Seed/advance phase; carries the slot values. Accepts ONLY planning/pursuing — it can never write complete, and on planning it resets the verdict to absent.
confirm-all-stories	orchestrator	Bulk-approves every unconfirmed story in the auto-generated set in one call — ultragoal's decomposition affordance, replacing a per-story confirm-story dialogue.
reorder-stories --order <id1,id2,...>	orchestrator	Planning-only reorder of the story array to an exact permutation of the current ids — steers the sequential dispatch order before pursuit begins.
set-verdict --verdict <APPROVE|REQUEST_CHANGES|COMMENT|absent>	gate layer	The ONLY writer of objective_verdict.
request-complete	gate layer	The ONLY path to phase=complete; structurally gated on completion-evidence being present and objective_verdict=APPROVE.
get-review-result	code-review lane	Read the current session's script-derived code-review result; reviewer/orchestrator never hand-sets the aggregate.
record-comment-resolution --artifact-sha256 <sha> --evidence <paths>	code-review lane	Record hash-bound evidence after required MEDIUM repairs and affected checks.
claim-review-dispatch	PreToolUse hook only	Atomically reserves one final code-review dispatch. The initial cap is 5; it persists the reservation before allowing the dispatch. The orchestrator never calls this command directly.
approve-review-dispatch-renewal	user only — a PreToolUse guard denies it on the orchestrator's Bash path; present the command and have the user run it	Adds exactly 5 to the review-dispatch cap; when a valid code-review artifact exists, also records the SHA-256 of its exact raw bytes as the user-approved marker (an absent/invalid artifact still renews — sole recovery when all dispatches died before writing one).
dismiss-review-finding --ref <file:line> --class <correctness|regression|cleanup|requirement-gap> --rationale <text>	user only — same PreToolUse guard; propose it, never run it	Removes ONE wrong admitted code-review finding from the completion gate's blocking set. Refuses unless EXACTLY ONE admitted IN_SCOPE finding with that exact ref and class is in the current artifact (two are indistinguishable to a dismissal, so clearing one would clear both), and pins the dismissal to that artifact's raw bytes so it lapses on the next review round. Propose per references/completion-gate.md; never run it on your own judgment.
resume-pursuit	user only — a PreToolUse guard denies it on the orchestrator's Bash path; present the command and have the user run it	Recovers only a budget_limited pursuit, restoring phase=pursuing, active=true, and iteration=0; refuses from any other phase.
get / status	read	Inspect current state / derived status.

set-budget-limited and set-blocked --reason <text> are system-only setters (the hook layer writes budget_limited; set-blocked records a reported blocker). The orchestrator never writes complete, budget_limited, or a fabricated verdict by any other route — the narrow gates are structural, not vigilance-based.

During pursuit, iteration counts consecutive Stop turns with no observed progress. A diff-carrying commit or a story status transition resets it to 0; Stops waiting for background work are not counted. Reaching max_iterations soft-stops the pursuit as budget_limited (state is preserved and no new work is dispatched). After draining any in-flight work and checking the completion gate, recovery from that pause requires the user to run resume-pursuit, which resets the counter and re-arms the pursuing phase.

For the final review lane, pass the supplied artifact destination opaquely and defer publication to the generic code-review publisher contract. The parent orchestrator then calls ultragoal-state.ts get-review-result, which computes the session verdict; it does not subjectively reclassify that result. set-verdict remains objective-lane-only.

---

Entry Gate

An ultragoal pursuit is only worth pursuing autonomously if "done" is decidable. Falsifiability trigger: refuse to start pursuit unless the request carries a falsifiable objective — a concrete verification surface a machine can check (a test, a benchmark, an artifact, an observable end state). "Make it better", "improve performance", "clean this up" with no verification surface are NOT pursuable objectives. When the verification surface is absent or vague, do NOT begin orchestration and do NOT advance state beyond the pristine seed (no set call); a pristine seed left untouched is inert — hooks ignore it and the lifecycle GC reaps it by TTL.

On a non-falsifiable request, take exactly ONE of these two remediation outcomes:

• outside-ultragoal clarification — when the objective is rich but under-specified (the verification surface can be derived through questioning), stop here: tell the user to invoke a clarification skill (e.g. deep-interview) directly, outside ultragoal, to crystallize a spec, then re-invoke ultragoal with that crystallized spec as the objective. Ultragoal itself does not call clarification skills — it only resumes the Entry Gate once the user re-enters with a crystallized spec.
• ask-user — when a single missing fact would make the objective falsifiable (the user can state the success criterion in one sentence), ask the user directly for the verification surface before proceeding.

Re-invocation refusal. Before seeding anything, read state via bun ${CLAUDE_SKILL_DIR}/scripts/ultragoal-state.ts get. If the result is active: true AND pristine: false, REFUSE to start a second pursuit — report the active objective and its phase, and stop. A second concurrent ultragoal is never seeded over a non-pristine active one. A pristine: true result means the state was freshly seeded by this very invocation's PreToolUse hook — proceed normally. (Terminal states read as inactive and do not block a fresh ultragoal.)

Continuation intent. When the user's invocation expresses explicit continuation intent — e.g. "하던 거 계속", "continue what I was doing", "resume the previous goal" — run:

bun ${CLAUDE_SKILL_DIR}/scripts/ultragoal-state.ts list-others

If candidates exist, present them via AskUserQuestion with one option per candidate (labeled with the candidate's purpose and age — e.g. "ship X — started 2026-06-10, 3 hours idle"), plus a "start fresh" option. Proceed to the next step ONLY on an explicit user selection:

• On candidate selection: run bun ${CLAUDE_SKILL_DIR}/scripts/ultragoal-state.ts adopt --src <selected-sid>, then run bun ${CLAUDE_SKILL_DIR}/scripts/ultragoal-state.ts get to read what was adopted, and resume from the restored state — if phase is planning, resume planning from the adopted Story set and resume_summary; if phase is pursuing, continue pursuit at the adopted iteration. Do NOT re-seed via set --phase planning from the new invocation's text.
• On "start fresh": proceed as a new ultragoal.

If no candidates exist, say so and proceed fresh. The branch never renames on its own — adoption requires an explicit user selection.

---

Planning: Seven Slots & Story Definition

You MUST read references/planning.md first before seeding the seven slots (set --phase planning), auto-generating and bulk-approving the Story set (set-stories/confirm-all-stories), or applying any mid-flight story mutation (add-story/revise-story/retire-story/split-story/reorder-stories) — it is the single owner of the slot definitions and the full story lifecycle.

---

Execution Dispatch

Ultragoal does not reimplement execution. It decomposes the objective into the Seven Slots and auto-generates a Story set itself — see references/planning.md — then, once the user bulk-approves via confirm-all-stories, dispatches the confirmed stories to sisyphus one story at a time, in sequence:

1. Arm the loop before dispatching. Run:

   bun ${CLAUDE_SKILL_DIR}/scripts/ultragoal-state.ts set --phase pursuing
   

   This must run BEFORE the first Skill(skill: "sisyphus") call below — the persistent-mode Stop hook only refuses to stop while phase=pursuing, so dispatching first leaves that story's entire execution window unguarded.

2. Derive the current story — the first confirmed story (in stored order) that does not yet carry an APPROVE per-story verdict in ultragoal-verdict-{sid}.json. No separate "current story" state field exists; it is always re-derived from the verdict artifact, never stored.

3. If the create_goal tool is available, register that story's WHAT statement as the objective by calling create_goal with it, then record the identical string via:

   bun ${CLAUDE_SKILL_DIR}/scripts/ultragoal-state.ts set --phase pursuing --codex-goal-objective - <<'OBJECTIVE'
   <the objective string just registered>
   OBJECTIVE
   

   Rules for that command:

   • Always stdin (-) with a quoted heredoc (<<'OBJECTIVE', never <<OBJECTIVE); never an inline quoted argument, in either quote style. The value must land byte-identical to what create_goal registered; the CLI strips the one newline the heredoc appends.
   • Check the delimiter against the payload before writing the command. A payload line equal to OBJECTIVE ends the body there and the rest reaches the shell as commands. If any line collides, use a delimiter you have verified is absent from the payload (OBJECTIVE_2, a longer token). set refuses an explicitly-supplied --codex-goal-objective that resolves to empty or whitespace, so a first-line collision exits non-zero instead of disarming the cross-check; a mid-payload collision truncates and the completion cross-check catches it as a mismatch.
   • The condition is the tool's presence, never a platform name. Where create_goal is absent the clause simply does not fire.

   If create_goal is refused because the thread already holds an unfinished goal, call get_goal and compare the objective it returns against this story's WHAT before doing anything else:

   • Equal to this story's WHAT → this story's own registration survived an interrupted arming (create_goal and the set above are not atomic). Re-run the arming command with the objective get_goal returned; register nothing new.
   • Not equal, and that objective belongs to a story that already carries an APPROVE verdict → that story's closing call was interrupted. Call update_goal({status:"complete"}), then retry create_goal for this story and arm normally. Not laundering — the APPROVE is already in the verdict artifact. Leaving it open is a permanent completion deadlock: every later create_goal stays refused and the cross-check can never be satisfied.
   • Not equal, anything else (a non-APPROVE story's goal — the re-plan case) → leave it alone and do not arm. set --phase planning has already cleared codex_goal_objective, so the gate is disarmed and the remaining gates carry this story. Never close such a goal to unblock create_goal.

   Dispatch ONLY that one story to sisyphus: Skill(skill: "sisyphus") with that story's WHAT statement, acceptance criteria, and verification surface, plus the pursuit's constraints, boundaries, and non_goals slot values — never the whole Story set at once. These scope limits travel with every first dispatch and repair dispatch. The executor returns a scope conflict for adjudication before editing; a review suggestion is not new authorization. Carry out the story's work on the basis of the sisyphus skill's discipline.

4. After sisyphus returns, run the per-story completion audit (see references/completion-gate.md) and re-derive that story's verdict.

5. Advance only on APPROVE. A non-APPROVE per-story verdict re-dispatches Skill(skill: "sisyphus") at the SAME story — the loop does not proceed to the next story until this one reads APPROVE.

   If the update_goal tool is available AND step 3 armed the gate for THIS story — get reports a codex_goal_objective equal to this story's WHAT, AND a fresh get_goal taken immediately beforehand reports that same objective live — call update_goal({status:"complete"}) exactly once, immediately after this story's verdict reads APPROVE: never call it on a non-APPROVE verdict or a re-dispatch retry, and a disarmed story skips it entirely. update_goal carries no goal selector — it closes whatever goal the thread currently holds — so both the recorded value and the live snapshot must name this story.

   So a re-plan cannot register a new native goal while a failed story's goal is still open — leave it rejected. Registration accepts a fresh objective only from status: "complete"; active and blocked reject it identically. Never close a non-APPROVE story's goal to unblock create_goal. Clearing an open goal is the user's action (/goal clear is an app-server RPC, not automatable here).

6. Once the current story is APPROVE, repeat from step 2 for the next confirmed story. When every confirmed story carries an APPROVE verdict, proceed to the final code-review lane (see Completion Gate).

Phase transitions

The autonomous loop blocks ONLY when phase=pursuing. Set the phase around decomposition so the loop yields while decomposing (human gates run un-wrapped) and only activates during pursuit:

• While decomposing the Seven Slots and auto-generating the Story set — run:

  bun ${CLAUDE_SKILL_DIR}/scripts/ultragoal-state.ts set --phase planning
  

  --phase planning also clears the verdict to absent, so a stale APPROVE can never survive a re-plan.
• Before the first sisyphus dispatch — see step 1 of the Execution Dispatch list above — run:

  bun ${CLAUDE_SKILL_DIR}/scripts/ultragoal-state.ts set --phase pursuing
  

Initial path: set --phase planning (seed slots) → auto-generate the Story set → user bulk-approves via confirm-all-stories → set --phase pursuing → dispatch story #1 to sisyphus. Re-plan loop-back: set --phase planning (clears the verdict) → re-generate or steer the Story set (add-story/revise-story/retire-story/split-story/reorder-stories) → user re-approves via confirm-all-stories → set --phase pursuing → dispatch the fresh sisyphus call.

---

Completion Gate

You MUST read references/completion-gate.md first before rendering a per-story verdict, evaluating the final code-review lane, or running the completion sequence (set-verdict/request-complete) — it is the single owner of the evidence rubric, the per-story and code-review artifact schemas, the pass signal, the concrete-progress routing per verdict, and the blocked-stop conditions.

Middle stories get a lightweight, self-attested per-story verdict — an inline objective self-check scoped to the one story just dispatched — no code-review runs per story. Only once every confirmed story is APPROVE does the independent code-review lane run, over the accumulated diff of all stories; a REQUEST_CHANGES result requiring HIGH/MEDIUM repair, or an unresolved/failed review submission, triggers fresh independent review under the same frozen scope. MEDIUM repairs resolve through COMMENT; LOW never triggers repair or review.

---

Benign-failure note

A verdict-write or state-write failure must degrade toward continued pursuit of the current story, never toward a claimed completion. If set-verdict fails to record APPROVE the verdict reads absent, and request-complete refuses on the verdict gate — absent verdict = block-and-continue. There is no path where a failed write produces a completion.