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,55 @@
+# Oscillation Detection
+
+## What Is Oscillation?
+
+A goal **oscillates** when it alternates between passing and failing across
+evolve cycles. Typically this means the fix for the goal causes a side-effect
+that breaks something else, which gets reverted, which re-exposes the original
+failure — creating a loop.
+
+Example from cycle-history.jsonl:
+```
+cycle 5:  goal-X → improved
+cycle 8:  goal-X → fail
+cycle 12: goal-X → improved
+cycle 15: goal-X → fail
+```
+
+## Detection
+
+Count **improved→fail transitions** for the same `target` in
+`.agents/evolve/cycle-history.jsonl`:
+
+```bash
+# Count oscillations for a given goal — reads via BC3 LoopReaderPort
+# (soc-y5vh.4 wrapper) instead of inline JSONL slurp.
+scripts/evolve-read-cycle-history.sh recent 0 \
+  | jq -r "select(.target==\"$GOAL_ID\") | .result" \
+  | awk 'prev=="improved" && $0=="fail" {count++} {prev=$0} END {print count+0}'
+```
+
+## Threshold
+
+**3 oscillations** (improved→fail transitions) within a single session
+triggers quarantine. The goal is skipped in Step 3 selection.
+
+## Effect
+
+- Quarantined goals are skipped during work selection (Step 3)
+- Skipping a quarantined goal counts as idle (no actionable work found)
+- The quarantine is session-scoped — a new session resets the count
+- Quarantine events are logged in cycle-history.jsonl with `"result": "quarantined"`
+
+## Recovery
+
+1. Human identifies the root cause (usually a conflict between two goals)
+2. Fix the underlying issue manually
+3. Start a new evolve session (quarantine resets)
+4. Or: remove the quarantine by deleting the goal from the skip list
+
+## Why Not Just Increase the Skip Threshold?
+
+The 3-consecutive-regression skip in Step 3 only catches monotonic failure.
+Oscillation is worse — it burns cycles alternating between "fixed" and "broken"
+without the stagnation detector ever triggering (because the goal intermittently
+passes). The oscillation detector catches this pattern explicitly.