Flight Route DSL — Notes (inline notes)

# Flight Route DSL — Notes (inline notes)

A **note** is a light-yellow inline note pinned to a route **stage**. Unlike
the external interaction / agreement / Navigation entities that point *into* a
route from their own frontmatter, a note is authored **inside the route
document it annotates**, in a doc-level `notes:` section. It is the **first
inline annotation surface** — the note and the stage it annotates live in the
same file.

Notes are for the *conversation around the route* — a facilitation note, an
open question about a stage. They follow the established **marker + shared
drawer** pattern: a compact light-yellow marker at the anchored stage, its full
text in the shared drawer, never a readable note square painted on the canvas.

> **This page documents the route delta only. It POINTS TO the shared
> [locator grammar](../locator-grammar.md) — it does not restate it.** The
> note's `locator:` is the **inline (position-only) form** defined there
> (§2 — no `[[file]]` head, resolved against the same document). The route adds
> exactly one segment kind: **`stage:`**.

## The `notes:` section

`notes:` is a **doc-level** key holding a **list** of note entries. Each entry
is a `{ locator, text, resolved? }` object:

```dwsd-flightroute
title: Delivery Route
for: feature
bands:
  - name: Coordination
    fl: 2
  - name: Delivery
    fl: 1
path:
  - epic @ Coordination --> story @ Delivery
notes:
  - on: "stage:epic @ Coordination::before"
    text: "Hand-off here is where things stall — watch it."
  - on: "stage:story @ Delivery::in"
    text: "Agreed to cap WIP at this stage."
    resolved: true
```

| Field | Required | Format | Meaning |
|-------|----------|--------|---------|
| `locator` | yes | inline (position-only) locator | Which stage on **this** route the note pins — a `stage:` segment + optional `::before` / `::in` / `::after` (bare = `::in`). **No `[[file]]` head** (D-02). |
| `text` | yes | string (inline markdown-lite) | The note content. The drawer renders a **safe, non-nesting** `**bold**` / `*italic*` / `` `code` `` subset (parsed to `<strong>`/`<em>`/`<code>` — never raw HTML). Links (`[[wikilink]]` / `[text](url)`) are **not** rendered in a note: a note row is already navigable to its locator, and note text is untrusted (G5). |
| `resolved` | no | boolean (default `false`) | The open/resolved lifecycle flag (see below). |
| `author` | no | string | **Optional, drawer-only** (D-04). Git blame is the authorship record — `author:` is a convenience label shown in the drawer, never required. |

An empty `text` is preserved; an absent or malformed `notes:` value degrades
to *no notes* rather than throwing — the rest of the route still renders (the
shared *"never blank, never break"* contract).

## The route locator — stage-only (v1)

A route note pins to a **stage** only, via the `stage:` segment:

- **`stage:` segment.** A stage is identified by its `(itemType, band)` pair,
  spelled **`itemType @ Band`** with a single space each side of the `@` — the
  same author form used in `path:` edges. So `stage:epic @ Coordination` names
  the `epic` stage in the `Coordination` band. The name before the `@` is the
  stage's token, or for a wikilink stage (`"[[Epic]] @ Coordination"`) its **link
  target**: `stage:Epic @ Coordination`. The match is exact within the route and
  the locator never nests `[[…]]`. The old lowercase spelling of a stage that
  became a wikilink (`stage:epic @ Coordination`) still resolves for one release and
  gets a `route.stage-name-spelling` warning.
- **before / in / after.** The trailing `::before` / `::in` / `::after` selects
  where, relative to the stage, the marker sits; **bare = `::in`**.

**Stage-only in v1.** A non-stage route position (a band, a trigger, a `⊙`
marker, an edge) has **no locator segment yet** — anchoring a note there is
**v2**, following the NAV-05 line (it needs a `parseLocator` grammar extension
across the shared spine). A non-stage or whitespace-drifted locator simply
resolves to no stage → it becomes an *orphan* (see below), never a blank preview.
See the [locator grammar](../locator-grammar.md#the-stage-route-segment-landed-phase-26)
for the full `stage:` reference.

## The `.` document-root note (whole route)

A note can anchor to the **whole route** instead of a single stage by using the
document-root locator `.`:

```dwsd-flightroute
title: Delivery Route
for: feature
bands:
  - name: Coordination
    fl: 2
  - name: Delivery
    fl: 1
path:
  - epic @ Coordination --> story @ Delivery
notes:
  - on: "."
    text: "Whole-route retro note — revisit the hand-offs."
```

`on: "."` resolves to **document scope** (an empty path), so the note is not
pinned to any stage — it renders as **one marker in the route header**, to the
**left of the doc-tag chips**. When two or more `.` doc-notes exist, they
**collapse to a single header marker with a count badge** — the same rule every
anchor follows: two or more notes on ONE anchor always collapse to one marker
showing how many. A leading `.` on a longer path
(`./stage:epic @ Coordination`) is a path *from* the document root and is
**equivalent to the bare path** (`stage:epic @ Coordination`) — see the
[locator grammar](../locator-grammar.md#3-typed-path-segments).

## Open / resolved lifecycle (D-10)

A note is **open** by default. Setting `resolved: true` marks it done — and the
**marker itself changes** (departing from the ODR `status`, which stayed
drawer-only):

- **On the canvas** — a resolved note **fades / desaturates** (lower opacity,
  muted yellow) at its stage, so open notes stand out.
- **In the drawer** — resolved notes group under a dedicated **"Resolved"**
  subsection, separated from the still-open notes.

The lifecycle state lives **where the entry is authored** — right on the inline
`notes:` entry.

## Orphan behavior — never silently dropped (D-11)

When a note's `locator:` no longer resolves (the stage was renamed, its band
changed, a whitespace drift in `itemType @ Band`), the note is **not** silently
lost — the deliberate departure from the route's usual degrade-to-no-marker:
*a reviewer's note is data, not decoration.* An orphaned note is surfaced
**both** ways:

1. **In the drawer** — it drops into a dedicated **"Orphaned notes"** tray inside
   the Notes bucket, with its **text preserved**.
2. **At the source** — an **authoring diagnostic** (a squiggle) is raised on the
   offending `notes:` entry.

Belt-and-suspenders: the preview reader *and* the author both see an orphan.

## The "Notes" drawer bucket (D-13)

Notes render into their **own** top-level, **side-agnostic** drawer bucket
labeled **"Notes"** (single type = own bucket, the ODR precedent). One stage
has one drawer across its before / in / after markers. The drawer a click on the
stage box opens lists the stage's notes after its other groups, so clicking the
box and then the note marker of the same stage closes the drawer (same stage, same
drawer). The "Orphaned notes" tray
is a subsection **within** the Notes bucket. The marker is styled with a
**light-yellow note anmutung** on both the pill and the drawer entries.

> The exact marker shade, glyph, and DV-3 treatment are locked by Thomas at the
> EDH walk (D-09) — this page deliberately hard-codes **no** hex value that could
> drift from the anchor registry.

## Worked example

A route with one open note before a stage and one resolved note in another:

```dwsd-flightroute
title: Referenced Route
for: feature
bands:
  - name: Coordination
    fl: 2
  - name: Operational
    fl: 1
path:
  - epic @ Coordination --> story @ Operational
notes:
  - on: "stage:epic @ Coordination::before"
    text: "Kickoff alignment still **open** — schedule it."
  - on: "stage:story @ Operational::in"
    text: "Flow policy agreed: pull only on green."
    resolved: true
    author: "Thomas"
```

- The first note renders a light-yellow marker **before** the
  `epic @ Coordination` stage, open.
- The second renders a **faded** marker **in** the `story @ Operational` stage
  and appears in the drawer's **"Resolved"** subsection.
- If `story @ Operational` were renamed, the second note would move to the
  **"Orphaned notes"** tray (text preserved) and raise a diagnostic on its entry.

## See also

- [Locator grammar](../locator-grammar.md) — the authoritative locator reference;
  the inline (position-only) form is §2, the `stage:` segment its own section.
- [Route anchors](./anchors.md) — the external interaction / agreement / pin
  stage surface (the outside-in direction) this inline surface complements.
- [Path & bands](./path-and-bands.md) — stage identity (`itemType @ Band`).
- [Board notes](../board/notes.md) · [Topology notes](../topology/notes.md)
  — the same `notes:` surface on the other two DSLs.