Files
settled-reach/governance
jpmschweitzerandClaude f5044926da docs(meta): D-261 — rivers are a stroke, not a scaled feature
A river is sub-pixel at almost every Atlas scale (a 100 m channel against
Global's ~17.6 km per screen pixel), so drawing it to scale draws nothing.
The line becomes a symbol whose job is legibility: a fixed 5 px screen-space
stroke, contiguous through the river's own cell centres, never drawn over
water, and culled when too small to read.

The cull threshold derives from the stroke rather than being stipulated. A
mark reads as a line at roughly 3x its own width, so the minimum is 15 px of
on-screen length — and the kilometre thresholds then fall out of each rung's
scale: 264 km at Global, 2.8 km at Region, 28 m at District. A level-of-detail
ladder with no hand-tuned constants, which self-corrects if the width changes.

Measured on the visible extent, not total river length: a course crossing the
window always spans it and passes, so only a course wholly inside the view and
small is culled. Correct at both ends of the ladder, and no new wire field.

Records a tension that had to be resolved rather than split. Jeroen proposed a
flat 100 km cutoff, then noted that 5x5 px still reads as a dot and asked for
15-20. Those are incompatible: the km threshold depends only on the pixel
length, so 100 km implies ~6 px, which is dot-shaped at a 5 px stroke.
Admitting 100 km rivers AND keeping them line-shaped needs a ~2 px stroke.
Thick lines mean fewer rivers; thin lines mean more. Ruled for the bold stroke.

Client-side, and provably so: the cull is measured in screen pixels, and the
display ratio is a client-side viewport-dependent parameter that never reaches
a wire request or cache key, so the server cannot know how many pixels a
course occupies. Water-clipping needs nothing new either — the per-cell
classification is already in the adopted canvas.

Built on the 2026-07-27 measurement in D-258's amendment: 375 courses present,
458 of 518,400 pixels different. The rivers were not failing to render, they
were correctly beneath notice; the defect was drawing specks instead of
drawing properly or not at all.

T-1237 implements. T-1238 restores size-varying width as polish, deliberately
deferred — noting width and cull are coupled, since a thinner stroke lowers
its own visibility threshold.

Co-Authored-By: Claude <noreply@anthropic.com>
2026-07-28 08:41:44 +02:00
..

Governance — Decisions, Questions, Rejected

Structured planning records for The Settled Reach. pql decisions sync parses these into .pql/pql.db; query them with pql decisions ….

Layout

Records live in three per-type subdirectories, split by domain:

governance/
  decisions/<domain>.md   # D-NNN — confirmed design decisions
  questions/<domain>.md    # Q-NNN — open questions (may resolve into a D or R)
  rejected/<domain>.md     # R-NNN — rejected alternatives (kept for the audit trail)

The parser infers record type from the parent subdirectory and domain from the filename stem. A ### D-NNN: Title (or Q-/R-) heading begins each record; - **Field:** value lines and inline [D-NNN](…#anchor) links carry the metadata and cross-references pql indexes.

Current domains: architecture, content, economics, perception, process, scope. Create a new <domain>.md in the relevant subdir when records land in a new domain.

Domain guide

When in doubt where a record belongs:

  • architecture — constrains how we build (engine, protocols, data structures, performance).
  • scope — defines what we build (game concept, feature scope, prototype shape).
  • perception — defines what the player observes or knows (camera, fog, LOS, audio).
  • content — defines narrative, NPCs, dialogue, setting, templates.
  • economics — the economics layer (currencies, commodities, corporations, simulation).
  • process — defines how the team works (workflow, commits, branches, reviews).

Cross-domain records live in one file with [D-NNN](../<subdir>/<domain>.md#…) links to the related domain.

Querying

pql decisions list                              # every record
pql decisions list --type confirmed --domain architecture
pql decisions show D-010 --with-tickets         # a record + its implementing tickets
pql decisions read D-238                         # full markdown body
pql decisions refs D-010                          # cross-references in/out
pql decisions coverage                            # decisions ↔ ticket coverage

Adding a record

  1. Claim an ID (no side effects): pql decisions claim D <domain> "title" (use Q for a question, R for a rejected alternative).
  2. Edit the appropriate file (decisions/<domain>.md, questions/<domain>.md, or rejected/<domain>.md). Follow the existing ### D-NNN: Title format.
  3. Commit. The pre-commit hook runs pql decisions validate (malformed-record gate) and stages the planning changelog.
  4. Update relevant agent briefings if needed.

When a question resolves, set its - **Status:** Resolved → [D-NNN](../decisions/<domain>.md#…) line in place — keep the Q-record for the audit trail rather than deleting it.

Maintained by Qatux.

Decisions

Open questions

Resolved questions

Rejected