Specifications#
These are geovista’s design specifications. Each is a living document,
maintained alongside the code it describes rather than archived behind it, so
read it as current. Where a specification and the code disagree, the
specification is what gets corrected, and the disagreement is worth reporting
as a defect in it.
The repository cites them by section. You will meet typing spec §3.2 in
pyproject.toml and docs spec §3.1 in conf.py, and each names a
section on one of the pages below. The prefix names the document, and it is
load-bearing: typing spec §3.2 and docs spec §3.2 are unrelated sections
of different documents. Wherever the documentation renders a citation in prose, in
a page, a specification or the API reference, it is a link to the section it names.
Citation |
Document |
Status |
|---|---|---|
|
✅ complete · 💡 1 |
|
|
✅ complete · 💡 1 |
|
|
🚧 1 of 14 rows · 💡 1 |
|
└─ |
🚧 3 of 6 rows · 💡 4 |
|
└─ |
🚧 2 of 5 rows |
|
└─ |
📋 not started · 💡 4 |
|
└─ |
🚧 2 of 3 rows |
|
|
🚧 7 of 8 rows · 💡 2 |
|
└─ |
✅ complete |
|
└─ |
✅ complete |
|
└─ |
✅ complete |
|
└─ |
✅ complete |
|
└─ |
🚧 2 of 3 rows |
|
|
🚧 2 of 5 rows · 💡 2 |
|
|
✅ complete |
|
|
🚧 9 of 10 rows · 💡 4 |
|
|
✅ complete |
The Status column sums each specification’s roadmap: 📋 not started, 🚧 how many of its rows have landed, or ✅ complete, with any 💡 candidates counted beside it. The build writes it, as docs spec §3.8 sets out.
A specification that extends another sits beneath it, and the specifications of a family are listed root first, each child under its parent and siblings in the order of their prefixes. Every specification names its family in its own header banner: its Lineage, from the root of its family down to itself, and its Children, the specifications that directly extend it. docs spec §3.7 sets out how a new specification takes its place in the table, and in the banners of its family.
Note
The implementation plans derived from these specifications are tracked in the repository under docs/src/developer/plans, but deliberately not published here. A plan records what was intended before implementation and is not updated afterwards.
Open Work#
The diagram below shows the work still to do across every roadmap: each row that has not landed, beside the landed rows it waits on or lands with. A green row is ready to start. It has not started, every row that it, or a row it lands with, waits on has landed, and no row it lands with is in progress or a candidate. Each box shows its row’s number, gives the opening words of its scope when the pointer rests on it, and links to its row. The build draws the diagram from the same reading of the orderings that the conventions test checks, so it is never out of date. diagram spec §4.5 sets out what it holds, and diagram spec §4.3 what ready means.
---
config:
theme: default
darkMode: false
themeVariables:
fontSize: 12px
flowchart:
useMaxWidth: false
padding: 6
nodeSpacing: 25
rankSpacing: 35
---
flowchart LR
subgraph docs_spec["docs spec"]
docs_spec_4_row_5["5"]
docs_spec_4_row_9["9"]
docs_spec_4_row_10["10"]
end
subgraph typing_spec["typing spec"]
typing_spec_4_row_8["8"]
typing_spec_4_row_9["9"]
typing_spec_4_row_10["10"]
typing_spec_4_row_11["11"]
typing_spec_4_row_12["12"]
end
subgraph crs_spec["crs spec"]
crs_spec_10_row_1["1"]
crs_spec_10_row_2["2"]
crs_spec_10_row_3["3"]
crs_spec_10_row_4["4"]
crs_spec_10_row_5["5"]
crs_spec_10_row_6["6"]
crs_spec_10_row_7["7"]
crs_spec_10_row_8["8"]
crs_spec_10_row_9["9"]
crs_spec_10_row_10["10"]
crs_spec_10_row_11["11"]
crs_spec_10_row_12["12"]
crs_spec_10_row_13["13"]
crs_spec_10_row_14["14"]
crs_spec_10_row_15["15"]
end
subgraph checks_spec["checks spec"]
checks_spec_4_row_2["2"]
end
subgraph globe_spec["globe spec"]
globe_spec_9_row_3["3"]
globe_spec_9_row_4["4"]
globe_spec_9_row_5["5"]
globe_spec_9_row_6["6"]
globe_spec_9_row_7["7"]
globe_spec_9_row_8["8"]
globe_spec_9_row_9["9"]
globe_spec_9_row_10["10"]
end
subgraph scene_spec["scene spec"]
scene_spec_9_row_3["3"]
end
subgraph heights_spec["heights spec"]
heights_spec_9_row_3["3"]
heights_spec_9_row_4["4"]
heights_spec_9_row_5["5"]
end
subgraph bench_spec["bench spec"]
bench_spec_9_row_4["4"]
end
subgraph layers_spec["layers spec"]
layers_spec_9_row_1["1"]
layers_spec_9_row_2["2"]
layers_spec_9_row_3["3"]
layers_spec_9_row_4["4"]
layers_spec_9_row_5["5"]
layers_spec_9_row_6["6"]
layers_spec_9_row_7["7"]
layers_spec_9_row_8["8"]
end
subgraph floors_spec["floors spec"]
floors_spec_9_row_1["1"]
floors_spec_9_row_2["2"]
floors_spec_9_row_3["3"]
floors_spec_9_row_4["4"]
floors_spec_9_row_5["5"]
floors_spec_9_row_6["6"]
floors_spec_9_row_7["7"]
end
subgraph diagram_spec["diagram spec"]
diagram_spec_9_row_1["1"]
diagram_spec_9_row_3["3"]
end
crs_spec_10_row_2 <==> globe_spec_9_row_5
crs_spec_10_row_1 --> crs_spec_10_row_3
crs_spec_10_row_3 --> crs_spec_10_row_4
crs_spec_10_row_4 --> crs_spec_10_row_5
crs_spec_10_row_4 --> crs_spec_10_row_6
crs_spec_10_row_4 --> crs_spec_10_row_7
crs_spec_10_row_4 --> crs_spec_10_row_8
crs_spec_10_row_4 --> crs_spec_10_row_9
crs_spec_10_row_4 --> crs_spec_10_row_10
crs_spec_10_row_4 --> crs_spec_10_row_11
crs_spec_10_row_4 --> crs_spec_10_row_12
crs_spec_10_row_4 --> crs_spec_10_row_13
crs_spec_10_row_6 --> crs_spec_10_row_14
crs_spec_10_row_7 --> crs_spec_10_row_14
crs_spec_10_row_8 --> crs_spec_10_row_14
crs_spec_10_row_9 --> crs_spec_10_row_14
crs_spec_10_row_10 --> crs_spec_10_row_14
crs_spec_10_row_11 --> crs_spec_10_row_14
globe_spec_9_row_3 --> globe_spec_9_row_4
globe_spec_9_row_4 <==> layers_spec_9_row_4
globe_spec_9_row_4 --> globe_spec_9_row_5
globe_spec_9_row_5 --> scene_spec_9_row_3
globe_spec_9_row_3 -.-> heights_spec_9_row_3
heights_spec_9_row_4 --> globe_spec_9_row_5
heights_spec_9_row_5 <==> layers_spec_9_row_2
layers_spec_9_row_1 --> layers_spec_9_row_2
layers_spec_9_row_2 --> layers_spec_9_row_3
layers_spec_9_row_3 --> layers_spec_9_row_4
floors_spec_9_row_1 --> floors_spec_9_row_2
floors_spec_9_row_2 --> floors_spec_9_row_3
floors_spec_9_row_3 --> floors_spec_9_row_4
floors_spec_9_row_1 --> floors_spec_9_row_5
diagram_spec_9_row_1 --> diagram_spec_9_row_3
classDef gv_landed fill:#eeeeee,stroke:#bbbbbb,color:#666666
classDef gv_progress fill:#ffe8a3,stroke:#c99a00,color:#000000
classDef gv_todo fill:#ffffff,stroke:#555555,color:#000000
classDef gv_candidate fill:#ffffff,stroke:#999999,stroke-dasharray:4 3,color:#555555
classDef gv_ready fill:#d9f2d9,stroke:#2e8b2e,stroke-width:3px,color:#000000
classDef gv_landed_small fill:#eeeeee,stroke:#bbbbbb,color:#666666,font-size:11px
classDef gv_progress_small fill:#ffe8a3,stroke:#c99a00,color:#000000,font-size:11px
classDef gv_todo_small fill:#ffffff,stroke:#555555,color:#000000,font-size:11px
classDef gv_candidate_small fill:#ffffff,stroke:#999999,stroke-dasharray:4 3,color:#555555,font-size:11px
classDef gv_ready_small fill:#d9f2d9,stroke:#2e8b2e,stroke-width:3px,color:#000000,font-size:11px
class docs_spec_4_row_5 gv_candidate
class docs_spec_4_row_9 gv_ready
class docs_spec_4_row_10 gv_candidate
class typing_spec_4_row_8 gv_candidate
class typing_spec_4_row_9 gv_candidate
class typing_spec_4_row_10 gv_candidate
class typing_spec_4_row_11 gv_candidate
class typing_spec_4_row_12 gv_ready
class crs_spec_10_row_1 gv_landed
class crs_spec_10_row_2 gv_todo
class crs_spec_10_row_3 gv_ready
class crs_spec_10_row_4 gv_todo
class crs_spec_10_row_5 gv_todo
class crs_spec_10_row_6 gv_todo
class crs_spec_10_row_7 gv_todo
class crs_spec_10_row_8 gv_todo
class crs_spec_10_row_9 gv_todo
class crs_spec_10_row_10 gv_todo
class crs_spec_10_row_11 gv_todo
class crs_spec_10_row_12 gv_todo
class crs_spec_10_row_13 gv_todo
class crs_spec_10_row_14 gv_todo
class crs_spec_10_row_15 gv_candidate
class checks_spec_4_row_2 gv_candidate
class globe_spec_9_row_3 gv_landed
class globe_spec_9_row_4 gv_todo
class globe_spec_9_row_5 gv_todo
class globe_spec_9_row_6 gv_candidate
class globe_spec_9_row_7 gv_candidate
class globe_spec_9_row_8 gv_candidate
class globe_spec_9_row_9 gv_candidate
class globe_spec_9_row_10 gv_ready
class scene_spec_9_row_3 gv_todo
class heights_spec_9_row_3 gv_ready
class heights_spec_9_row_4 gv_ready
class heights_spec_9_row_5 gv_todo
class bench_spec_9_row_4 gv_candidate
class layers_spec_9_row_1 gv_ready
class layers_spec_9_row_2 gv_todo
class layers_spec_9_row_3 gv_todo
class layers_spec_9_row_4 gv_todo
class layers_spec_9_row_5 gv_candidate
class layers_spec_9_row_6 gv_candidate
class layers_spec_9_row_7 gv_candidate
class layers_spec_9_row_8 gv_candidate
class floors_spec_9_row_1 gv_landed
class floors_spec_9_row_2 gv_landed
class floors_spec_9_row_3 gv_ready
class floors_spec_9_row_4 gv_todo
class floors_spec_9_row_5 gv_ready
class floors_spec_9_row_6 gv_candidate
class floors_spec_9_row_7 gv_candidate
class diagram_spec_9_row_1 gv_landed
class diagram_spec_9_row_3 gv_ready
click docs_spec_4_row_5 href "2026-10-06-published-specs-design.html#docs-spec-4-row-5" "5: GitHub reference roles and hardcoded-lin…"
click docs_spec_4_row_9 href "2026-10-06-published-specs-design.html#docs-spec-4-row-9" "9: Figures read as MyST reads them, for the…"
click docs_spec_4_row_10 href "2026-10-06-published-specs-design.html#docs-spec-4-row-10" "10: The specifications index for a large col…"
click typing_spec_4_row_8 href "2026-10-06-type-coverage-design.html#typing-spec-4-row-8" "8: The pyvista release carrying the fixes o…"
click typing_spec_4_row_9 href "2026-10-06-type-coverage-design.html#typing-spec-4-row-9" "9: The lazy_loader override withdrawn"
click typing_spec_4_row_10 href "2026-10-06-type-coverage-design.html#typing-spec-4-row-10" "10: The cast in Transform.from_tiff withdraw…"
click typing_spec_4_row_11 href "2026-10-06-type-coverage-design.html#typing-spec-4-row-11" "11: The override for the distributions that…"
click typing_spec_4_row_12 href "2026-10-06-type-coverage-design.html#typing-spec-4-row-12" "12: The trigger tests of rows 8 to 11 harden…"
click crs_spec_10_row_1 href "2026-10-23-globe-first-crs-design.html#crs-spec-10-row-1" "1: The coverage test of §6, recording today…"
click crs_spec_10_row_2 href "2026-10-23-globe-first-crs-design.html#crs-spec-10-row-2" "2: The globe model, units, heights and laye…"
click crs_spec_10_row_3 href "2026-10-23-globe-first-crs-design.html#crs-spec-10-row-3" "3: The cutting engine: rotate, clip, cut a…"
click crs_spec_10_row_4 href "2026-10-23-globe-first-crs-design.html#crs-spec-10-row-4" "4: The domain registry, and class 0 on the…"
click crs_spec_10_row_5 href "2026-10-23-globe-first-crs-design.html#crs-spec-10-row-5" "5: The CRS interface: geovista classes, dom…"
click crs_spec_10_row_6 href "2026-10-23-globe-first-crs-design.html#crs-spec-10-row-6" "6: Class 1, latitude limits"
click crs_spec_10_row_7 href "2026-10-23-globe-first-crs-design.html#crs-spec-10-row-7" "7: Class 2, caps"
click crs_spec_10_row_8 href "2026-10-23-globe-first-crs-design.html#crs-spec-10-row-8" "8: Class 3, bands"
click crs_spec_10_row_9 href "2026-10-23-globe-first-crs-design.html#crs-spec-10-row-9" "9: Class 4, oblique aspects"
click crs_spec_10_row_10 href "2026-10-23-globe-first-crs-design.html#crs-spec-10-row-10" "10: Class 5, interrupted Goode Homolosine, b…"
click crs_spec_10_row_11 href "2026-10-23-globe-first-crs-design.html#crs-spec-10-row-11" "11: Class 6, Spilhaus"
click crs_spec_10_row_12 href "2026-10-23-globe-first-crs-design.html#crs-spec-10-row-12" "12: Cut once, map many"
click crs_spec_10_row_13 href "2026-10-23-globe-first-crs-design.html#crs-spec-10-row-13" "13: Display refinement, as an explicit opt-i…"
click crs_spec_10_row_14 href "2026-10-23-globe-first-crs-design.html#crs-spec-10-row-14" "14: Today's seam and transform path deleted,…"
click crs_spec_10_row_15 href "2026-10-23-globe-first-crs-design.html#crs-spec-10-row-15" "15: The regions of §9 item 1, as a design of…"
click checks_spec_4_row_2 href "2026-10-23-repository-checks-design.html#checks-spec-4-row-2" "2: Third-party tools: ruff, mypy type-ignor…"
click globe_spec_9_row_3 href "2026-10-26-globe-heights-layers-design.html#globe-spec-9-row-3" "3: Heights as data: height and depth, the v…"
click globe_spec_9_row_4 href "2026-10-26-globe-heights-layers-design.html#globe-spec-9-row-4" "4: Layers: the order, the base layer's lowe…"
click globe_spec_9_row_5 href "2026-10-26-globe-heights-layers-design.html#globe-spec-9-row-5" "5: Removing zlevel and zscale, migrating th…"
click globe_spec_9_row_6 href "2026-10-26-globe-heights-layers-design.html#globe-spec-9-row-6" "6: A vertical scale for the viewer"
click globe_spec_9_row_7 href "2026-10-26-globe-heights-layers-design.html#globe-spec-9-row-7" "7: Heights given for each cell"
click globe_spec_9_row_8 href "2026-10-26-globe-heights-layers-design.html#globe-spec-9-row-8" "8: Heights against another vertical datum"
click globe_spec_9_row_9 href "2026-10-26-globe-heights-layers-design.html#globe-spec-9-row-9" "9: A vertical mapping in bands, or as a fun…"
click globe_spec_9_row_10 href "2026-10-26-globe-heights-layers-design.html#globe-spec-9-row-10" "10: The render radius at the Earth's radius:…"
click scene_spec_9_row_3 href "2026-10-27-globe-scene-design.html#scene-spec-9-row-3" "3: The release after which a retired field…"
click heights_spec_9_row_3 href "2026-10-28-heights-as-data-design.html#heights-spec-9-row-3" "3: A scene whose globe can be replaced, reb…"
click heights_spec_9_row_4 href "2026-10-28-heights-as-data-design.html#heights-spec-9-row-4" "4: Heights from a raster band in Transform.…"
click heights_spec_9_row_5 href "2026-10-28-heights-as-data-design.html#heights-spec-9-row-5" "5: A surface below sea level seen past a ba…"
click bench_spec_9_row_4 href "2026-11-09-benchmarks-design.html#bench-spec-9-row-4" "4: Each benchmark's peak memory compared wi…"
click layers_spec_9_row_1 href "2026-11-12-layers-design.html#layers-spec-9-row-1" "1: Tiers: the built-in tiers, tier=, above=…"
click layers_spec_9_row_2 href "2026-11-12-layers-design.html#layers-spec-9-row-2" "2: The globe: the bias by rank, the base la…"
click layers_spec_9_row_3 href "2026-11-12-layers-design.html#layers-spec-9-row-3" "3: The lift, on the globe and on a map"
click layers_spec_9_row_4 href "2026-11-12-layers-design.html#layers-spec-9-row-4" "4: The web: the bias written into each .vtk…"
click layers_spec_9_row_5 href "2026-11-12-layers-design.html#layers-spec-9-row-5" "5: A clip on the web"
click layers_spec_9_row_6 href "2026-11-12-layers-design.html#layers-spec-9-row-6" "6: Data draped over terrain"
click layers_spec_9_row_7 href "2026-11-12-layers-design.html#layers-spec-9-row-7" "7: The interim bias of row 4 removed"
click layers_spec_9_row_8 href "2026-11-12-layers-design.html#layers-spec-9-row-8" "8: The view from below the surface"
click floors_spec_9_row_1 href "2026-11-15-dependency-floors-design.html#floors-spec-9-row-1" "1: The floors environment and the Python su…"
click floors_spec_9_row_2 href "2026-11-15-dependency-floors-design.html#floors-spec-9-row-2" "2: A floor on every pip requirement and the…"
click floors_spec_9_row_3 href "2026-11-15-dependency-floors-design.html#floors-spec-9-row-3" "3: The composite action and the pypi job of…"
click floors_spec_9_row_4 href "2026-11-15-dependency-floors-design.html#floors-spec-9-row-4" "4: The test-floors job of ci-wheels.yml (§4…"
click floors_spec_9_row_5 href "2026-11-15-dependency-floors-design.html#floors-spec-9-row-5" "5: The floors-docs environment (§4.1) and t…"
click floors_spec_9_row_6 href "2026-11-15-dependency-floors-design.html#floors-spec-9-row-6" "6: A report of each floor beside the versio…"
click floors_spec_9_row_7 href "2026-11-15-dependency-floors-design.html#floors-spec-9-row-7" "7: The browser tests at the docs floors (§4…"
click diagram_spec_9_row_1 href "2026-11-18-row-order-diagrams-design.html#diagram-spec-9-row-1" "1: One reading of the graph: the reading of…"
click diagram_spec_9_row_3 href "2026-11-18-row-order-diagrams-design.html#diagram-spec-9-row-3" "3: The report's diagrams, and the job that…"
Key
---
config:
theme: default
darkMode: false
themeVariables:
fontSize: 12px
flowchart:
useMaxWidth: false
padding: 6
nodeSpacing: 15
rankSpacing: 20
---
flowchart LR
subgraph key_states[" "]
direction TB
key_landed["landed"]
key_progress["in progress"]
key_todo["not started"]
key_candidate["candidate"]
key_ready["ready to start"]
key_landed ~~~ key_progress ~~~ key_todo ~~~ key_candidate ~~~ key_ready
end
subgraph key_relations[" "]
direction LR
key_after_1["1"] -->|"after"| key_after_2["2"]
key_before_1["1"] -->|"before"| key_before_2["2"]
key_with_1["1"] <==>|"with"| key_with_2["2"]
key_or_1["1"] -.->|"with or after"| key_or_2["2"]
end
key_states ~~~ key_relations
classDef gv_landed fill:#eeeeee,stroke:#bbbbbb,color:#666666
classDef gv_progress fill:#ffe8a3,stroke:#c99a00,color:#000000
classDef gv_todo fill:#ffffff,stroke:#555555,color:#000000
classDef gv_candidate fill:#ffffff,stroke:#999999,stroke-dasharray:4 3,color:#555555
classDef gv_ready fill:#d9f2d9,stroke:#2e8b2e,stroke-width:3px,color:#000000
classDef gv_landed_small fill:#eeeeee,stroke:#bbbbbb,color:#666666,font-size:11px
classDef gv_progress_small fill:#ffe8a3,stroke:#c99a00,color:#000000,font-size:11px
classDef gv_todo_small fill:#ffffff,stroke:#555555,color:#000000,font-size:11px
classDef gv_candidate_small fill:#ffffff,stroke:#999999,stroke-dasharray:4 3,color:#555555,font-size:11px
classDef gv_ready_small fill:#d9f2d9,stroke:#2e8b2e,stroke-width:3px,color:#000000,font-size:11px
style key_states fill:none,stroke:none
style key_relations fill:none,stroke:none
class key_landed gv_landed
class key_progress gv_progress
class key_todo gv_todo
class key_candidate gv_candidate
class key_ready gv_ready
class key_after_1,key_after_2,key_before_1,key_before_2,key_with_1,key_with_2,key_or_1,key_or_2 gv_todo
Statuses#
Every roadmap row and open item in a specification carries a status, and a
finished one names the work that finished it, as in
✅ landed (2026-10-06, {pull}`2565`).
docs spec §3.6 sets out the vocabulary, and what each
status must cite.
When you change a status, check it against GitHub before you push, giving the
number of your pull request so that a status may cite it while it is still
open, e.g., for pull request 1234:
$ pixi run -e test check-spec-status 1234
The check confirms that a landed row cites merged pull requests on its
date, and that a Resolved or Abandoned item cites work that exists. The
ci-spec-status.yml workflow runs it on every pull request that changes a
specification. Each night it also runs with drift, to report a status the
work has moved past, such as an Open item whose issue has closed.
Tip
Without a token, GitHub allows 60 requests an hour. Set GH_TOKEN to
raise the limit, e.g., GH_TOKEN="$(gh auth token)".
Decisions and Verification#
Each specification records what was agreed in its Decisions section, and shows in its Verification section whether each decision was delivered. Together they are its ledger, which ledger spec §3.2, §3.3, §3.4 set out.
Adding a decision. Append it to the end of the list, never between two others: a decision keeps its number for as long as the specification exists. Open it with its state and its provenance, then its title:
7. **🤝 Agreed** (2026-11-02, {user}`bjlittle`, {pull}`1234`) — **The title.**
Its reasoning.
In the same pull request, add its row to the Verification table, naming the
decision by its citation, as | §2 decision 7 | ⏳ pending | |. The build
links the citation to the decision. A bare 7 is refused, since it reads as
any row, item or decision that the Evidence column cites
(ledger spec §2 decision 17).
Citing a decision. Write heights spec §2 decision 3, or
§2 decision 3 inside the specification itself. One citation names one
decision, so two decisions take two citations. The build links each to the
decision.
Retiring a decision. A decision that no longer holds is retired, never
deleted. Change its state to 🗄️ Retired, with the retirement’s date, who
retired it and its pull request, then ; agreed and the original date and pull
request. Keep its text, and add a sentence saying why it was retired and what
replaced it, citing the replacement. Its row becomes 🗄️ retired. A correction
or a clarification that keeps a decision’s meaning is an edit, not a retirement.
Verifying a decision. When a test exercises the decision, cite the decision
in the test’s docstring or a comment, and make its row
✅ verified (date, {pull}`1234`), naming the test file in the Evidence column.
The conventions test checks that the file exists and cites the decision. On the
rendered page, each test file the Evidence column names links to the first line
in it that cites the decision, at the commit or the release tag the
documentation was built from (ledger spec §2 decision 18).
Signing off a decision. Where no test can honestly show a decision, a
reviewer signs it off. The row becomes
✍️ signed off (date, {user}`reviewer`, {pull}`1234`), and its Evidence says
what the reviewer checked. The reviewer named then adds the signed-off label
to the pull request. An agent never adds that label, since GitHub records the
account and not the person (ledger spec §2 decision 7). The pull request’s
checks fail until the reviewer named adds it, and pass once they do. A pull
request merged without it is reported each night, and the reviewer can still
add the label to the merged pull request.
The verification report. To see the whole ledger at once, run:
$ pixi run -e test verification-report
$ pixi run -e test verification-report heights
For every specification, or the one a prefix names, it shows the roadmap with each row’s status, then each decision with its state and every place in the repository that cites it, grouped as source, tests, documentation, specifications and plans, and last the open items, each with its state, the row that owes it and how often it has moved. It flags a verified row whose test no longer cites its decision, and a decision in force that nothing cites. It also flags an item on its last move, which must settle or graduate when its row lands, and an item owed by a row in progress, which that row’s pull request must answer. It is a view, never a check: it exits 0 whatever it finds (ledger spec §3.8, items spec §3.9).
Open Items#
A specification’s Open Items section tracks a gap found while delivering it: an input the design missed, or a decision a test only partly held. Each item has a state, where it was found, and an issue that tracks it, set out in items spec §3.1, §3.2, §3.3, §3.4. Every specification’s items are in that grammar.
Raising an item. Append it to the end of the Open Items section, in the
same pull request that raises its issue, labelled spec: open item:
7. **❓ Open** (🔎 2026-11-02, {pull}`1234` · 🎯 row N of §M ·
🎫 {issue}`1235`) — **The title.** Its reasoning.
An agent may add the spec: open item label itself: it records what the
issue is, not anyone’s judgement, unlike signed-off
(items spec §2 decision 11).
Citing an item or a row. Write typing spec §8 item 9 or
item 9 of typing spec §8, and §8 item 9 or item 9 of §8 inside the
specification itself. Cite a row the same way, as row 5 of §10, or across
specifications as row 5 of crs spec §10. The build links each to the item or row it names.
Owing it to a row. 🎯 names a row of the item’s own roadmap that has not landed, the row whose work the gap belongs to. A row may not land while an open or deferred item still names it: the pull request that lands it settles, moves or promotes every item it owes.
Moving it. A pull request that lands a row without settling an item it
owes moves it instead, appending ⬅️ with the row it leaves and its date and
pull request, and the item becomes ⏭️ Deferred:
7. **⏭️ Deferred** (🔎 2026-11-02, {pull}`1234` · 🎯 row N of §M ·
⬅️ row 5, 2026-12-01, {pull}`1240` · 🎫 {issue}`1235`) —
**The title.** Its reasoning.
An item may carry two ⬅️ and no more; at the third landing that owes it, it must settle or graduate (items spec §3.6).
Settling or promoting it at a landing. The pull request that lands a row
owing an item resolves it, abandons it, or graduates it to a row of its own,
at least a 💡 candidate:
7. **🏁 Resolved** (2026-11-02, {pull}`1250` · 🔎 2026-11-02,
{pull}`1234` · 🎫 {issue}`1235`) — **The title.** What was settled.
7. **🚫 Abandoned** (2026-11-02, {pull}`1250` · 🔎 2026-11-02,
{pull}`1234` · 🎫 {issue}`1235`) — **The title.** Why it was dropped.
7. **🎓 Graduated** (2026-11-02, {pull}`1250`, to row N of §M ·
🔎 2026-11-02, {pull}`1234` · 🎫 {issue}`1235`) — **The title.**
Resolving or abandoning closes the item’s issue, by a closing keyword in the pull request or by hand once it merges. Graduating carries the issue to the new row instead, which cites it, and the issue keeps its label until that row lands.
Ordering Roadmap Rows#
When a row depends on another, its Scope cell says so after the scope. Each
ordering opens with · 🔗, and a row may carry several:
| # | Scope | Status |
|---|---|---|
| 1 | Tiers on a map | 📋 not started |
| 2 | Tiers on the globe · 🔗 after row 1 | 📋 not started |
| 3 | The lift · 🔗 after row 2 · 🔗 with row 2 of heights spec §9 | 📋 not started |
An ordering states one of four relations, and names one row:
Relation |
The row lands |
|---|---|
|
in a later pull request than the row it names |
|
in an earlier pull request |
|
in the same pull request |
|
in the same pull request, or a later one |
A bare row 1 is a row of the same roadmap, and a row of another
specification is cited in full, as row 2 of layers spec §9. Write each
ordering once, on the row its reason belongs to: the row that waits, or the
earlier row for before. A with between two specifications goes on the
row whose work the other row does. A release takes before alone, as
· 🔗 before 0.6.
The reasons stay in the paragraph under the table, and the ordering never does: the conventions test refuses one written in prose, such as row 3 needs row 1, and points you at the cell.
The test also reads the orderings of every roadmap together, as one graph, and
refuses a cycle, such as row 2 after row 1 and row 1 after row 2, or a with
and a before between the same two rows; a 📋 not started row waiting on
a 💡 candidate, which may never land; and a status the order contradicts. A
row starts only once the rows it comes after have landed, and lands on their day
or later, in a pull request of its own, while two rows with each other land
in the same one.
A row with another lands in one pull request with it, and that pull request
answers the open items both rows owe. So for each row in progress, the
verification report lists any row it lands with that still owes open items, and
names those items.
order spec §4.1 sets out the form, order spec §4.5 what the test refuses, and
order spec §4.6 what the report shows.
Under each roadmap table, the build draws the roadmap’s rows and their
orderings as a diagram, with a key folded beneath it: a solid arrow for after and a
dotted one for with or after, each pointing from the row that lands first,
and a heavy one with two heads for with, whose rows land together. A before is drawn as the
after it is from the other row. The rows of other specifications that the
roadmap orders against are drawn small at its edge, in their own colours, so a
row this roadmap frees shows there as ready. Nothing is written for a diagram,
and a roadmap without orderings draws its rows alone. diagram spec §4.4 sets them
out.