interphase

keep priority P2 effort S wave 2

What it does: Per code: a Clavain companion that adds lifecycle state management on top of the beads issue tracker via three sourced bash libraries plus three hooks. lib-phase.sh tracks an 8-state lifecycle (brainstorm→brainstorm-reviewed→strategized→planned→plan-reviewed→executing→shipping→done) on beads using bd set-state phase=X, with bead-ID inference and JSONL telemetry; pure observability, never blocks. lib-gates.sh validates phase transitions against an explicit transition graph, enforces priority-tiered gates (hard P0/P1=block, soft P2/P3=warn, none P4=skip) with opt-in CLAVAIN_GATE_FAIL_CLOSED strict mode, detects flux-drive review staleness (git-log-since vs review timestamp), does dual persistence (bead state + markdown Phase: headers), and writes a sideband bead payload to ~/.interband for interline’s statusline. lib-discovery.sh ranks open beads by a multi-factor score (priority+phase+recency−staleness), infers next actions from filesystem artifacts, detects parent-closed beads, runs deterministic ‘possibly already implemented’ heuristics (command-file/commit-grep/function-grep), finds orphan artifacts, and is claim-aware. Hooks: bead-autoclaim (auto-claim on bd update —claim/—status=in_progress with collision detection + 45min TTL), heartbeat (adaptive-throttle claim refresh), session-end-release (best-effort release).

Rationale: Mature, correct, and directly aligned with the strongest 2026 SOTA signal: ‘harness engineering as a discipline’ — anything that must happen every time (approval gates, phase advancement, claim lifecycle) should be a deterministic hook, not something the model is hoped to remember. interphase implements exactly that: deterministic phase gates with explicit transition graph, priority tiering, structured transient/permanent error classification, and fail-safe-by-default semantics (return 0 on dependency/error paths) with an opt-in fail-closed strict mode for high-risk transitions. It also embodies the verification-gate and human-in-the-loop-checkpoint patterns the frontier validates over fire-and-forget autonomy (review-staleness detection forces /flux-drive refresh before hard transitions). The claim/heartbeat/release machinery is a legitimate coordination/blast-radius primitive for the worktree-per-session multi-agent model this ecosystem already runs. It has bats + structural test coverage, a clean file-based sideband contract to interline (no direct coupling), and a thin static skill surface (one progressive-disclosure SKILL.md), which is the winning packaging model. Nothing here is a thin LLM wrapper; it is deterministic infrastructure. No modernize/deprecate signal.

SOTA gap: The F8 discovery scorer (score_bead) is a hand-tuned static weighting (priority 0-60, phase 0-30, recency 0-20, −10 staleness). The 2026 frontier on next-task selection/routing (Select-then-Solve embedding routers; RAG-MCP retrieval-augmented selection; MemRouter embedding-gated memory selection) has moved toward cheap sub-millisecond embedding gates that decide relevance/ranking without LLM calls. interphase ranks purely on metadata heuristics and never consults the embedding infra that already exists in-ecosystem (intersearch embedding_index/query). A semantic-relevance term — score the bead against the current session’s working context via an embedding gate — would make discovery context-aware rather than purely priority/recency-driven. This is the one frontier idea it lacks; it is an enhancement, not a defect.

Redundancy: Coordination overlap with interlock (file reservation + agent coordination via intermute MCP): interphase’s claimed_by/claimed_at + heartbeat-TTL + session-end-release is a parallel claim-lease lifecycle, but scoped to beads rather than files — complementary axes, not duplicative, though the TTL/release machinery is conceptually similar and worth keeping aligned. Discovery’s multi-factor scorer overlaps with internext (work prioritization + next-task tradeoff scoring) and partially with interject (which it consumes [interject] bead metadata from). Statusline state overlaps by contract with interline (intentional sideband, not redundancy). None rise to a merge candidate; the separation of concerns (bead-phase vs file-lock vs tradeoff-scoring) is defensible.

Actions:

Fix the beads-workflow SKILL.md hardcoded server path: it asserts the beads DB lives at /root/projects/Interverse/.beads/ and that bd must run from there. This is zklw-specific and misleads agents on Mac/worktree setups (e.g. elf-revel runs bd from per-session worktrees with a symlinked DB). Make the path guidance environment-relative or describe discovery rather than a fixed absolute path.
Add the deferred performance fix already flagged in-code: lib-discovery.sh has a TODO that phase_get is O(n) subprocess calls per bead — for >50 beads cache phase state in /tmp/clavain-phase-cache-${session_id}.json (the comment at the score loop). Low effort, removes a real scaling cliff in discovery_scan_beads.
Optional P3 modernization: add a semantic-relevance term to score_bead using intersearch embedding_query against current session context, gated behind availability (fail-open to today’s static score if embeddings unavailable). Driven by the Select-then-Solve / RAG-MCP / MemRouter embedding-gating trend.
Reconcile the claim-lease TTL constants (autoclaim uses 2700s/45min freshness; heartbeat default 15s; discovery uses 2700s) into one documented source of truth and confirm alignment with interlock’s reservation TTLs to avoid two coordination layers disagreeing on staleness.