ultragoal

ultragoal은 작동 루프에서 증거 기반 실행 단계입니다. 승인된 brief를 repo-native 아티팩트로 바꾸고, 목표를 구현·수정·검증·최종 증거 요약까지 끌고 갑니다. ralplan이 검토된 계획을 만들면, ultragoal이 그것을 완료·체크포인트된 결과까지 가져갑니다.

무엇을 추적하나

계획은 지속 가능한 repo-native 아티팩트 몇 개가 됩니다:

새 계획은 기본적으로 집계 목표를 둡니다. 이는 전체 지속 계획에 대한 안정적인 포인터 역할을 하며, 스토리 진행은 ledger에서 추적합니다. ledger는 지속 감사 추적이므로 성공이든 실패든 매번 체크포인트하세요.

목표 만들기

승인된 계획에서 시작합니다. brief 문자열, brief 파일, 또는 stdin을 씁니다:

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

그 다음 .gjc/ultragoal/goals.json을 확인하고 필요하면 다듬습니다. 스토리당 하나의 목표 컨텍스트가 명시적으로 선호될 때만 --gjc-goal-mode per-story를 씁니다.

승인된 계획이나 합의 아티팩트가 없다면 먼저 ralplan을 돌리세요. PRD·테스트 사양·역할 명단·검증 가이드를 ledger에 보존합니다. 계획이 빠진 채 임시 실행으로 조용히 대체하지 마세요.

목표 완료하기

실행을 완료까지 끌고 갑니다. gjc ultragoal status가 모든 목표 완료를 보고할 때까지 반복합니다:

인라인 목표 상태는 통합 goal 도구로 다룹니다. 그것이 목표 상태의 유일한 에이전트 대면 표면입니다:

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

집계 모드에서는 중간 스토리에 대해 goal({"op":"complete"})를 호출하지 않습니다. 리뷰 게이트를 통과하고 최종 집계 영수증이 존재한 뒤 마지막 스토리에서만 발동합니다.

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

체크포인트

각 스토리는 체크포인트로 기록됩니다. complete 체크포인트는 깨끗한 품질 게이트가 필요합니다. 런타임 훅은 품질 게이트 없이 종료를 거부합니다:

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>

스토리가 차단되거나 실패하면 종결 상태를 대신 기록합니다:

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

ledger를 증거로 다루세요. 체크포인트가 영수증을 만듭니다. goals.json.status만으로는 완료 증거가 되지 않습니다.

완료 정리·리뷰 게이트

품질 게이트가 돌기 전에는 스토리를 complete로 체크포인트할 수 없습니다:

"깨끗함" 조건은 다음을 모두 만족할 때입니다:

• 모든 architectReview 상태가 "CLEAR"이고 recommendation이 "APPROVE"
• executor QA 상태가 "passed"이고 iteration이 fullRerun: true로 "passed"
• 모든 evidence 필드가 비어있지 않음
• 모든 blockers 배열이 비어있음

다음 중 하나라도 있으면 깨끗하지 않습니다: COMMENT, WATCH, REQUEST CHANGES, BLOCK, 누락된 증거, 비어있지 않은 blockers.

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>

동적 steering

실제 발견이 스토리 분해를 바꿔야 함을 증명할 때 gjc ultragoal steer를 씁니다. 집계 목표와 원래 제약은 고정됩니다. steering은 명시적·증거 기반이며, 광범위한 자연어 요청은 추측하지 않고 거부됩니다.

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

허용 mutation 종류: add_subgoal, split_subgoal, reorder_pending, revise_pending_wording, annotate_ledger, mark_blocked_superseded.

steering의 제약:

• 집계 목표, 원래 brief 제약, 품질 게이트, 완료 상태는 절대 편집하지 않습니다.
• 목표를 hard-delete하거나 검증을 약화시키지 않습니다.
• 수락·거부된 시도 모두 ledger에 감사 항목을 추가합니다.

역할 에이전트 위임

스토리가 위임으로 이득을 볼 만큼 클 때는 번들된 역할 에이전트를 씁니다:

독립적인 슬라이스가 있는 큰 서브골에서는 병렬 executor 서브에이전트를 띄웁니다. 순차적 단독 작업 대신, 각각에 제한적이고 깔끔하게 분리되는 타깃을 줍니다.

ultragoal 리더가 goals.json과 ledger.jsonl을 소유합니다. 역할 에이전트는 구현·리뷰 증거를 반환할 뿐, ultragoal을 체크포인트하거나 목표 상태를 변경하지 않습니다.

ultragoal과 team 함께 쓰기

눈에 보이는 병렬 실행 레인이 도움이 되는 지속 스토리라면 ultragoal을 team과 짝지으세요.

• ultragoal은 리더 소유로 남습니다.
• team은 태스크·증거 상태를 반환하는 tmux 실행 엔진입니다.
• 리더는 최신 목표 스냅샷으로 team 증거에서 ultragoal을 체크포인트합니다.
• 워커는 목표 상태를 소유하지 않으며 gjc ultragoal checkpoint를 실행해서는 안 됩니다.