9dbb8f0bcb
Task nodes carry wait_kind (external | human | both | unqualified, null unless wait): the hub field wins, otherwise derived from needs_human and dependency edges (task-level depends_on, or a workplan dependency row whose target the task cites). Workplan nodes carry blocked_kind (human | external | none, null unless blocked). Task-level depends_on becomes a task -> workplan/task depends_on edge; depends_on edges carry edge_kind commitment (cyan #0891b2), human gates are marked on the node (humanGate, rose #be123c). A needs_human=true query / "Needs human" toggle / --needs-human flag keeps only blocked_kind=human workplans and their human-wait tasks; the parameter survives in the shareable URL and mode switch like include_residuals. Fabric stays a read of State Hub. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Assistant: claude-code Assistant-Model: sonnet Assistant-Process: 237582@bnt-lap001 Assistant-Session: f2b3d9f1-8fb9-4b9c-bc2b-837ec5dfc826
82 lines
3.7 KiB
Markdown
82 lines
3.7 KiB
Markdown
# 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.
|