docs(constitution): a capability keys to the object class, not to the verb that first needed it - #323
Open
stellarfeline wants to merge 3 commits into
Open
docs(constitution): a capability keys to the object class, not to the verb that first needed it#323stellarfeline wants to merge 3 commits into
stellarfeline wants to merge 3 commits into
Conversation
…rb that first needed it `close-gate.sealed_hint` encodes "answer a player who presses this thing" — a property of anything right-clickable, nothing to do with closing a gate. Built onto the verb, it left the sealed shortcut door with no surface to consume, and the proposed fix was a second bespoke field. Owner ruling 2026-08-06: a second bespoke field is the defect, not the fix. A capability keys to the object class it acts on; the verb becomes one consumer. Generality is decided at the first site — the second costs a version bump, fences, and an adoption round per active campaign.
…ng is too narrow The shape that fools you: the mechanism exists, but it does not reach the objects it should. A trigger's interaction body is a point at a cell, not the clickable shape of the object, so the island boulder's own pattern authored on a shortcut door compiles clean and ships a box pressable only from the side the door opens from. That reads as a missing feature, and the fix adds a fourth mechanism — which is what the planner proposed in this very PR.
Owner decision 2026-08-06: engine primitives are abstract, flexible and configurable, never bound to one campaign's design. A creator must be able to build any content with it. A primitive encodes a MECHANISM, never a design decision about what that mechanism is for; the genre we happen to be building is content, and content lives in campaigns. The capability-ownership rule becomes a corollary of that, and the three review shapes sit under it: keyed to the verb; a general mechanism privately re-implemented; a general mechanism whose binding is too narrow to reach the objects it should.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed at the design level
One bullet in
CLAUDE.md's Methodology, beside the no-hack rule. It names a defect class the repo has been paying for without a name for it.The live instance.
close-gateownssealed_hint— a field that encodes answering a player who presses this thing. That capability is a property of anything a player can right-click; it has nothing to do with closing a gate. Built as a property of the verb, it left the second object that needed it — the sealed shortcut door, which has no interaction body on the near side at all, so neither click does anything — with no surface to consume. The proposed fix was a second bespoke field onshortcuts[].Owner ruling, 2026-08-06: that is too narrow. What is wanted is a general capability — an author can attach a custom right-click hint to a scene object — not a field per use case. A second bespoke field is the defect repeating, not its repair.
The rule, so it is checkable in review. Before adding an authorable field to a verb: could an author want this on an object that has nothing to do with that verb? If yes, it keys to the object class and the verb becomes one consumer. The tell in a diff is a doc comment reading "X, mirroring Y", a hook on one variant of a sum type but not its siblings, or a default baked into a path a second path cannot reach.
Why it belongs beside the no-hack rule. Same layering failure, one axis over: no-hack is about which layer a capability lives at; this is about what it is keyed to inside that layer. And it is the DSL-surface form of the shape already paid for at the walker layer — hand-rolled walks enumerating 3 of 5 effect roots (#301/#302/#321), a defect of expressibility rather than of care.
Generality is decided at the first site. Retrofitting at the second costs a
dsl_versionbump, per-stage fences, and an adoption round on every active campaign.What CI proves
Nothing behavioural — this is text in the constitution. The docs job proves the file still parses for every consumer that reads it.
Not in this PR
The repo-wide audit of the class, and every lift it will recommend. Both were ordered in the same breath and are running separately; no surface is touched here.