docs-authority-model-reconciliation

Answer

Premise correction (code-first). The task premise claimed fleet.toml is create-only on restart. Reading loader.go first showed the opposite: ApplyFleetConfig is an upsert that re-pins existing projects (cooldown/model/provider/enabled) at every startup. The code is the behavior authority; the docs and two doc comments were the stale party. Fix = reconcile all artifacts to the verified model, and lock it in with tests.

Fix 1 — loader.go doc comment on ApplyFleetConfig (was lying):

- // ApplyFleetConfig applies fleet.toml at startup. It is create-only:
- // existing projects keep their runtime values across restarts.
+ // ApplyFleetConfig reconciles the project store against fleet.toml.
+ // It is NOT create-only. Existing projects are RE-PINNED on every
+ // startup: Cooldown, Model, Provider and Enabled are overwritten from
+ // the file, and LastPin is advanced. Projects that exist in the store
+ // but not in fleet.toml are left untouched (fleet.toml never deletes).

Fix 2 — loader.go field comment on ProjectConfig.Cooldown (was lying):

- // Cooldown is applied only at project creation; existing projects
- // keep their runtime value.
+ // Cooldown is authoritative on every startup: ApplyFleetConfig
+ // re-pins this value onto the existing project record, overwriting
+ // any runtime adjustment made since the previous boot. Empty means
+ // "preserve the current value" for existing projects.

Fix 3 & 4 — the two docs (docs/cooldown-authority.md, docs/fleet-config.md) rewritten from "create-only / runtime mutations persist" to the verified model: fleet.toml is the startup authority; runtime mutations are overwritten on boot; the file never deletes store-only projects; absent enabled/empty cooldown preserve current values.

The authoritative code path (re-pin branch, kept as-is from verified behavior):

if p, ok := s.Get(pc.ID); ok {
    // Re-pin: fleet.toml wins over any runtime mutation made
    // since the previous boot.
    if present {
        p.Cooldown = cooldown
    }
    p.Model = pc.Model
    p.Provider = pc.Provider
    if pc.Enabled != nil {
        p.Enabled = *pc.Enabled
    }
    p.LastPin = now
    if err := s.Put(p); err != nil {
        return stats, err
    }
    stats.RePinned++
    continue
}

Plus a drift guard in loader_test.go that embeds all three source files and fails if any stale phrase ("create-only on restart", "create-only upsert", …) reappears, and requires the "re-pin" model to stay stated — so docs cannot silently lie again.