railiance-fabric/docs/coordination-graph.md

Coordination graph (workplans and waits)

Repository files own workplans; State Hub indexes them. The Fabric explorer does not edit 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.

Switching views

The mode selector switches between topology and coordination in the same page. Residual visibility refreshes the coordination payload and is retained in the shareable URL. A failed refresh leaves the prior graph visible and shows an error; an empty result can still be switched back to topology. Graph-specific rules, selection, and zone placement reset when replacing the dataset.

The registry route is available locally. Hosted acceptance remains blocked by RAIL-FAB-WP-0028's runtime, persistence, access, and deployment decisions; this UI change does not establish a production authority.