Files
settled-reach/governance
jpmschweitzer da15261276 fix(client): PR #192 review round — per-rung legend, Region coalescing + clamp boundary tests, halving-loop honesty
All Hoshe/Araminta findings addressed (Tyre approved outright), none
retracted — plus a Dudley stop-and-flag discovery that improved on the
asked-for fix:

- Legend 100x lie (Araminta, blocking): subtitle computed via
  spacing_for_rung() and refreshed at all three _held_granularity_v2
  write sites. Region test asserts 204.800 km/cell; the District
  direction needed a stale-header-aware helper — a District-only test
  spuriously passes against the old literal by coincidence.
- Region coalescing coverage (Hoshe 1): both directions tested
  (Region-vs-District separate slots; Region-vs-Region coalesces).
- Clamp boundary tests + dangling citations (Hoshe 2): writing the
  requested halving-loop-fires test surfaced that the loop is PROVABLY
  UNREACHABLE at current constants (per-axis clamp forecloses it —
  brute-forced independently on both server and client sides). Ruling:
  the loop stays as defensive code; the test became a property sweep
  pinning both the wire-cap invariant and the loop's no-op status (a
  future constant change breaks it loudly); doc comments on both sides
  drop the load-bearing framing and state the truth; the old client
  mirror test that claimed the loop fires (passing on the per-axis
  clamp alone) is replaced the same way. Client citations now name the
  real server tests verbatim.
- Governance (Tyre): D-226 amendment note — progressive cross-rung
  refinement EXTENDS T-1124 §4 (not supersedes); legacy u32 field
  scheduled for retirement (T-1159).

Server: 1818 lib tests green, clippy/fmt clean. Client: zoom_ladder
48/48, window_request 26/26, viewer 74/74; gdlint clean. Every fix
revert-verified.
2026-07-22 17:24:07 +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