ultragoal

ultragoal turns an approved brief into repo-native artifacts and then drives a goal safely through implementation, revision, verification, and a final evidence summary. It is the execution-through-evidence stage of the working loop: once ralplan has produced a reviewed plan, ultragoal carries it to a finished, checkpointed result.

What it tracks

A plan becomes a small set of durable, repo-native artifacts:

New plans default to a stable pointer-style aggregate goal for the whole durable plan, while story progress is tracked in the ledger. The ledger is the durable audit trail — checkpoint after every success or failure.

Create goals

Start from an approved plan. Use a brief string, a brief file, or stdin:

gjc ultragoal create-goals --brief "<brief>"
gjc ultragoal create-goals --brief-file <approved-plan>
cat <approved-plan> | gjc ultragoal create-goals --from-stdin

Then inspect .gjc/ultragoal/goals.json and refine if needed. Pass --gjc-goal-mode per-story only when one goal context per story is explicitly preferred.

If a request has no approved plan or consensus artifact, run ralplan first and preserve its PRD, test spec, role roster, and verification guidance in the ledger. Do not silently substitute ad-hoc execution for missing planning.

Complete goals

Drive execution to completion. Loop until gjc ultragoal status reports all goals complete:

Inline goal state is driven through the unified goal tool — the only agent-facing surface for it:

goal({"op":"get"})
goal({"op":"create","objective":"<printed payload objective>"})
goal({"op":"complete"})

In aggregate mode, do not call goal({"op":"complete"}) for intermediate stories. It fires only on the final story, after the review gate passes and the final aggregate receipt exists.

gjc ultragoal status
gjc ultragoal status --json
gjc ultragoal complete-goals
gjc ultragoal complete-goals --retry-failed

Checkpoints

Each story is recorded with a checkpoint. A complete checkpoint requires a clean quality gate; the runtime hook rejects closure without one:

gjc ultragoal checkpoint --goal-id <id> --status complete \
  --evidence "<evidence>" \
  --gjc-goal-json <goal-get-json-or-path> \
  --quality-gate-json <quality-gate-json-or-path>

If a story is blocked or fails, record the terminal state instead:

gjc ultragoal checkpoint --goal-id <id> --status failed --evidence "<blocker/evidence>"

Treat the ledger as proof: a checkpoint creates a receipt, and goals.json.status alone is not proof of completion.

Completion cleanup and review gate

A story cannot be checkpointed complete until the quality gate has run:

"Clean" means all architectReview statuses are "CLEAR", the recommendation is "APPROVE", executor QA statuses are "passed", iteration is "passed" with fullRerun: true, every evidence field is non-empty, and every blockers array is empty. COMMENT, WATCH, REQUEST CHANGES, BLOCK, missing evidence, or non-empty blockers are non-clean.

gjc ultragoal record-review-blockers --goal-id <id> \
  --title "Resolve verification blockers" \
  --objective "<blocker-resolution objective>" \
  --evidence "<architect/executor findings>" \
  --gjc-goal-json <active-goal-get-json-or-path>

Dynamic steering

Use gjc ultragoal steer when real findings prove the story decomposition should change while the aggregate objective and original constraints stay fixed. Steering is explicit-only and evidence-backed; broad natural-language requests are rejected instead of guessed.

gjc ultragoal steer --kind add_subgoal \
  --title "Investigate blocker" \
  --objective "Validate the blocker and report evidence." \
  --evidence "log/test output" \
  --rationale "The blocker changes the safe execution order." --json

Allowed mutation kinds are add_subgoal, split_subgoal, reorder_pending, revise_pending_wording, annotate_ledger, and mark_blocked_superseded. Steering never edits the aggregate objective, original brief constraints, quality gates, or completion status, and never hard-deletes goals or weakens verification. Accepted and rejected attempts both append audit entries to the ledger.

Role-agent delegation

When a story is large enough to benefit from delegation, use the bundled role agents:

For large subgoals with independent slices, the leader must spawn parallel executor subagents instead of doing serial solo work, giving each a bounded, cleanly separable target.

The ultragoal leader owns goals.json and ledger.jsonl. Role agents return implementation and review evidence — they do not checkpoint ultragoal or mutate goal state.

ultragoal and team together

For a durable story that benefits from a visible parallel execution lane, pair ultragoal with team. Ultragoal stays leader-owned; team is the tmux execution engine that returns task and evidence status. The leader checkpoints ultragoal from team evidence with a fresh goal snapshot. Workers do not own goal state and must not run gjc ultragoal checkpoint.