evolution

Documentation

Overview

Package evolution 實作 F097 evolve 價值閘門的 deterministic veto 純函式（無 LLM）。 candidate 型別一律重用 internal/protocol，本套件不另造平行型別。

Index

• Constants
• func BareFeature(c protocol.Candidate, id, name string) feature.Feature
• func BuildEvolveReport(r EvolveRoundResult) string
• func CandidateToDiscovered(c protocol.Candidate) protocol.DiscoveredFeature
• func PreVeto(cands []protocol.Candidate, existing []feature.Feature, threshold float64) (kept, dropped []protocol.Candidate)
• type AutoRunResult
• type EnqueuedFeature
• type EvolveRoundResult
• type EvolveState
  • func LoadEvolveState(path string) (EvolveState, error)
  • func (s EvolveState) Save(path string) error
  • func (s EvolveState) ShouldHalt(maxIdle int) bool
• type Rejection
  • func PostVeto(cands []protocol.Candidate, verdicts []Verdict, existing []feature.Feature, ...) (accepted []protocol.Candidate, rejected []Rejection)
• type ResolvedEvolution
  • func ResolveEvolution(cfg protocol.Config) ResolvedEvolution
• type Verdict
  • func ParseVerdicts(path string) ([]Verdict, error)

Constants

const (
	VerdictAccept = "accept"
	VerdictReject = "reject"
)

gate role 對單一 candidate 的兩種判斷結果。

Functions

func BareFeature

func BareFeature(c protocol.Candidate, id, name string) feature.Feature

BareFeature 在 enrich（LLM）失敗或 discarded 時，用「已通過 value gate」的 candidate 原文 物化成一筆最小 feature（裁決 3：gate 已認可其價值，不因 enrich 失敗而遺失）。 Status 一律 not-started（裁決 2：閘門即核准，不再用 draft 二次卡關）。 id 與 name 由呼叫端依 backlog 編號算好後傳入。

func BuildEvolveReport

func BuildEvolveReport(r EvolveRoundResult) string

BuildEvolveReport 把單輪結果組成 .4x/evolve-report.md 內容，分段呈現 Mined / Accepted / Rejected / Enqueued / Auto-Run / Halted。

func CandidateToDiscovered

func CandidateToDiscovered(c protocol.Candidate) protocol.DiscoveredFeature

CandidateToDiscovered 把 mine/gate 階段流通的 protocol.Candidate 轉成 enrich 套件期望的 protocol.DiscoveredFeature 輸入。兩者目前都只有 Title/Description，轉接僅搬移這兩欄。

func PreVeto

func PreVeto(cands []protocol.Candidate, existing []feature.Feature, threshold float64) (kept, dropped []protocol.Candidate)

PreVeto 在 LLM gate 前做便宜去重（省 LLM 成本）：每筆 candidate 與所有 existing feature （Name+" "+Description）以及已保留的 candidate（Title+" "+Description）比對 Jaccard 相似度， 相似者丟到 dropped，其餘進 kept。比對文字為 candidate 的 Title+" "+Description。 回傳順序維持輸入順序。

Types

type AutoRunResult

type AutoRunResult struct {
	ID             string
	FinalStatus    string
	SelfModBlocked bool
}

AutoRunResult 是 --auto-run 對單一 enqueued feature 跑完 meta-loop 後的結果。 SelfModBlocked 為 true 表示觸及 self_mod_guard 受保護路徑、需人工 approve 才能完成（F098）。

type EnqueuedFeature

type EnqueuedFeature struct {
	ID       string
	Name     string
	Enriched bool
}

EnqueuedFeature 是一筆已排入 backlog 的 feature 摘要。Enriched 標記其是否經 LLM 補強 （false 代表走裁決 3 的 bare candidate fallback）。

type EvolveRoundResult

type EvolveRoundResult struct {
	Round               int
	Mined               []protocol.Candidate
	Deduped             int
	Accepted            []protocol.Candidate
	Rejected            []Rejection
	Enqueued            []EnqueuedFeature
	AutoRan             []AutoRunResult
	Halted              bool
	ConsecutiveNoAccept int
}

EvolveRoundResult 彙整單輪 evolve pipeline 的所有產出，供 BuildEvolveReport 生成 markdown。

type EvolveState

type EvolveState struct {
	Version             int       `json:"version"`
	Round               int       `json:"round"`
	ConsecutiveNoAccept int       `json:"consecutiveNoAccept"`
	LastRunAt           time.Time `json:"lastRunAt"`
}

EvolveState 跨多次 `4x evolve` 呼叫持久化 anti-spin 防空轉計數，存於 .4x/evolve-state.json。 每次 evolve 只跑一輪（裁決 4），重複跑由外部驅動；連續未接受的輪數靠本檔跨呼叫累計。

func LoadEvolveState

func LoadEvolveState(path string) (EvolveState, error)

LoadEvolveState 讀取 evolve-state.json；檔案不存在時回零值（不視為錯誤，對齊 protocol.LoadCandidates 慣例），JSON 解析失敗才回 error。

func (EvolveState) Save

func (s EvolveState) Save(path string) error

Save 以同目錄 temp file + rename 原子寫入 path，避免 dashboard 讀到半寫的 JSON。

func (EvolveState) ShouldHalt

func (s EvolveState) ShouldHalt(maxIdle int) bool

ShouldHalt 回報是否已達 anti-spin 早退門檻。 maxIdle <= 0 表示停用 halt（永遠跑）；正數時 ConsecutiveNoAccept >= maxIdle 即應早退。

type Rejection

type Rejection struct {
	Title  string
	Reason string
}

Rejection 記錄一筆被 POST-veto 否決的 candidate 與首個命中的否決原因。

func PostVeto

func PostVeto(cands []protocol.Candidate, verdicts []Verdict, existing []feature.Feature, cfg ResolvedEvolution) (accepted []protocol.Candidate, rejected []Rejection)

PostVeto 對 gate role 的 verdict 套用不可翻硬否決與 convergence cap。 依序檢查每筆 candidate，任一規則命中即 reject 並記第一個命中原因——reject 永遠蓋過 accept，不用加權平均。 否決規則順序：非 accept → 缺 why_not_hack → 低於 value_floor → 重複既有 feature → 超 max_accept_per_run → 超 max_backlog_undone。接受時把 verdict 的 ValueScore/WhyNotHack 寫回 candidate。

type ResolvedEvolution

type ResolvedEvolution struct {
	ValueFloor       float64
	MaxAcceptPerRun  int
	MaxBacklogUndone int
	GateRunner       string
	GateModel        string
	DedupThreshold   float64
	// MaxIdleRounds 為 anti-spin 早退門檻：<= 0 表示停用（永遠跑），正數才啟用。
	// 來源 EvolutionConfig.MaxIdleRounds 為 nil 時套預設 3，非 nil 照值（含明確的 0/負數）。
	MaxIdleRounds int
}

ResolvedEvolution 為填妥預設值後的 evolution 設定，供 veto 邏輯直接取用。

func ResolveEvolution

func ResolveEvolution(cfg protocol.Config) ResolvedEvolution

ResolveEvolution 把 cfg.Evolution 的零值數值欄位補上預設值後回傳。 cfg.Evolution 為 nil 時等同全部套預設；GateRunner/GateModel 不補預設（空字串保留）。

type Verdict

type Verdict struct {
	Title      string  `json:"title"`
	Verdict    string  `json:"verdict"`
	ValueScore float64 `json:"value_score"`
	WhyNotHack string  `json:"why_not_hack,omitempty"`
	Reason     string  `json:"reason,omitempty"`
}

Verdict 為 gate role 對單一 candidate 的價值判斷，對應 gate-verdicts.json 內每筆條目。

func ParseVerdicts

func ParseVerdicts(path string) ([]Verdict, error)

ParseVerdicts 讀取並解析 gate role 產出的 gate-verdicts.json。 檔案讀取或 JSON 解析失敗時回 error。