railiance-fabric/docs/coordination-graph.md

Coordination graph (workplans and waits)

State Hub owns workplans. Fabric does not author them. This view projects open workplans and open tasks into the existing graph explorer so chokepoints are inspectable.

# JSON payload (residuals omitted by default)
railiance-fabric export --format coordination --state-hub http://127.0.0.1:8000

# Include flavor=residual
railiance-fabric export --format coordination --include-residuals --state-hub http://127.0.0.1:8000

# UI (local registry server)
make graph-explorer
# then open
# http://127.0.0.1:8765/ui/graph-explorer?mode=coordination
# optional: &include_residuals=true

Nodes

Open workplans (proposed|ready|active|blocked|backlog) and their open tasks (todo|progress|wait).

flavor: residual workplans and their tasks are omitted by default. Unspecified flavor stays visible. The word “residual” in a title is not a flavor. The explorer checkbox / include_residuals query includes them (parity with State Hub include_residuals).

Workplan nodes carry flavor / nodeClass (planning | implementation | refactoring | extension | residual | unspecified).

Edges (precedence)

1. Indexed depends_on (edgeSource: indexed, edgeType: depends_on) from State Hub workplan depends_on (and /state/deps when the list endpoint does not yet carry the field). These do not require a wait note.
2. Citation waits_on (edgeSource: citation) when a wait/human task cites another workplan id in its prose and no indexed depends_on already exists for that pair. Fallback for files not yet backfilled (CUST-WP-0072). Never the reverse: citations do not replace indexed edges.
3. belongs_to task → workplan.

Chokepoint size is in-degree of visible (by default: non-residual) workplan nodes from depends_on and remaining waits_on edges.

Solid blue = indexed depends_on. Dashed amber = citation waits_on.