boundary-segmentation

name	boundary-segmentation
description	Explains how W2 Jaccard-Cosine Boundary Segmentation works, what events fire it, and how to interpret the cluster state in plugins/boundary-segmenter/state/boundary-clusters.json. Invoked when a developer asks "why did Sylph commit/branch here?" or "what's W2 doing?"
allowed-tools	Read

boundary-segmentation

What this is

Sylph's defining engine. Every PostToolUse(Edit|Write|MultiEdit) event flows into an online agglomerative clusterer. When the next event's distance to the active cluster exceeds threshold θ (default 0.55), a task boundary fires — and that triggers the downstream plugins to branch, commit, and eventually open a PR.

The distance function

Three components, weighted:

d(event, cluster) = α · (1 − jaccard(files))         α = 0.4  (file overlap)
                  + β · (1 − cosine(tokens))         β = 0.4  (content overlap)
                  + γ · tanh(idle_gap / τ)           γ = 0.2, τ = 300s

Weights and threshold live in shared/constants.sh (SYLPH_BOUNDARY_*). sylph-learning (W5) tunes them per-developer over time — the defaults are what a fresh install starts with.

How to read the state

plugins/boundary-segmenter/state/boundary-clusters.json contains:

• threshold, uncertainty_band, cfg (alpha/beta/gamma/tau)
• active: the currently-open cluster (opened_at, events[])
• closed_clusters: the last 20 finalized clusters

Each event in a cluster records files, vector (L2-normalized token weights), tool, timestamp. The vector shows what tokens the algorithm matched on — useful for debugging why two edits did or didn't cluster together.

When W2 upgrades to Crow V1

If Crow is installed and publishes crow.change.classified events on the mcp-event-bus, Sylph will substitute Crow V1's semantic diff embedding in place of the stdlib token vector. The API is the same; the accuracy improves.

When to invoke this skill

A developer asking:

• "Why did Sylph commit here?" → show the last closed cluster + distance.
• "Why didn't it commit yet?" → show the active cluster growing.
• "Can I tune this?" → point at SYLPH_BOUNDARY_* in shared/constants.sh and sylph-learning/state/learnings.json for per-dev overrides.