state

Documentation

Index

• Constants
• func CanTransition(from, to protocol.Phase) bool
• func FinalizeDone(ws *protocol.Workspace, featureID string, s protocol.State) (protocol.State, error)
• func PhaseToRole(p protocol.Phase) protocol.Role
• func RecoverTo(s protocol.State, to protocol.Phase, role protocol.Role) (protocol.State, error)
• func ShouldStop(s protocol.State) (bool, string)
• func Transition(s protocol.State, to protocol.Phase, role protocol.Role) (protocol.State, error)

Constants

const MaxGuardRetries = 2

MaxGuardRetries 是跨 round 的 guard retry 上限。 超過時不再自動重試，直接進 needs-attention。

Functions

func CanTransition

func CanTransition(from, to protocol.Phase) bool

CanTransition 檢查從 from 到 to 是否合法。

done 與 abandoned 是不可逆終態：一旦 feature 進入終態，任何轉出（含轉到 blocked／needs-attention 等 universal target）都不合法，一律回 false， 避免已結束的 feature 被重新喚醒。其餘 phase 才適用 universal-target 放行與 transitions 轉換表。

func FinalizeDone

func FinalizeDone(ws *protocol.Workspace, featureID string, s protocol.State) (protocol.State, error)

FinalizeDone 將 feature 從 pending-review 推進到 done 終態，是 CLI（cmd/4x/done.go） 與 server（internal/server/server.go）原本各自重寫的 done 收尾序列之唯一真實來源： Transition→PhaseDone（role 空字串）、設 Active=false / StopReason="done"、WriteState、 SyncFeatureStatus、append 一條 transition event。回傳寫入後的最新 State 供呼叫端使用。

SyncFeatureStatus 失敗採 non-fatal：呼叫它之前 WriteState 已成功把 state.json 寫成 done， transition 已落地；feature_list.json 的狀態投影只影響 dashboard 顯示，失敗僅記 slog warning 後續跑。回傳的 error 只反映真正 fatal 的失敗（Transition / WriteState / AppendEvent）， 避免在 state 其實已 done 時謊報整體失敗。

func PhaseToRole

func PhaseToRole(p protocol.Phase) protocol.Role

PhaseToRole 回傳某 phase 預設對應的 role

func RecoverTo

func RecoverTo(s protocol.State, to protocol.Phase, role protocol.Role) (protocol.State, error)

RecoverTo 在 crash recovery 場景下，把 state 校正到依實際 artifacts 推斷出的 phase。 與 Transition 不同，它不受一般 transitions 轉換表限制——crash 後 state.json 的 phase 與磁碟 artifacts 可能不一致（例：state.json 停在 coding，artifacts 卻已跑到 deep-review FAIL）， 一般轉換表（如 coding → amending 非法）會擋下這種校正。RecoverTo 改以「目標 phase 是否為 可恢復的工作 phase」為合法性判準，並套用與 Transition 完全相同的 round 副作用 （首次 coding → Round=1、amending → Round++），確保 recovery 後的語意與正常流程一致。

用法：僅供 run resume 校正 crash 後 phase 用，不可取代正常流程的 Transition。

func ShouldStop

func ShouldStop(s protocol.State) (bool, string)

ShouldStop 檢查是否觸發停止條件。

MaxRounds<=0 代表「不設 max rounds 上限」（未指定上限的語意）：此時跳過 max rounds 檢查，避免 Round(0) >= MaxRounds(0) 在 run 一開始就誤判停止， 僅保留 ConsecutiveNoProgress>=3 的停止條件。

func Transition

func Transition(s protocol.State, to protocol.Phase, role protocol.Role) (protocol.State, error)

Transition 執行 state 轉換，回傳錯誤或更新後的 state