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.

Qualified waits (CUST-WP-0074)

Open task nodes carry wait_kind (external | human | both | unqualified, null unless status: wait). The hub's wait_kind field wins when present; otherwise needs_human: true → human, a dependency edge (task-level depends_on, or a workplan dependency row whose target the task cites) → external, both → both, neither → unqualified. Workplan nodes carry blocked_kind (human when any wait task is a human gate, else external, else none; null unless status: blocked).

Task-level depends_on becomes a task → workplan/task depends_on edge (edgeSource: task). All depends_on edges carry edge_kind: commitment (cyan #0891b2); citation edges carry edge_kind: citation. Human gates have no edge target, so the marker is on the node: humanGate: true, rose #be123c (WAIT_KIND_COLORS in coordination_graph.py).

The Needs human checkbox / needs_human=true query (CLI --needs-human) keeps only blocked_kind: human workplans and their human-wait tasks — the operator's queue. It survives in the shareable URL like include_residuals.

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.