张宗平
5.1 KiB
Long-Loop Discipline — Disk Is Truth, Conversation Is Decorative
The cross-cutting axiom that every other /evolve reference implements.
When a loop runs past ~50 cycles (/evolve, /loop, ScheduleWakeup-driven
cron), every load-bearing state must live on disk, not in conversation
context. The conversation accumulates: skill prompts re-inject, hook
reminders pile up, tool-result history grows. Auto-compact handles it well
enough that correctness survives — if and only if the work-state was on
disk to begin with.
This doc is the principle; the implementing references are listed below.
The Axiom
| State | Truth surface |
|---|---|
| Cycle outcome | .agents/evolve/cycle-history.jsonl (append-only, read at every cycle start) |
| Hypothesis tracker | .agents/evolve/hypotheses.jsonl |
| Queueable work | bd ready (Dolt-backed, out-of-band) |
| Skill rules | skills/<n>/SKILL.md + references/ (read fresh per cycle) |
| Conversation context | Decorative — re-derives state from disk; never trusted alone |
If you remove the conversation context entirely between cycles and the work keeps moving, the loop is healthy. If removing it breaks the loop, you are storing load-bearing state in the wrong place.
Evidence (anchored)
"Every cycle starts by recovering state from
.agents/evolve/cycle-history.jsonl— not from the conversation. Context drift in the conversation doesn't lose the work-state … The conversation context that accumulates is mostly decorative; the load-bearing state is on disk." —docs/learnings/2026-05-13-loop-context-drift-87-cycle-observation.md(87-cycle empirical observation)
"text in SKILL.md is aspirational until paired with harness automation." —
docs/learnings/2026-05-11-evolve-skill-friction-from-13-cycle-session.md(H45.2 + H45.3 falsified within 4-6 cycles because the rule lived only in prose, not in a gate)
"Cycle 12's deep-scout … was the most productive move of cycles 11-13 even though it shipped zero code. … A scout cycle is neither productive (ships code) nor idle (finds nothing): it ships durable knowledge about pending work, narrowing future cycles' search and discovery cost." —
.agents/learnings/2026-05-11-evolve-scout-mode-pattern.md(durable knowledge IS the disk-truth surface)
"in a shared tree, commit by explicit path (
git add <files>), nevergit add -A; treat full-repo gate runs as unreliable when other agents are active and lean on targeted proof commands instead." —.agents/learnings/2026-05-16-evolve-trace-shared-tree.md(disk-truth survives only if peer agents don't clobber it)
How To Apply
- Read the ledger first. Every cycle's first action is
tail -n 50 .agents/evolve/cycle-history.jsonl(or theproductionLoopReaderadapter). Recover state from there, not from prior turns' messages. - Append, don't overwrite. Each cycle appends one JSONL line. Never rewrite earlier cycles. The ledger is the audit trail.
- Bead-driven work selection.
bd readyis the queue. Beads live in Dolt; the conversation never owns work scheduling. - Falsify aspirational rules. Any rule in
SKILL.mdthat depends on the agent following it (vs. a harness gate enforcing it) will be violated within 4-6 cycles. Wire automation or accept the rule is guidance only. - Treat "complete" claims with suspicion. When a cycle says "all surfaces wired," the next CI run often finds one more. Add a per-cycle drift sweep instead of trusting prior claims.
- Protect disk-truth in shared trees. See
../../swarm/references/shared-checkout-discipline.md
— disk-truth only survives if peer agents don't clobber it via
git add -Aor destructive recovery.
Implementing References (Already In /evolve)
The axiom is the principle. Each reference below is one mechanism that keeps disk-truth working:
| Reference | Role |
|---|---|
| cycle-history.md | JSONL format, recovery protocol, kill switch |
| autonomous-execution.md | ScheduleWakeup self-perpetuation pattern |
| context-budget.md | CONTEXT_BUDGET_EXHAUSTED as a third stop reason |
| convergence-mechanics.md | Read-path mechanisms (prior-failure injection, healing-first classifier) |
| scout-mode.md | Scout-cycle as a first-class disk-truth-only result type |
| gate-hygiene.md | Pre-gate source-surface detection + structural gate-output parsing |
| metronome-gate.md | Cross-cycle detector blocking same-mode-repeated failure |
| pre-flight-schema-check.md | Cheap field-fit check before architectural migration |
See Also
skills/rpi/references/orchestrator-compression-anti-pattern.md— when the orchestrator skips phases by inlining sub-skill work, no flywheel artifact lands (same disk-truth principle, applied to /rpi).skills/swarm/references/shared-checkout-discipline.md— disk-truth only survives if peer agents don't clobber it.