initial: pi-setup workspace with skill + extension plan
This commit is contained in:
张宗平
@@ -0,0 +1,128 @@
|
||||
# Parallel Goal Execution
|
||||
|
||||
## Architecture
|
||||
|
||||
When `--parallel` is enabled, `/evolve` uses `/swarm` to execute multiple independent
|
||||
goal improvements concurrently instead of fixing one goal per cycle.
|
||||
|
||||
```
|
||||
/evolve --parallel (Fitness Loop)
|
||||
│
|
||||
├─ Step 2: Measure ALL goals
|
||||
│
|
||||
├─ Step 3: Select top N independent failing goals (max_parallel, default 3)
|
||||
│ └─ select_parallel_goals: heuristic independence via check-script overlap
|
||||
│
|
||||
├─ Step 4: Parallel execution via /swarm
|
||||
│ ├─ TaskCreate for each selected goal
|
||||
│ ├─ Artifact isolation: .agents/evolve/parallel-rpi/{goal.id}/
|
||||
│ ├─ Git isolation: /swarm --worktrees (each worker in /tmp/evolve-{goal.id})
|
||||
│ └─ /swarm spawns N fresh-context workers, each runs full /rpi cycle:
|
||||
│ └─ research → plan → pre-mortem → crank → vibe → post-mortem
|
||||
│
|
||||
├─ Step 5: Single regression gate (re-measure ALL goals after wave)
|
||||
│ ├─ If ANY goal regressed → revert ENTIRE parallel wave
|
||||
│ └─ If clean → log cycle with goal_ids array
|
||||
│
|
||||
└─ Step 6-7: Log, loop (same as sequential)
|
||||
```
|
||||
|
||||
## The Fractal Pattern
|
||||
|
||||
Swarm is the universal coordination primitive at every level:
|
||||
|
||||
```
|
||||
LEVEL 0: /evolve --parallel
|
||||
└─ /swarm (parallel goal improvements) ← NEW: swarm at evolve level
|
||||
└─ LEVEL 1: /rpi (per-goal lifecycle)
|
||||
└─ research → plan → crank → vibe → post-mortem
|
||||
└─ LEVEL 2: /crank (epic execution)
|
||||
└─ /swarm (parallel issue implementation) ← existing: swarm at crank level
|
||||
└─ LEVEL 3: workers (atomic tasks)
|
||||
```
|
||||
|
||||
Each level creates fresh context for the next (Ralph Wiggum pattern).
|
||||
The pattern is always: **one leader + N fresh-context workers + validation + cleanup**.
|
||||
|
||||
## Goal Independence Detection
|
||||
|
||||
`select_parallel_goals` uses a heuristic check:
|
||||
|
||||
1. Start with highest-weight failing goal
|
||||
2. For each remaining eligible goal (weight-sorted):
|
||||
- Compare check commands for shared scripts/paths
|
||||
- If independent: add to selection (up to max_parallel)
|
||||
- If overlapping: skip (handled in next cycle)
|
||||
|
||||
**This is a heuristic, not a guarantee.** Goals don't declare which files their
|
||||
improvements will modify — only which scripts verify them. Two goals with different
|
||||
check scripts may still modify overlapping files.
|
||||
|
||||
**The regression gate (Step 5) is the real safety net.** If parallel goals conflict,
|
||||
the regression check detects it and reverts the entire wave. This makes false
|
||||
negatives in independence detection safe (they just cost one wasted cycle).
|
||||
|
||||
## Artifact Isolation
|
||||
|
||||
Each parallel /rpi worker needs isolated artifact directories to prevent collision:
|
||||
|
||||
| Directory | Purpose | Isolation |
|
||||
|-----------|---------|-----------|
|
||||
| `.agents/evolve/parallel-rpi/{goal.id}/` | /rpi phase summaries, next-work | Per-goal subdirectory |
|
||||
| `.agents/evolve/parallel-results/{goal.id}.md` | Worker result summary | Per-goal file |
|
||||
| `/tmp/evolve-{goal.id}` | Git worktree | Per-goal worktree via /swarm |
|
||||
|
||||
Without isolation, N concurrent /rpi cycles would collide on `.agents/rpi/`
|
||||
(phase summaries, next-work.jsonl) and git index locks.
|
||||
|
||||
## Git Isolation
|
||||
|
||||
Parallel workers MUST use worktree isolation (via `/swarm --worktrees`):
|
||||
|
||||
- Each worker operates in `/tmp/evolve-{goal.id}` worktree
|
||||
- No git lock conflicts (each worktree has its own index)
|
||||
- Lead merges worktrees after all complete, before regression gate
|
||||
- On regression: revert all merged commits using `cycle_start_sha`
|
||||
|
||||
## Regression Handling
|
||||
|
||||
**Sequential mode:** Revert commits from one goal's /rpi cycle.
|
||||
|
||||
**Parallel mode:** Revert ALL commits from the entire parallel wave.
|
||||
The `cycle_start_sha` (captured before the wave) anchors the revert point.
|
||||
All N goal improvements are rolled back together — even goals that individually
|
||||
succeeded. This is by design: if goals interfere, we can't know which one
|
||||
caused the regression without testing each in isolation.
|
||||
|
||||
## Cycle History Schema
|
||||
|
||||
Sequential cycles use `target` (string). Parallel cycles use `goal_ids` (array) with `parallel: true`:
|
||||
|
||||
```jsonl
|
||||
{"cycle": 1, "target": "test-pass-rate", "result": "improved", "sha": "abc1234", ...}
|
||||
{"cycle": 2, "goal_ids": ["doc-coverage", "lint-clean"], "result": "improved", "sha": "def5678", "parallel": true, ...}
|
||||
```
|
||||
|
||||
Legacy entries may use `goal_id` instead of `target` and `commit_sha` instead of `sha`. Tools should handle both.
|
||||
|
||||
## Compounding
|
||||
|
||||
Each parallel /rpi worker runs its own /post-mortem, which feeds the knowledge
|
||||
flywheel independently. Learnings from all N parallel cycles compound into the
|
||||
flywheel, feeding the next /evolve cycle.
|
||||
|
||||
## When to Use
|
||||
|
||||
| Scenario | Mode |
|
||||
|----------|------|
|
||||
| 1-2 failing goals | Sequential (default) — parallelism overhead not worth it |
|
||||
| 3+ independent failing goals | `--parallel` — significant speedup |
|
||||
| Goals with overlapping files | Sequential — parallel would cause conflicts |
|
||||
| First run on new repo | Sequential — learn the codebase before parallelizing |
|
||||
|
||||
## Constraints
|
||||
|
||||
- Max 5 parallel goals per wave (`--max-parallel` cap)
|
||||
- Default 3 parallel goals (balance between speedup and resource usage)
|
||||
- Each /rpi worker needs a full context window — budget accordingly
|
||||
- Worktree isolation required (no shared-worktree parallel /rpi)
|
||||
Reference in New Issue
Block a user