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.

```bash
# 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`.