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.

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

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