Repository navigation
Port loop/ + crew/ + spec-queue/ to a plugin (P1.5), with claim fencing #128
Description
Proposal
Parent: Phase 1a item P1.5 (3.9k LOC; rewrite expected — loop.ts is 105 KB and its
hook points are gone in opencode 2). Depends on plugin-repo-layout and slots after
port-peer-plugin (delegation ledger precedes loop completion messaging).
Why
The autonomous loop is the platform's engine: it claims ready work, runs it in isolated
worktrees, and hands off on completion (charter §8.5–8.8). In the fork this lives in a
105 KB loop.ts hooking upstream internals that opencode 2 has removed — so this port
is a rebuild against the plugin surfaces, guided by the existing spec suite
(crew-loop, swarm-coordinator, loop-done-handoff, escalate-before-idle,
loop-spec-queue, fix-queue-branch-awareness) and the landed behavior:
loop-completion-contract, the --auto flag and its Phase 5–6 tests
(52516a57eb, d5cf928208, 7b31baa46f, c509c05cb4, 70d6c7c41a, 1ecc4db407,
a97d9b7ec4), and crew claims as shared files (813393f21a).
What Changes
- Rebuild the loop engine as the
skein-loop-crewplugin package: spec-queue-driven
work claims, execution, and completion handoff, keeping the landed behaviors above
observable (drained vs found-nothing distinction, aggregated report, fenced auto
runs, claim/release for cancellation). - Add claim fencing (charter §8.5): lease token, expiry, heartbeat, and a monotonic
ownership generation so an expired worker cannot continue publishing stale work.
Before reassignment, reconcile actual process/branch state — a stale heartbeat does
not prove execution is stopped. - Register the skein worktree implementation via
worktree.transform; worktree naming
stays linked to work item + execution ID; no auto-delete of unmerged work (§8.6). - Completion handoff (§8.7) drives the next assignment from the workflow engine's own
turn (record outcome → validate evidence → unlock downstream → assign ready work),
never from an unbounded prompt loop (§23). - Role/capacity routing decisions stay llama-skein-tenant and policy-driven
(per-model-placement-controlscarries). The scheduling loop performs no LLM calls
(§23).
Non-goals
- No global control-plane duties (charter §9.1 —
skein-control-planeowns cross-repo). - No new work-source authority: spec-queue remains the only claimable-work source until
the P1.9/P1.5 ready-work contract lands.
Risks
- Rewrite scope is the known schedule risk (K2); ship the engine behind the landed
behavior tests, growing coverage rather than porting the 105 KB blob verbatim. - Claims data must survive plugin reloads — the shared-file claims store carries over;
fencing tokens must be introduced atomically with adoption of the shared store.
Impact
skein-loop-crew plugin: spec queue + claims + fencing + handoff + worktree transform.
This is where crew autonomy becomes durable; unblocks autonomous-swarm-epic work and
the soak phase.
Tasks
Depends on plugin-repo-layout (isolation + repo name) and port-peer-plugin (the
ledger) for completion messaging.
- 1.1 Design the
skein-loop-crewplugin structure against the landed behaviors:
write design.md mapping each landed behavior/name to its plugin-boundary
implementation, and mark which of the landed behaviors change shape in the
rebuild (the drained/aggregation/fencing outcomes do not). - 1.2 Rebuild spec-queue claiming over the shared-file claims store; the auto runs
are fenced by QueueDenyRules as before; drain vs found-nothing distinction kept. - 1.3 Add claim fencing: lease token + expiry + heartbeat + ownership generation;
acquire in an atomic compare-and-swap over the claims store. - 1.4 Reconcile-before-reassign: on expired heartbeat, inspect owning process
availability + branch/worktree state first; tests cover both "recovered" and
"still-alive" outcomes. - 1.5 Register the skein worktree set via
worktree.transform; naming links work
item + execution ID; abandoned-worktree preservation rule enforced (§8.6). - 1.6 Implement handoff-on-completion: record outcome, validate evidence, unlock
downstream, assign next ready work; driver test: crew of 1 lead + 2 workers over
a repo with ≥2 ready changes all assigning/rotating without human nudges
(charter §8.9, Scenario C partial). - 1.7 Keep the loop's cancellation semantics (claim/release lifecycle) and verify
no nudge storms by a cap + reason-aware retry (§16.2/§16.4). - 1.8 Before any further fork-side loop work: coordinate with
reconcile-openspec-queue-v2(its claims/cancellation/handoff tasks merge here
or get superseded — recorded there, not guessed). - 1.9 Disposition of fork-side
loop//crew//spec-queue/recorded for P1.7.
Activity