Files
settled-reach/governance
jpmschweitzerandClaude Opus 5 3a640f91f7 docs(governance): Q-124 — Typer costs the cheap option down, and moves the target
Jeroen raised Typer as the Python-CLI option. Costing it changed what the
question is actually about.

The repo is already most of the way there: pyproject.toml exists, `make
setup-venv` already does `pip install -e ".[dev]"`, and 22 tooling files
already use argparse. What is missing is a single line — there is no
[project.scripts] entry at all, so no console entrypoint exists. This is
consolidation, not authorship, and it resolves the largest friction (per-script
permission prompts) for one allowlist entry.

But the framework is the second decision, not the first. A [project.scripts]
entrypoint lands in .venv/bin/, which is on PATH only when the venv is
activated — and agents and git hooks never activate it. That is the same split
VENV_PY already papers over in the Makefile, and precisely the failure recorded
for tea: an absolute path breaks the Bash(tea *) rule and prompts every time,
fixed only by a bare name on PATH. So the deliverable is "one bare command
reliably on PATH" (uv tool / pipx into ~/.local/bin, or a symlink), and a Typer
app behind an absolute venv path would solve nothing.

Two honest costs recorded against it: Typer and Click are further venv
dependencies, so it does not help the venv friction at all; and a single
entrypoint importing every subcommand eagerly would pay all 123 modules'
import cost on every invocation, four times per push. Lazy subcommand
registration is therefore mandatory rather than an optimisation, and must be
measured before and after.

Net: this looks like the answer for the check/gate family and the day-to-day
scripts, and it leaves the numpy/scipy/PIL planet-gen path alone — the part a
Rust port would have had to prove numerical equivalence for. T-1246 updated to
start here.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-20 02:00:39 +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