DWSD.md

Flight Route DSL — Anchors (route refs)

An Interaction or an Agreement can anchor to a route position — a slot before, in, or after a stage — the same way it anchors to a board position. The direction is outside-in: the route file declares nothing; an external entity points into the route from its own frontmatter, and the route renders a marker at that stage. This page documents the route-specific delta only — the stage locator and its markers. The locator string family itself lives in one place for all three DSLs.

This page POINTS TO the shared locator grammar — it does not restate it. Route refs use the same locator grammar that spans topology, board, and route. The head forms, the ::before / ::in / ::after position qualifier, the value-polymorphic interaction-of: / agreement-of: keys, the body-table container convention, and the graceful-degradation contract are all defined there. Read that page for the grammar; read this one for what route adds to it.

Route refs, in brief

An interaction or agreement note addresses a route stage via its entity frontmatter — the same interaction-of: / agreement-of: keys the board surface uses (no new keys). The value is a locator whose path drills to a stage:

---
type: interaction
title: Epic Kickoff
interaction-of: "[[Referenced Route]]/stage:epic @ Coordination::before"
---

When it resolves, the route renders a type-specific marker at that stage — an interaction marker for type: interaction (a meeting is an interaction), a policy marker for type: agreement — exactly as the board anchor surface does. Clicking the stage box or any of its markers opens the one shared drawer listing the stage’s Flight Item Type first and then every entity anchored to that stage, with the same UX as the board drawer. Because the drawer is side-agnostic, one stage has one drawer across its before / in / after markers, and a click on the box and a click on a marker of the same stage open the same drawer (a second click on either closes it). The inner zones keep their own actions: the pills, the change pill, the bound-board pill, the note marker and the stage label of a wikilink do not additionally open the box drawer. A stage with nothing anchored opens with the Flight Item Type row alone.

The route delta — the stage: segment

Route refs add exactly one new locator segment kind: stage:. Everything else is the shared grammar. The route-specific specifics:

  • stage: segment. A route position is addressed with a stage: path segment, e.g. stage:epic @ Coordination. The four board segment kinds (col: / lane: / group: / split:) address a board; stage: addresses a route.
  • itemType @ Band naming. A stage’s identity is the (itemType, band) pair, spelled itemType @ Band with a single space each side of the @ — the same author form used in path: edges (see Path & bands). So stage:epic @ Coordination names the epic stage in the Coordination band. A whitespace drift produces no marker (the key simply never matches — graceful). For a stage written as a wikilink ("[[Epic]] @ Coordination") the name is its link target: stage:Epic @ Coordination. The old lowercase spelling still anchors it for one release; the editor shows a anchor.route-stage-spelling warning on the line that writes it.
  • before / in / after side. The trailing ::before / ::in / ::after qualifier selects where, relative to the stage, the marker sits; bare = ::in. This is the shared position qualifier — see the locator grammar.
  • Multi-route disambiguation mirrors the board’s #boardId slot: in a Markdown file hosting several route fences, [[file]]#Route Name/stage:epic @ Coordination selects a route by name; the bare [[file]]/stage:epic @ Coordination form also resolves for the common one-route-per-file case.

Navigation pins — stage-only in v1

A route stage can also be anchored by one of the four in-flux change entities — a signal, insight, driver, or proposal (see the vendored in-flux types reference for the full type model, and the change category page for where they sit in the chain). “Navigation pin” is the name of the data (RoutePin) and of the old glyph, kept because it is what the code calls it; the category is change. These are pins, not markers: all pins of one stage (whatever sides their locators name) show up as ONE change pill, a quiet capsule in the stage box’s own paint centered on the stage’s top edge at the right, left of the stage note marker, distinct from the interaction/agreement stage markers (on a stage with a pill, the in markers sit at the left of the top edge, so the two never overlap). It has a level indicator of four small dots (signal, insight, driver, proposal), filled up to the highest stage that has an entry and faint above it, and the entry count; it has no type colors. Hovering it shows the card “Change story here · n entries”; hiding the Change conversation layer removes it, live. See Where the pins render.

  • Stage anchoring uses the same stage: locator. A signal / insight anchors a stage via its observes: field. A driver / proposal is not placed on a route stage by observes (format 1.3): it names its domain with for-domain: and shows on that domain’s box in the structure views; its dot in a route stage’s pill stays empty for now. The value of observes: drills to a stage exactly like the interaction/agreement locator:

    ---
    type: signal
    observes: "[[Daily Replenishment Flow]]/stage:order @ Shops::before"
    ---

  • Stage-only in v1. A route Navigation pin anchors to a stage only. A non-stage route anchor (band-level or route-level, no stage: segment) is v2 — it renders no pin and degrades gracefully (the shared never blank contract), never blanking the preview.

  • The four categories share ONE drawer super-group. In the shared, side-agnostic drawer, a click on the pill opens the stage drawer, where the four pin categories fold under a single contiguous “Change conversation” band in stage order (each a per-type sub-row with a (count) badge), ADD-ALONGSIDE the flat interaction/agreement rows. The band folds into a long pill, and hovering a row fades the rows outside its derived-from net; the drawer has no action that opens a Change Trail.

Mandates on a stage

A mandate can hang at a route stage too: a Mandate of cell on a holder’s file, or mandate-of: on a type: mandate file, takes the same stage: locator as interaction-of: and agreement-of:. The stage shows a mandate marker with a key glyph, in Terracotta (stroke #C9956B), at the side the locator names. Several holders at one stage group into one pill with their count. The shared drawer names each holder and shows the mandate text beside a key glyph, and the Mandates layer of the filter menu hides the markers. A row without a Mandate of locator draws nothing. See Mandates. The color and the own layer are the current defaults, not settled.

Graceful degradation — a warning, never a blank

An unresolvable anchor (a missing route file, a stage the route never declares, a whitespace-drifted stage name) simply renders no marker and degrades to a warning — it never blanks the preview. The rest of the route renders normally; the cost of a stale anchor is one missing marker, nothing more. This is the shared “show as much as possible, never blank, never break” contract — see the locator grammar’s graceful-degradation section. A container entity (a meeting) can anchor N route positions at once via its body table — one row per stage — exactly as it does for boards.

See also

  • The locator grammar — the single, authoritative locator reference (head forms, position qualifier, container tables, the value-polymorphic keys). Route refs are the stage: extension of it.
  • Path & bands — stage identity (itemType @ Band) and the bands: a stage lives in.
  • Examples — worked routes, including the refs fixture a companion entity anchors to.

Like what you see? → Start — build your own org folder in ~2 min

anchors.md
# Flight Route DSL — Anchors (route refs)


An **Interaction** or an **Agreement** can anchor to a **route position** — a
slot *before*, *in*, or *after* a **stage** — the same way it anchors to a board
position. The direction is **outside-in**: the route file declares nothing; an
external entity points *into* the route from its own frontmatter, and the route
renders a marker at that stage. This page documents the **route-specific delta**
only — the stage locator and its markers. The locator string family itself lives
in **one** place for all three DSLs.


> **This page POINTS TO the shared locator grammar — it does not restate it.**
> Route refs use the **same** [locator grammar](../locator-grammar.md) that
> spans topology, board, **and** route. The head forms, the `::before` / `::in` /
> `::after` position qualifier, the value-polymorphic `interaction-of:` /
> `agreement-of:` keys, the body-table container convention, and the
> graceful-degradation contract are all defined there. Read that page for the
> grammar; read this one for what route adds to it.


## Route refs, in brief


An interaction or agreement note addresses a route stage via its **entity
frontmatter** — the **same** `interaction-of:` / `agreement-of:` keys the board
surface uses (no new keys). The value is a locator whose path drills to a stage:


```yaml
---
type: interaction
title: Epic Kickoff
interaction-of: "[[Referenced Route]]/stage:epic @ Coordination::before"
---
```


When it resolves, the route renders a **type-specific marker** at that stage — an
interaction marker for `type: interaction` (a meeting *is* an interaction), a
policy marker for `type: agreement` — exactly as the board anchor surface does.
Clicking the stage box or any of its markers opens the **one shared drawer**
listing the stage's Flight Item Type first and then every entity anchored to that
stage, with the same UX as the board drawer. Because the drawer is
**side-agnostic**, one stage has **one drawer** across its before / in / after
markers, and a click on the box and a click on a marker of the same stage open the
same drawer (a second click on either closes it). The inner zones keep their own
actions: the pills, the change pill, the bound-board pill, the note marker and
the stage label of a wikilink do not additionally open the box drawer. A stage with
nothing anchored opens with the Flight Item Type row alone.


## The route delta — the `stage:` segment


Route refs add exactly **one** new locator segment kind: **`stage:`**. Everything
else is the shared grammar. The route-specific specifics:


- **`stage:` segment.** A route position is addressed with a `stage:` path
  segment, e.g. `stage:epic @ Coordination`. The four board segment kinds
  (`col:` / `lane:` / `group:` / `split:`) address a board; `stage:` addresses a
  route.
- **`itemType @ Band` naming.** A stage's identity is the `(itemType, band)`
  pair, spelled **`itemType @ Band`** with a single space each side of the `@` —
  the same author form used in `path:` edges (see
  [Path & bands](./path-and-bands.md)). So `stage:epic @ Coordination` names the
  `epic` stage in the `Coordination` band. A whitespace drift produces no marker
  (the key simply never matches — graceful). For a stage written as a wikilink
  (`"[[Epic]] @ Coordination"`) the name is its **link target**: `stage:Epic @ Coordination`.
  The old lowercase spelling still anchors it for one release; the editor shows a
  `anchor.route-stage-spelling` warning on the line that writes it.
- **before / in / after side.** The trailing `::before` / `::in` / `::after`
  qualifier selects where, relative to the stage, the marker sits; **bare =
  `::in`**. This is the shared position qualifier — see
  [the locator grammar](../locator-grammar.md#4-position-qualifier).
- **Multi-route disambiguation** mirrors the board's `#boardId` slot: in a
  Markdown file hosting several route fences,
  `[[file]]#Route Name/stage:epic @ Coordination` selects a route by name; the
  bare `[[file]]/stage:epic @ Coordination` form also resolves for the common
  one-route-per-file case.


## Navigation pins — stage-only in v1


A route stage can also be anchored by one of the four **in-flux change entities** — a
`signal`, `insight`, `driver`, or `proposal` (see the vendored
[in-flux types reference](../change/in-flux.md) for the full type model, and the
[change category page](../change/README.md) for where they sit in the chain).
"Navigation pin" is the name of the data (`RoutePin`) and of the old glyph, kept because
it is what the code calls it; the *category* is `change`. These are **pins**, not
markers: all pins of one stage (whatever sides their locators name) show up as ONE
**change pill**, a quiet capsule in the stage box's own paint centered on the stage's top edge at the right,
left of the stage note marker, distinct from the interaction/agreement stage markers (on a
stage with a pill, the `in` markers sit at the left of the top edge, so the two never overlap). It has a
level indicator of four small dots (signal, insight, driver, proposal), filled up to the
highest stage that has an entry and faint above it, and the entry count; it has no type colors. Hovering
it shows the card "Change story here · n entries"; hiding the Change conversation layer
removes it, live. See [Where the pins render](../change/in-flux.md#where-the-pins-render).


- **Stage anchoring uses the same `stage:` locator.** A `signal` / `insight` anchors a stage via
  its `observes:` field. A `driver` / `proposal` is not placed on a route stage by `observes`
  (format 1.3): it names its domain with `for-domain:` and shows on that domain's box in the structure
  views; its dot in a route stage's pill stays empty for now. The value of `observes:` drills to a
  stage exactly like the interaction/agreement locator:


  ```yaml
  ---
  type: signal
  observes: "[[Daily Replenishment Flow]]/stage:order @ Shops::before"
  ---
  ```


- **Stage-only in v1.** A route Navigation pin anchors to a **stage** only. A non-stage
  route anchor (band-level or route-level, no `stage:` segment) is **v2** — it renders
  **no pin** and degrades gracefully (the shared *never blank* contract), never blanking
  the preview.
- **The four categories share ONE drawer super-group.** In the shared, side-agnostic
  drawer, a click on the pill opens the stage drawer, where the four pin categories fold
  under a single contiguous **"Change conversation"** band in stage order (each a
  per-type sub-row with a `(count)` badge), ADD-ALONGSIDE the flat interaction/agreement
  rows. The band folds into a long pill, and hovering a row fades the rows outside its
  `derived-from` net; the drawer has no action that opens a Change Trail.


## Mandates on a stage


A mandate can hang at a route stage too: a `Mandate of` cell on a holder's file, or `mandate-of:` on a
`type: mandate` file, takes the same `stage:` locator as `interaction-of:` and `agreement-of:`. The stage shows a
**mandate marker** with a key glyph, in Terracotta (stroke `#C9956B`), at the side the locator names. Several
holders at one stage group into one pill with their count. The shared drawer names each **holder** and shows the
mandate text beside a key glyph, and the **Mandates** layer of the filter menu hides
the markers. A row without a `Mandate of` locator draws nothing. See [Mandates](../mandates.md). The color and the own layer
are the current defaults, not settled.


## Graceful degradation — a warning, never a blank


An **unresolvable** anchor (a missing route file, a stage the route never
declares, a whitespace-drifted stage name) simply renders **no marker** and
degrades to a **`warning`** — it **never blanks the preview**. The rest of the
route renders normally; the cost of a stale anchor is one missing marker, nothing
more. This is the shared *"show as much as possible, never blank, never break"*
contract — see
[the locator grammar's graceful-degradation section](../locator-grammar.md#6-graceful-degradation).
A container entity (a meeting) can anchor **N** route positions at once via its
body table — one row per stage — exactly as it does for boards.


## See also


- [The locator grammar](../locator-grammar.md) — the single, authoritative
  locator reference (head forms, position qualifier, container tables, the
  value-polymorphic keys). Route refs are the `stage:` extension of it.
- [Path & bands](./path-and-bands.md) — stage identity (`itemType @ Band`) and
  the `bands:` a stage lives in.
- [Examples](./examples.md) — worked routes, including the `refs` fixture a
  companion entity anchors to.