张宗平
99 lines
5.1 KiB
Markdown
99 lines
5.1 KiB
Markdown
# 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>`), never
|
|
> `git 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
|
|
|
|
1. **Read the ledger first.** Every cycle's first action is
|
|
`tail -n 50 .agents/evolve/cycle-history.jsonl` (or the
|
|
`productionLoopReader` adapter). Recover state from there, not from prior
|
|
turns' messages.
|
|
2. **Append, don't overwrite.** Each cycle appends one JSONL line. Never
|
|
rewrite earlier cycles. The ledger is the audit trail.
|
|
3. **Bead-driven work selection.** `bd ready` is the queue. Beads live in
|
|
Dolt; the conversation never owns work scheduling.
|
|
4. **Falsify aspirational rules.** Any rule in `SKILL.md` that 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.
|
|
5. **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.
|
|
6. **Protect disk-truth in shared trees.** See
|
|
[../../swarm/references/shared-checkout-discipline.md](../../swarm/references/shared-checkout-discipline.md)
|
|
— disk-truth only survives if peer agents don't clobber it via
|
|
`git add -A` or 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](cycle-history.md) | JSONL format, recovery protocol, kill switch |
|
|
| [autonomous-execution.md](autonomous-execution.md) | ScheduleWakeup self-perpetuation pattern |
|
|
| [context-budget.md](context-budget.md) | `CONTEXT_BUDGET_EXHAUSTED` as a third stop reason |
|
|
| [convergence-mechanics.md](convergence-mechanics.md) | Read-path mechanisms (prior-failure injection, healing-first classifier) |
|
|
| [scout-mode.md](scout-mode.md) | Scout-cycle as a first-class disk-truth-only result type |
|
|
| [gate-hygiene.md](gate-hygiene.md) | Pre-gate source-surface detection + structural gate-output parsing |
|
|
| [metronome-gate.md](metronome-gate.md) | Cross-cycle detector blocking same-mode-repeated failure |
|
|
| [pre-flight-schema-check.md](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.
|