initial: pi-setup workspace with skill + extension plan

2026-06-10 17:30:43 +08:00
commit 49e581247b
158 changed files with 28777 additions and 0 deletions
@@ -0,0 +1,98 @@
+# 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.