docs(decisions): restructure into pql governance DQR tree
Phase 1 of the pql migration. Moves the flat decisions/*.md layout into
governance/{decisions,questions,rejected}/<domain>.md — the tree pql's
`decisions sync` parses natively (record type from subdir, domain from
filename stem). Proven against pql 1.6.2: sync reports 357 records
(237 D / 108 Q / 12 R), 1057 refs, broken: 0; validate ok.
- 6 D-domain files -> governance/decisions/ (git renames)
- 5 questions-<domain>.md -> governance/questions/<domain>.md (prefix dropped)
- rejected.md split by domain -> governance/rejected/{architecture(R-001..010),
economics(R-011),perception(R-012)}.md
- decisions/README.md + questions.md index folded into governance/README.md;
pql's `decisions sync` now auto-maintains the record index appended below
the hand-written domain guidance (no more manual ID-list table upkeep).
- .pql/config.yaml: canonical vault config (tracked, not ignored).
Link rewrites are token-preserving: only the relative `foo.md` path portion
changes (e.g. `rejected.md#r-011` -> `../rejected/economics.md#r-011`); every
`[D-NNN]` bracket text and `#anchor` stays byte-identical, so pql's reference
extraction is unaffected. The one-shot transform is committed at
tooling/pql-migrate/restructure_decisions.py for provenance.
Codebase path references to decisions/ (CLAUDE.md, rules, skills, docs) are
updated in a follow-up commit.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,43 @@
|
||||
# Rejected Alternatives — Architecture
|
||||
|
||||
Rejected proposals in the **architecture** domain, rationale preserved for the audit trail.
|
||||
|
||||
### R-001: Stellaris mod
|
||||
- **Rejected:** 2026-02-08
|
||||
- **Reason:** Character system too shallow, multi-empire assumption conflicts with the Settled Reach's single-civilization focus, wormhole-as-infrastructure not achievable within Stellaris modding. Team Leader's experience with Star Trek: New Horizons confirmed that even well-suited IPs struggle with character connection in Stellaris.
|
||||
|
||||
### R-002: CK3 total conversion
|
||||
- **Rejected:** 2026-02-08
|
||||
- **Reason:** Would require building a space map from scratch within CK3's framework - essentially building a game inside a game. The map system fundamentally doesn't support the complexity needed.
|
||||
|
||||
### R-003: Other existing games (Distant Worlds 2, GalCiv IV, Sins of a Solar Empire II, Victoria 3)
|
||||
- **Rejected:** 2026-02-08
|
||||
- **Reason:** Each captures at most 40% of what's needed. Smaller modding communities, less mature tools, and none solve the core CK3+Stellaris hybrid requirement.
|
||||
|
||||
### R-004: Pure Bevy (Rust) — no Godot
|
||||
- **Rejected:** 2026-02-09
|
||||
- **Reason:** No visual editor (level design is code-only). UI framework in flux. API breaks significantly between versions. For a solo developer who needs visual tools for hand-crafted buildings ([D-014](../decisions/scope.md#d-014-v01-map-specification)), Godot's editor is a massive productivity advantage. Bevy's ECS is used — just not its renderer.
|
||||
|
||||
### R-005: Pure Godot (GDScript or C#)
|
||||
- **Rejected:** 2026-02-09
|
||||
- **Reason:** Scene tree paradigm fights ECS-style simulation. Perception queries ([D-017](../decisions/perception.md#d-017-perception-modes-as-character-build-system)) and information boundaries ([D-010](../decisions/architecture.md#d-010-multiplayer-ready-architectural-baseline)) map naturally to ECS component queries, not scene tree traversal. Multi-core scaling for expanded content impossible in GDScript. Kept as kill-switch fallback if Rust architecture exceeds time budget.
|
||||
|
||||
### R-006: Godot + Rust via GDExtension
|
||||
- **Rejected:** 2026-02-09
|
||||
- **Reason:** gdext is pre-1.0 with breaking API changes. Godot version upgrades break GDExtension ABI. Thread safety at FFI boundary is CRITICAL risk (`Gd<T>` is `!Send`/`!Sync`). Couples Rust and Godot learning curves. Subprocess/IPC achieves the same architecture without the FFI risk surface, and maps directly to [D-010](../decisions/architecture.md#d-010-multiplayer-ready-architectural-baseline) client-server. See `docs/architecture/risk-godot-rust-bridge.md` for full analysis.
|
||||
|
||||
### R-007: Godot + C++ via GDExtension
|
||||
- **Rejected:** 2026-02-09
|
||||
- **Reason:** More mature bindings than gdext, but trades Rust's safety guarantees for C++ memory unsafety. No advantage over subprocess/IPC approach. Developer not experienced in C++.
|
||||
|
||||
### R-008: Fyrox (pure Rust engine)
|
||||
- **Rejected:** 2026-02-09
|
||||
- **Reason:** Single maintainer. ~1/50th of Godot's community. Less documentation, fewer tutorials, weaker AI training data for Claude Code. Single-maintainer risk unacceptable for multi-year project.
|
||||
|
||||
### R-009: Custom framework (Rust + raylib/macroquad)
|
||||
- **Rejected:** 2026-02-09
|
||||
- **Reason:** Maximum control but you build everything — tilemap rendering, camera, UI, audio, input, asset pipeline. Months before testing a mechanic. The game's hard problems are simulation, not rendering — don't reinvent the rendering wheel.
|
||||
|
||||
### R-010: protobuf for client-server serialization
|
||||
- **Rejected:** 2026-02-09
|
||||
- **Reason:** Schema evolution across independent deployments is a problem we don't have (one developer, client and server ship together). Poor GDScript support. Rigid schema fights dynamic HUD composition driven by perception modes ([D-017](../decisions/perception.md#d-017-perception-modes-as-character-build-system)). MessagePack's schema-optional nature fits better.
|
||||
@@ -0,0 +1,12 @@
|
||||
# Rejected Alternatives — Economics
|
||||
|
||||
Rejected proposals in the **economics** domain, rationale preserved for the audit trail.
|
||||
|
||||
### R-011: Single currency for Phase 2 economics
|
||||
- **Rejected:** 2026-04-05
|
||||
- **Proposed by:** Burnelli-Sheldon (economist), Sprint 32 Workshop #796 Round 1
|
||||
- **Proposal:** Use a single currency for the Phase 2 economics simulation to reduce model complexity; exchange-rate mechanics could be added in a later phase.
|
||||
- **Reason:** Three currencies create structural economic bloc tension as an emergent property of initialization, requiring no event generation. The Tractus/Mark divide maps directly to the canonical Assembly vs. Compact political divide. Deferring to a later phase would require retrofitting political geography into a running simulation. Complexity cost low; design value high.
|
||||
- **Raised by:** Lead directive overruling the recommendation.
|
||||
- **Cross-reference:** [D-171 (economics.md)](../decisions/economics.md#d-171-three-currency-system)
|
||||
- **Note:** Canonical location is `rejected.md`. Two duplicate copies in `economics.md` were removed 2026-06-06 (id-collision cleanup).
|
||||
@@ -0,0 +1,8 @@
|
||||
# Rejected Alternatives — Perception
|
||||
|
||||
Rejected proposals in the **perception** domain, rationale preserved for the audit trail.
|
||||
|
||||
### R-012: Overheard NPC conversation system (D-078) — scrapped
|
||||
- **Rejected:** 2026-04-10
|
||||
- **Reason:** The entire NPC ambient interaction model (overheard conversations, room grammar, zone-type NPC population, behavior engine for physical spaces) is scrapped. These systems were designed speculatively before a walkable environment exists. The NPC interaction model will be designed and built from scratch after Phase 5 (world generation at tile level) is complete. All content authored against these systems (overheard.ron, zone-type conversation pools) is orphaned. Related content pattern note in content.md and D-078 in perception.md are superseded.
|
||||
- **Cross-reference:** D-078 (perception.md), content pattern note (content.md #664)
|
||||
Reference in New Issue
Block a user