hecks 1.3.0 → 1.4.0

data/lib/hecks/bluebook/dsl/rule_reference.rb

@@ -1,35 +1,37 @@
+require_relative "bootstrap_table"
+
 module Hecks
   module Bluebook
     module DSL
-      # THE THREE RESOLUTION PRIMITIVES the S10 given/invariant family's
+      # The three resolution primitives the S10 given/invariant family's
       # own "declared once, referenced by name" mechanism (ADR 0025)
       # reduces to, at every scope this language has grown one so far
       # (a command referencing its owner or a sibling piece's entity-wide
       # pool; an aggregate referencing another aggregate chapter-wide; a
       # value object referencing a sibling value object on the same
-      # aggregate) — extracted here, once, so the NEXT scope this family
+      # aggregate) — extracted here, once, so the next scope this family
       # widens to (there will be one — see docs/resolution-rules/
       # chapter-given.md's own "Known limitations" for two already named)
       # reuses one of these three shapes instead of a fourth hand-written
       # near-duplicate resolver.
       #
-      # NOT ONE UNIFIED ALGORITHM — a real design question this file
-      # answers directly: the THREE existing resolvers are not
-      # superficially different, they are STRUCTURALLY different (a
-      # multi-pool fallback CHAIN; ONE pool keyed by declaring OWNER,
-      # needing disambiguation; a LIVE SCAN over already-built sibling
+      # **Not one unified algorithm** — a real design question this file
+      # answers directly: the three existing resolvers are not
+      # superficially different, they are structurally different (a
+      # multi-pool fallback chain; one pool keyed by declaring owner,
+      # needing disambiguation; a live scan over already-built sibling
       # objects with no separate pool at all) — forcing them into one
       # shape would be a real behavior change (see `#lookup`, below, for
       # which construct uses which), not the pure internal refactor this
-      # module is. `build_rule` is the one piece that WAS genuinely
+      # module is. `build_rule` is the one piece that was genuinely
       # identical across all 7 declaring methods (`given`×3,
       # `invariant`×3, `ensures`×1) before this file existed — extract
       # predicate source, refuse if extraction failed, build the struct.
       #
-      # `#lookup`/`#verify_resolves_via!` read WHICH construct uses which
+      # `#lookup`/`#verify_resolves_via!` read which construct uses which
       # primitive off the self-hosted grammar table itself
       # (`Keyword#resolves_via`, `syntax.bluebook`) — not a Ruby-only
-      # Hash cross-checked afterward (this file's OWN earlier shape, one
+      # Hash cross-checked afterward (this file's own earlier shape, one
       # round ago) — so a real domain's own boot, not just `bundle exec
       # rspec`, fails loudly the moment the table and this file's own
       # hand-written resolution methods disagree.
@@ -39,14 +41,14 @@ module Hecks
         # `struct_class` is `Given` or `Invariant` (both `Struct.new(
         # :description, :canonical, :predicate, keyword_init: true)` —
         # `Given` lives in command.rb, `Invariant` in value_object.rb).
-        # `owner_name`/`word` are ONLY for the refusal message's own
+        # `owner_name`/`word` are only for the refusal message's own
         # wording. `extraction_failure` is the tail of that same
-        # message, and stays a REQUIRED parameter rather than one
+        # message, and stays a required parameter rather than one
         # hardcoded string on purpose — `given` ("its source could not
         # be read, so no other runtime could ever evaluate it"),
         # `invariant` ("it would be a rule the IR cannot carry"), and
         # `ensures` ("a postcondition is carried as text, and this one
-        # has none") each already had their OWN exact wording before
+        # has none") each already had their own exact wording before
         # this method existed; unifying them into one generic sentence
         # would be a real (if small) behavior change this refactor is
         # not making.
@@ -64,9 +66,9 @@ module Hecks
           struct_class.new(description: description, canonical: canonical, predicate: predicate, ast: ast)
         end
 
-        # PRIMITIVE 1 — an ORDERED CHAIN of flat `Hash[description] =>
+        # Primitive 1 — an ordered chain of flat `Hash[description] =>
         # Rule` pools, first match wins. `CommandBuilder#given`'s own
-        # two-pool shape (its OWN owner's `named_givens`, then a sibling
+        # two-pool shape (its own owner's `named_givens`, then a sibling
         # piece's entity-wide pool) is this with a 2-element chain — a
         # future single-pool bare reference is the same primitive with a
         # 1-element chain, not a separate "just look in one hash" method.
@@ -75,12 +77,12 @@ module Hecks
           nil
         end
 
-        # PRIMITIVE 2 — ONE pool keyed BY DECLARING OWNER,
+        # Primitive 2 — one pool keyed by declaring owner,
         # `Hash[description][owner] => Rule` — `AggregateBuilder#given`'s
         # own chapter-wide shape, the only construct so far where the
-        # SAME description can mean two genuinely different predicates
+        # same description can mean two genuinely different predicates
         # (docs/implemented/resolution-rules/chapter-given.md). Returns the full
-        # candidates Hash (0, 1, or many entries) — deliberately NOT
+        # candidates Hash (0, 1, or many entries) — deliberately not
         # raising here, so each caller keeps its own exact refusal
         # wording for "none," "ambiguous," and "declared_by: named the
         # wrong owner" rather than one generic message papering over all
@@ -89,10 +91,10 @@ module Hecks
           pool[description] || {}
         end
 
-        # PRIMITIVE 3 — a LIVE SCAN over already-built SIBLING OBJECTS'
+        # Primitive 3 — a live scan over already-built sibling objects'
         # own collections, not a separately-maintained pool at all —
         # `ValueObjectBuilder#invariant`'s own shape: every sibling value
-        # object on the same aggregate has ALREADY been built by the time
+        # object on the same aggregate has already been built by the time
         # a later one references back (declaration order, the same
         # constraint every scope in this family carries), so there is
         # nothing to write through — just read their own already-declared
@@ -105,36 +107,36 @@ module Hecks
                   .find { |rule| rule.description == description }
         end
 
-        # WHICH CONSTRUCT USES WHICH PRIMITIVE — no longer a Ruby-only
-        # Hash (that WAS this constant's own shape, one round ago): the
+        # **Which construct uses which primitive** — no longer a Ruby-only
+        # Hash (that was this constant's own shape, one round ago): the
         # user's own correction — "my goal is that if they read the same
         # table they behave identically" — means a table only Ruby ever
         # reads cannot deliver that, no matter how faithfully it is
         # cross-checked afterward. `Keyword#resolves_via`/`#disambiguator`
-        # (self-hosted, `syntax.bluebook`) is the REAL table now — the
-        # SAME generated data `rust/parser/src/keywords.rs` is generated
+        # (self-hosted, `syntax.bluebook`) is the real table now — the
+        # same generated data `rust/parser/src/keywords.rs` is generated
         # from (`bin/project_parser_table`). `#lookup` reads it live.
         #
-        # THE ONE UNAVOIDABLE EXCEPTION: the meta-domain's own bootstrap
+        # **The one unavoidable exception**: the meta-domain's own bootstrap
         # (`MetaValidator.load_grammar_into`) dispatches `given`/
-        # `invariant` on ITSELF 61 times while building the very grammar
+        # `invariant` on itself 61 times while building the very grammar
         # table that would answer "how does given/Aggregate resolve" —
         # `MetaValidator.grammar_registry`/`SyntaxBoot.call` are not
-        # ready yet, and cannot be made ready without ALREADY having
+        # ready yet, and cannot be made ready without already having
         # resolved a `given` somewhere upstream. `MetaValidator.
-        # bootstrapping?` is the SAME guard `MetaValidator.call` (the
+        # bootstrapping?` is the same guard `MetaValidator.call` (the
         # judge) already uses to skip self-judging during this exact
         # window — `#lookup` uses it too, falling back to
-        # `BOOTSTRAP_FALLBACK` (below) ONLY while it's true. Every REAL
+        # `BOOTSTRAP_FALLBACK` (below) only while it's true. Every real
         # domain (banking, pizzas, compliance, any future one) boots
-        # AFTER `grammar_registry` is fully built and memoized, so reads
+        # after `grammar_registry` is fully built and memoized, so reads
         # the real table, every time, no exception.
-        BOOTSTRAP_FALLBACK = {
-          %w[given Aggregate]       => { resolves_via: "owner_keyed", disambiguator: "declared_by" },
-          %w[given Entity]          => { resolves_via: "owner_keyed", disambiguator: "declared_by" },
-          %w[given Command]         => { resolves_via: "hash_chain" },
-          %w[invariant ValueObject] => { resolves_via: "sibling_scan" }
-        }.freeze
+        #
+        # No longer kept in sync by hand — the same `resolves_via`/
+        # `disambiguator` columns, projected ahead of time into the
+        # committed lib/hecks/bluebook/dsl/bootstrap_table.rb
+        # (bin/project_bootstrap_table, pinned by spec/bootstrap_table_spec.rb).
+        BOOTSTRAP_FALLBACK = BootstrapTable::RESOLVES
 
         def lookup(word, context)
           if MetaValidator.bootstrapping?
@@ -149,16 +151,16 @@ module Hecks
           end
         end
 
-        # A LIVE CROSS-CHECK, not a spec-only one — every REAL domain's
+        # A live cross-check, not a spec-only one — every real domain's
         # own boot (not just `bundle exec rspec`) now genuinely fails
         # loudly if a construct's own hand-written resolution method
         # ever disagrees with what the self-hosted grammar table claims
         # for it. Each of the three `reference_named_*` methods below
-        # calls this FIRST, naming the primitive it is ABOUT to use —
+        # calls this first, naming the primitive it is about to use —
         # if `syntax.bluebook`'s own `resolves_via` for this exact
         # (word, context) pair ever names something else, this is a
         # real drift between the language's own self-description and
-        # its own implementation, caught at the next boot of ANYTHING,
+        # its own implementation, caught at the next boot of anything,
         # not just the next `rspec` run.
         def verify_resolves_via!(word, context, expected_primitive)
           actual = lookup(word, context)[:resolves_via]

data/lib/hecks/bluebook/dsl/translation_builder.rb

@@ -28,10 +28,10 @@ module Hecks
           @backfills = []
         end
 
-        # RENAMED FROM `rename`/`move`/`convert`/`retype`/`compute`/
+        # Renamed from `rename`/`move`/`convert`/`retype`/`compute`/
         # `rekey`/`backfill` (all seven below) — item #13's full
         # metaprogrammed dispatch (slice 4c). Not bootstrap-reachable
-        # (translation.bluebook describes ITS OWN structure with
+        # (translation.bluebook describes its own structure with
         # aggregate/entity/attribute, never with these — they're
         # words for real, user-authored `.translation` files only,
         # loaded after the grammar table exists), so none need a
@@ -93,7 +93,7 @@ module Hecks
           @computes << TranslationCompute.new(old_path.to_s, to.to_s, sql.to_s)
         end
 
-        # THE AGGREGATE'S OWN IDENTITY, changing what it's computed from —
+        # The aggregate's own identity, changing what it's computed from —
         # not a field crossing a boundary (`move`), not a value's own
         # transform (`compute`): the record's key. No path arguments,
         # unlike every rule above — nothing is consumed from or moved into
@@ -107,8 +107,8 @@ module Hecks
           @rekeys << TranslationRekey.new(sql.to_s)
         end
 
-        # A NEWLY ADDED, required attribute — the addition-side sibling of
-        # `drop`. Nothing to rename, move, or convert FROM, since old data
+        # A newly added, required attribute — the addition-side sibling of
+        # `drop`. Nothing to rename, move, or convert from, since old data
         # never held this field at all; `default` is what an existing
         # record reads until the next command against it writes a real
         # value. Adapter-agnostic, unlike `compute` — applied the same
@@ -128,11 +128,11 @@ module Hecks
         # The scaffold writes this where it cannot decide; a file carrying
         # one can only boot into this refusal — never a guess.
         #
-        # RENAMED FROM `unresolved` — item #13's full metaprogrammed
+        # Renamed from `unresolved` — item #13's full metaprogrammed
         # dispatch (slice 4). Builds its own message with real branching
         # (empty vs. named candidates, a special :identity case), not a
         # fixed string a boolean `refuses:` flag could express — reached
-        # through `calls:` instead, like `attribute`/`role`. NOT
+        # through `calls:` instead, like `attribute`/`role`. Not
         # bootstrap-reachable: translation.bluebook (loaded during
         # bootstrap, to describe the translation DSL itself) never
         # writes `unresolved` — that word is only ever used by real,
@@ -178,7 +178,7 @@ module Hecks
           path.to_s.include?(".") ? path.to_s.inspect : ":#{path}"
         end
 
-        # THE SCAFFOLD'S OWN HINT for the one drift it can detect but never
+        # The scaffold's own hint for the one drift it can detect but never
         # resolve on its own — an aggregate's `identified_by` changed. Not
         # a field to rename/move/drop, so none of the ordinary hints fit;
         # `coverage_check.rb#check_identity_unchanged!` is the real gate,
@@ -211,7 +211,7 @@ module Hecks
           @retired    = []
         end
 
-        # RENAMED FROM `aggregate` — item #13's full metaprogrammed
+        # Renamed from `aggregate` — item #13's full metaprogrammed
         # dispatch (slice 4c). Not bootstrap-reachable — this "Translation"
         # -context `aggregate` (opens a TranslationAggregateBuilder) is a
         # different (context, word) pair than "Bluebook"-context

data/lib/hecks/bluebook/dsl/value_object_builder.rb

@@ -23,7 +23,7 @@ module Hecks
           @owner_value_objects = owner_value_objects
         end
 
-        # THE WRAPPER BLOCK IS GONE (ADR 0025, "Attributes" — "closed sets
+        # The wrapper block is gone (ADR 0025, "Attributes" — "closed sets
         # lose the wrapper block"). `member` lines are bare now, written
         # directly in the `value_object` body with no `one_of do ... end`
         # around them — `build`'s own `closed_set: @closed_set ||
@@ -39,24 +39,24 @@ module Hecks
         # use the inline form on one of its own attributes. One `one_of`
         # method now, not two.
         #
-        # LEGACY UNDER SHADOW-PARSING (S0a's own bridge) — frozen era text
+        # Legacy under shadow-parsing (S0a's own bridge) — frozen era text
         # still writes the block form (2 locations in
         # `examples/banking/data/eras/banking/1.bluebook`, duplicated once
         # more in that era's own archive copy), so `EraGuard.shadow_parse`
         # still needs to read it. `block_given?` is what tells the two
         # calling shapes apart: the type-position form
         # (`one_of("a", "b")`) never passes a block, only the wrapper does.
-        # RENAMED FROM `one_of` — item #13's full metaprogrammed dispatch
-        # (slice 5). SAME NAME as `AttributeCollector#one_of_impl`'s own
+        # Renamed from `one_of` — item #13's full metaprogrammed dispatch
+        # (slice 5). Same name as `AttributeCollector#one_of_impl`'s own
         # — required for the `super(*values)` call below to keep
         # resolving; see that method's own comment. Reached directly
         # through its own "ValueObject"-context Keyword row (the
         # block-wrapper form has its own row, distinct from "Type"'s),
-        # not through the Type-position fallback this word's OTHER
+        # not through the Type-position fallback this word's other
         # context uses.
         def one_of_impl(*values, &block)
           unless block
-            # NO VALUES, NO BLOCK is the SCALAR spelling — nonsensical, not
+            # No values, no block is the scalar spelling — nonsensical, not
             # merely inert: it names a closed set with nothing in it. The
             # original block form caught this by a side effect (`@closed_set
             # = true` ran unconditionally, before the `if block`), and this
@@ -83,7 +83,7 @@ module Hecks
           instance_eval(&block)
         end
 
-        # RENAMED FROM `member` — item #13's full metaprogrammed dispatch
+        # Renamed from `member` — item #13's full metaprogrammed dispatch
         # (slice 4c). Bootstrap-reachable, in
         # GenericDispatch::BOOTSTRAP_CALLS_FALLBACK.
         def member_impl(**fields)
@@ -92,11 +92,11 @@ module Hecks
           @members << fields
         end
 
-        # NO BLOCK is a REFERENCE, not a fresh declaration — the same
+        # No block is a reference, not a fresh declaration — the same
         # move S10 already made for `CommandBuilder#given` (ADR 0025,
         # "a precondition shared across commands is declared once... a
         # command references it by name"), one level over: a rule
-        # shared across SIBLING value objects on the same aggregate,
+        # shared across sibling value objects on the same aggregate,
         # declared once, on the first one to need it. Real, live
         # redundancy this closes: `Account`'s own `Money`/`PositiveMoney`
         # both declared `invariant("a currency is a three-letter code")
@@ -105,7 +105,7 @@ module Hecks
         # the referencing value object's own build time, against
         # whatever sibling value objects the aggregate has already
         # built, the same ordering rule `given` carries.
-        # RENAMED FROM `invariant` — item #13's full metaprogrammed
+        # Renamed from `invariant` — item #13's full metaprogrammed
         # dispatch (slice 4b). Bootstrap-reachable, in
         # GenericDispatch::BOOTSTRAP_CALLS_FALLBACK.
         def invariant_impl(description, &predicate)
@@ -119,7 +119,7 @@ module Hecks
 
         private
 
-        # PRIMITIVE 3 (RuleReference#resolve_sibling_scan) — see that
+        # Primitive 3 (RuleReference#resolve_sibling_scan) — see that
         # method's own comment for why this is a live scan, not a pool.
         def reference_named_invariant(description)
           verify_resolves_via!("invariant", "ValueObject", "sibling_scan")
@@ -157,15 +157,15 @@ module Hecks
 
         private
 
-        # THE NEW SPELLING — `attribute :name, String, one_of: %w[...]`,
-        # overriding `AttributeCollector`'s own refusal (every OTHER
-        # includer has no meaningful use for this). PRIVATE, like the
+        # **The new spelling** — `attribute :name, String, one_of: %w[...]`,
+        # overriding `AttributeCollector`'s own refusal (every other
+        # includer has no meaningful use for this). Private, like the
         # module's own version it overrides — it is a callback `attribute`
         # invokes on itself, never a word a bluebook author calls by name.
-        # Refuses a SECOND attribute naming one_of: on the same value
+        # Refuses a second attribute naming one_of: on the same value
         # object outright — a single-field set names exactly one field, by
         # construction; two would be structurally ambiguous about which
-        # field each member line belongs to. `build` refuses the OTHER
+        # field each member line belongs to. `build` refuses the other
         # half of that same rule (this attribute coexisting with unrelated
         # ones on a multi-field object).
         def install_inline_closed_set(field, values)

data/lib/hecks/bluebook/dsl/word_gate.rb

@@ -2,46 +2,49 @@ require_relative "generic_dispatch"
 module Hecks
   module Bluebook
     module DSL
-      # THE RUBY-SIDE `word_gate` (`rust/parser/src/parse/mod.rs`'s own,
+      # The Ruby-side `word_gate` (`rust/parser/src/parse/mod.rs`'s own,
       # read there first — this is the same job, one level up: Rust's own
-      # gate refuses a mistyped/inadmissible WORD directly, at the
-      # moment it reads a line of `.bluebook` SOURCE TEXT, before any
+      # gate refuses a mistyped/inadmissible word directly, at the
+      # moment it reads a line of `.bluebook` source text, before any
       # per-construct parsing runs. Ruby never lexes source text — a
-      # `.bluebook` file IS Ruby, so `given("x")` is ALREADY a real
+      # `.bluebook` file is Ruby, so `given("x")` is already a real
       # method call by the time any of this code runs, and Ruby's own
-      # method dispatch already refuses an ARITY mismatch on an
-      # EXISTING method for free. What Ruby's own dispatch does NOT do
-      # is consult the self-hosted grammar table AT ALL — a mistyped
+      # method dispatch already refuses an arity mismatch on an
+      # existing method for free. What Ruby's own dispatch does not do
+      # is consult the self-hosted grammar table at all — a mistyped
       # word (`giv3n("x")`) or a word used in the wrong context
       # (`identified_by` inside a `command` block) just raises Ruby's
       # own generic `NoMethodError`, naming nothing about what the
       # language actually admits. This module closes that gap.
       #
-      # `method_missing`/`respond_to_missing?` ONLY — a word this
+      # ## What reaches this module
+      #
+      # `method_missing`/`respond_to_missing?` only — a word this
       # builder class already answers with an ordinary `def` (or a
-      # shared mixin method like `AttributeCollector#attribute`) never
+      # method a shared mixin such as `AttributeCollector` defines) never
       # reaches this module at all; Ruby's own method lookup finds it
-      # first, and item #13's later slices haven't removed every one of
-      # those yet. This WAS "zero behavior change for every currently-
-      # valid line in the entire corpus" in its own first slice — since
-      # item #13's full metaprogrammed dispatch (slice 1, whole-project
-      # table-unification survey) started REMOVING the hand-written
-      # methods this module's own admissibility check used to defer to,
-      # some words now execute for real here too, via `GenericDispatch`
-      # — see that module's own header for exactly which ones, and the
-      # full account of what was verified before each was migrated. A
-      # mistyped or wrongly-contexted word still gets the same real,
-      # helpful, table-driven refusal Rust's own `word_gate` already
-      # gives, instead of Ruby's own generic `NoMethodError` — that half
-      # is genuinely unchanged.
+      # first, and not every word has had its hand-written method
+      # removed. A word the grammar admits whose builder has no
+      # hand-written method executes for real here, via `GenericDispatch`
+      # (item #13's full metaprogrammed dispatch, whole-project
+      # table-unification survey) — see that module's own header for
+      # exactly which ones, and the full account of what was verified
+      # before each was migrated. A mistyped or wrongly-contexted word
+      # gets the same real, helpful, table-driven refusal Rust's own
+      # `word_gate` already gives, instead of Ruby's own generic
+      # `NoMethodError`.
+      #
+      # ## `GRAMMAR_CONTEXT`
       #
       # `self.class::GRAMMAR_CONTEXT` — each including class names which
       # row of the self-hosted `Context` closed set it corresponds to
       # (`AggregateBuilder::GRAMMAR_CONTEXT = "Aggregate"`, etc.) — the
-      # SAME string `word_gate`'s own `context` parameter already is on
+      # same string `word_gate`'s own `context` parameter already is on
       # the Rust side, read off the identical table.
       #
-      # BOOTSTRAPPING GATED, the same reason `RuleReference#lookup`
+      # ## Bootstrapping
+      #
+      # Bootstrapping gated, the same reason `RuleReference#lookup`
       # already is (`rule_reference.rb`'s own comment has the full
       # story) — the meta-domain's own bootstrap calls dozens of
       # keywords on itself before its own grammar table exists to
@@ -52,28 +55,31 @@ module Hecks
       # is deliberately no fallback covering the whole ~200-row table —
       # that would defeat the entire point.
       #
-      # ONE NARROW EXCEPTION, added in item #13's full metaprogrammed
-      # dispatch (slice 3, whole-project table-unification survey):
-      # `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`, a SMALL, EXPLICIT
-      # table naming the same (context, word) -> method pairs the real
-      # `calls:` column would say once it exists — used ONLY for words
-      # BOTH migrated to the `calls:` shape AND bootstrap-reachable
-      # (`attribute`, today). This is the one place in this whole arc a
+      # One narrow exception (item #13's full metaprogrammed dispatch,
+      # slice 3, whole-project table-unification survey):
+      # `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`, an explicit table
+      # naming the same (context, word) -> method pairs the real
+      # `calls:` column carries, projected ahead of time into the
+      # committed `bootstrap_table.rb` — it matters only for words both
+      # migrated to the `calls:` shape and bootstrap-reachable
+      # (`attribute`, for one). This is the one place in this whole arc a
       # bootstrap fallback was worth building despite `RuleReference`'s
-      # own precedent against it: it duplicates NO logic, only a METHOD
-      # NAME — `attribute_impl`'s own real, hand-written body is called
+      # own precedent against it: it duplicates no logic, only a method
+      # name — `attribute_impl`'s own real, hand-written body is called
       # either way, bootstrap or not, so there is nothing here that can
       # drift the way a full behavioral duplicate could.
       #
-      # TWO FURTHER PIECES, both slice 5:
+      # ## `word_gate_dispatch` and the type-position fallback
+      #
+      # Two further pieces, both slice 5:
       #   - `word_gate_dispatch` is the same admission+dispatch logic
       #     `method_missing` below runs, factored out so a class with
-      #     its OWN class-level `method_missing` (`HecksagonBuilder`'s/
+      #     its own class-level `method_missing` (`HecksagonBuilder`'s/
       #     `WorldBuilder`'s genuinely open-ended verb vocabulary) can
       #     call it directly and fall back to its own open-verb handling
       #     only when this returns `NOT_ADMITTED` — a class-level `def`
       #     always wins over an included module's in Ruby's own method
-      #     resolution, so their OWN `method_missing` is the only one
+      #     resolution, so their own `method_missing` is the only one
       #     that ever runs for them, and this is what lets a real,
       #     closed-set word (`port`/`realm`/`latest`) still reach
       #     `GenericDispatch` despite that.
@@ -84,7 +90,7 @@ module Hecks
       #     "Type" builder `self.class::GRAMMAR_CONTEXT` could ever
       #     name. See that method's own comment.
       module WordGate
-        # A caller with its OWN class-level `method_missing`
+        # A caller with its own class-level `method_missing`
         # (`HecksagonBuilder`/`WorldBuilder` — see `word_gate_dispatch`'s
         # own header) checks for this to tell "not a word the grammar
         # admits at all" apart from every other outcome below (a real
@@ -92,7 +98,7 @@ module Hecks
         # caller can fall through to its own open-ended handling instead.
         NOT_ADMITTED = Object.new.freeze
 
-        # PRIVATE, matching Ruby's own convention for both (`Object`
+        # Private, matching Ruby's own convention for both (`Object`
         # defines them private too) — and load-bearing here, not just
         # style: `spec/syntax_conformance_spec.rb`'s "declares every
         # word X answers" check walks `public_instance_methods`, and a
@@ -129,23 +135,23 @@ module Hecks
           result
         end
 
-        # THE CORE ADMISSION+DISPATCH LOGIC, factored out of
+        # The core admission+dispatch logic, factored out of
         # `method_missing` — item #13's full metaprogrammed dispatch
         # (slice 5, whole-project table-unification survey) — so a
-        # class with its OWN class-level `method_missing`
+        # class with its own class-level `method_missing`
         # (`HecksagonBuilder`'s/`WorldBuilder`'s genuinely open-ended
         # verb vocabulary, `persisted_by "Heki"`/`posted_by "Carrier"`,
-        # can never BE a closed table) can still route a word THE
-        # GRAMMAR ADMITS through here first, falling back to its own
+        # can never be a closed table) can still route a word the
+        # grammar admits through here first, falling back to its own
         # open-verb handling only for what this doesn't recognize at
         # all — unblocking `Hecksagon#port`/`World#realm`/`World#latest`,
         # each a real, closed-set word that happened to sit on a class
         # whose own `method_missing` a class-level `def` always wins
         # over Ruby's own module-inclusion order.
         #
-        # NEVER RAISES "not admitted" — returns `NOT_ADMITTED` instead,
+        # Never raises "not admitted" — returns `NOT_ADMITTED` instead,
         # so the caller (this module's own `method_missing`, or one of
-        # the two above) decides what that means for it. DOES still
+        # the two above) decides what that means for it. Does still
         # raise the richer, table-driven refusals below once a word is
         # admitted-but-unimplemented, or admitted-somewhere-else-only —
         # those are real, useful refusals regardless of which
@@ -161,16 +167,16 @@ module Hecks
           keywords = rows[:keywords]
           admitted = keywords.select { |row| row[:context] == context && (row[:word] == word.to_s || row[:was] == word.to_s) }
 
-          # THE TYPE-POSITION FALLBACK — item #13's full metaprogrammed
+          # **The type-position fallback** — item #13's full metaprogrammed
           # dispatch (slice 5). `one_of`/`list_of`, called inside an
           # attribute's own type argument (`attribute :x,
           # one_of("a","b")`), run with `self` as whatever builder is
-          # CURRENTLY instance_eval'ing — there is no dedicated "Type"
+          # currently instance_eval'ing — there is no dedicated "Type"
           # builder of its own; every attribute()-taking builder answers
           # these identically, through the shared `AttributeCollector`
-          # mixin. `self.class::GRAMMAR_CONTEXT` can never actually BE
+          # mixin. `self.class::GRAMMAR_CONTEXT` can never actually be
           # "Type", so a word admitted only there would otherwise look
-          # inadmissible everywhere. Checked only once THIS context has
+          # inadmissible everywhere. Checked only once this context has
           # already come up empty, so a context with its own same-named
           # row (`ValueObject`'s own `one_of`, the block-wrapper form)
           # keeps using that instead, unaffected.
@@ -190,11 +196,11 @@ module Hecks
                   "'#{word}' is not a word #{context} admits — legal words here: #{legal.join(', ')}"
           end
 
-          # ITEM #13's FULL METAPROGRAMMED DISPATCH — the word IS
+          # Item #13's full metaprogrammed dispatch — the word is
           # admitted here, and this builder has no hand-written method
           # left for it; before falling through to the "not yet
           # implemented" refusal every word without one still gets,
-          # offer it to GenericDispatch — the SAFE, verified subset of
+          # offer it to GenericDispatch — the safe, verified subset of
           # words whose whole behavior is now executed off this same
           # table, not just checked against it.
           dispatched = GenericDispatch.try(self, context, word.to_s, args, kwargs, block, rows)
@@ -215,13 +221,13 @@ module Hecks
             super
         end
 
-        # A word admitted SOMEWHERE, just not in THIS context, still
+        # A word admitted somewhere, just not in this context, still
         # falls through to Ruby's own `NoMethodError` rather than this
         # module's own richer refusal — `method_missing` fires for
         # every typo in the whole codebase (this class's own genuinely
         # private helper methods included), not just DSL keyword calls;
-        # only raise the RICH, table-driven message when the word is at
-        # least SOMETHING the grammar knows about, anywhere, so an
+        # only raise the rich, table-driven message when the word is at
+        # least something the grammar knows about, anywhere, so an
         # unrelated Ruby-level typo inside a builder's own private code
         # keeps its own ordinary, unconfusing `NoMethodError`.
         def admitted_anywhere?(rows, word)