hecks 1.0.2 → 1.2.0

data/lib/hecks/bluebook/value_object.rb

@@ -3,7 +3,7 @@ require_relative "expression/ast_json"
 
 module Hecks
   module Bluebook
-    Invariant = Struct.new(:description, :canonical, :predicate, keyword_init: true)
+    Invariant = Struct.new(:description, :canonical, :predicate, :ast, keyword_init: true)
 
     # A value object — a DECLARATION HOLDER, never instantiated.
     #
@@ -37,7 +37,7 @@ module Hecks
         # `Expression::AstJson`'s own header — built for `rust/host`'s
         # own mint-time invariant check (`reference_validate.rs`), which
         # has no kernel crate to parse `canonical` with.
-        invariants: -> { invariants.map { |rule| { description: rule.description, canonical: rule.canonical, ast: Expression::AstJson.emit_predicate(rule.canonical) } } },
+        invariants: -> { invariants.map { |rule| Expression::AstJson.rule_row(rule) } },
         closed_set: :closed_set?,
         # THE FIELD NAME IS STRINGIFIED, NEVER THE VALUE. A `member` row can
         # hold any of the scalar types an attribute declares — `Integer 84`

data/lib/hecks/codemod.rb

@@ -221,7 +221,11 @@ module Hecks
       # loop for why it can't batch) — splitting it across methods just
       # to satisfy the line count would scatter state four ways for no
       # readability gain.
+      # rubocop:disable-next Metrics/AbcSize
       # rubocop:disable-next Metrics/BlockLength
+      # rubocop:disable-next Metrics/CyclomaticComplexity
+      # rubocop:disable-next Metrics/MethodLength
+      # rubocop:disable-next Metrics/PerceivedComplexity
       def run_example_domains(results, dry_run)
         Codemod::EXAMPLE_ROOTS.each do |domain_dir|
           bluebook_files = Dir.glob(File.join(domain_dir, "bluebook", "*.bluebook"))
@@ -286,6 +290,15 @@ module Hecks
       # changes the IR, so the running state's own export should always
       # still equal the pristine original after each kept edit, by
       # definition, no moving target needed.
+      # Same shape and same reason as run_example_domains just above (see
+      # its own comment) — the write/verify/revert sequence, PER
+      # CANDIDATE (this method's own comment explains why it cannot
+      # batch), is one coherent unit; splitting it would scatter
+      # before_meta/live_meta/applied_by_file state across methods for
+      # no gain.
+      # rubocop:disable-next Metrics/AbcSize
+      # rubocop:disable-next Metrics/CyclomaticComplexity
+      # rubocop:disable-next Metrics/PerceivedComplexity
       def run_meta_domain(results, dry_run)
         before_meta     = Codemod.boot_meta
         meta_candidates = @find_candidates.call(Codemod.meta_registry)

data/lib/hecks/doc/reference.rb

@@ -114,7 +114,7 @@ module Hecks
           by `bin/reference` — do not edit inside the markers. The prose
           between them is hand-written and survives regeneration.*
           #{GENERATED_END}
-          #{preamble.empty? ? '' : "\n#{preamble}\n"}
+          #{"\n#{preamble}\n" unless preamble.empty?}
           #{sections.join("\n")}
         PAGE
       end
@@ -145,7 +145,7 @@ module Hecks
           ## #{row[:word]}
 
           #{generated_begin(row[:word])}
-          #{spellings}#{facts.empty? ? '' : " — #{facts.join(', ')}"}
+          #{spellings}#{" — #{facts.join(', ')}" unless facts.empty?}
           #{table}#{GENERATED_END}
 
           #{prose_or_sentinel(prose)}
@@ -181,7 +181,7 @@ module Hecks
           name = arg[:at].to_s.empty? ? "`#{arg[:named]}:`" : "positional #{arg[:at]}"
           lines << "| #{name} | #{arg[:kind]} | #{arg[:required]} | #{arg[:fills]} |"
         end
-        lines.join("\n") + "\n"
+        "#{lines.join("\n")}\n"
       end
 
       def render_index
@@ -210,6 +210,11 @@ module Hecks
       # region existed has no generated marker ahead of its first `## `,
       # so nothing is collecting when that heading arrives and no empty
       # preamble is invented — the older shape reads back unchanged.
+      # A single-pass line-scanning state machine (current/collecting/
+      # buffer/in_fence) — each branch mutates shared local state that
+      # carries into the NEXT iteration, so splitting per branch would
+      # mean passing all four back and forth by reference every line.
+      # rubocop:disable-next Metrics/PerceivedComplexity
       def harvest(text)
         prose = {}
         current = PREAMBLE
@@ -263,7 +268,7 @@ module Hecks
       end
 
       def guide_index(root)
-        paths = Dir.glob(File.join(root, "docs/implemented/guides/*.md")).sort
+        paths = Dir.glob(File.join(root, "docs/implemented/guides/*.md"))
                    .reject { |p| %w[AUTHORING.md].include?(File.basename(p)) }
         lines = paths.map do |path|
           heading = File.foreach(path).find { |line| line.start_with?("# ") }
@@ -273,7 +278,7 @@ module Hecks
         lines.join("\n")
       end
 
-      def reference_index(root)
+      def reference_index(_root)
         count = contexts.size
         "[The DSL reference](docs/implemented/reference/index.md) — #{count} contexts, generated from " \
           "the aggregate-local tables under `lib/hecks/language/` and held to them by " \
@@ -333,11 +338,11 @@ module Hecks
       end
 
       def corpus_roster(root)
-        dirs = Dir.glob(File.join(root, "examples/*/")).sort
+        dirs = Dir.glob(File.join(root, "examples/*/"))
         lines = dirs.filter_map do |dir|
           name = File.basename(dir.chomp("/"))
-          bluebooks = Dir.glob(File.join(dir, "bluebook/*.bluebook")).sort
-          bluebooks = Dir.glob(File.join(dir, "*.bluebook")).sort if bluebooks.empty?
+          bluebooks = Dir.glob(File.join(dir, "bluebook/*.bluebook"))
+          bluebooks = Dir.glob(File.join(dir, "*.bluebook")) if bluebooks.empty?
           next if bluebooks.empty?
 
           vision = bluebooks.filter_map { |bluebook| File.read(bluebook)[/vision\s+"([^"]*)"/, 1] }.first
@@ -364,7 +369,7 @@ module Hecks
       # example — a word whose only "example" is invisible or inert is a
       # word still shipping on its prose alone, which is the thing this
       # gate exists to refuse.
-      EXAMPLE_FENCE = /^```ruby(?: bluebook| boot)?[ \t]*$/.freeze
+      EXAMPLE_FENCE = /^```ruby(?: bluebook| boot)?[ \t]*$/
 
       def exemplified?(prose) = prose.to_s.match?(EXAMPLE_FENCE)
 
@@ -378,12 +383,13 @@ module Hecks
       # `harvest` already rejects empty prose and the TODO sentinel, so a
       # word with nothing written for it arrives here with a nil.
       def live_words(directory)
-        contexts.flat_map { |context|
+        rows = contexts.flat_map do |context|
           path = File.join(directory, page_name(context))
           prose = File.exist?(path) ? harvest(File.read(path)) : {}
           keywords.select { |row| row[:context] == context && live?(row) }
                   .map { |row| [row[:word], context, prose[row[:word]]] }
-        }.uniq { |word, context, _| [word, context] }
+        end
+        rows.uniq { |word, context, _| [word, context] }
       end
 
       def name_of(word, context) = "#{word} (#{context})"

data/lib/hecks/facade/cli_runner.rb

@@ -79,7 +79,7 @@ module Hecks
       rescue Runtime::NotFound, Runtime::TypeMismatch => e
         # A BAD ARGUMENT AND A MISSING RECORD BOTH LAND HERE, and both want the
         # same next step: read what the verb actually takes.
-        ["#{e.message}\n\n  #{program} #{asking ? 'ask ' : ''}#{name} --help", 1]
+        ["#{e.message}\n\n  #{program} #{'ask ' if asking}#{name} --help", 1]
       rescue *Runtime::DOMAIN_REFUSALS => e
         # THE REFUSAL IS THE PRODUCT — the chapter's own sentence, verbatim.
         [e.message, 1]
@@ -177,7 +177,7 @@ module Hecks
 
         lines = ["no such #{asking ? 'question' : 'verb'}: #{name}"]
         lines += ["", "did you mean:", *near.first(5).map { |candidate| "  #{candidate}" }] unless near.empty?
-        lines += ["", "  #{program}#{asking ? ' ask' : ''}   for the full list"]
+        lines += ["", "  #{program}#{' ask' if asking}   for the full list"]
         lines.join("\n")
       end
 

data/lib/hecks/facade/command_request.rb

@@ -18,9 +18,7 @@ module Hecks
 
       def normalize(input, receiver:, legacy_receiver: nil)
         request = symbolize(input)
-        unless request.is_a?(Hash)
-          raise Runtime::TypeMismatch, "a command request must be a hash"
-        end
+        raise Runtime::TypeMismatch, "a command request must be a hash" unless request.is_a?(Hash)
 
         route, facts = split(request, receiver: receiver, legacy_receiver: legacy_receiver)
         validate_route!(route, receiver)
@@ -54,9 +52,7 @@ module Hecks
       def take_legacy_route(flat, receiver, legacy_receiver)
         return unless legacy_receiver
 
-        if receiver == :aggregate
-          return flat.delete(legacy_receiver.to_sym)
-        end
+        return flat.delete(legacy_receiver.to_sym) if receiver == :aggregate
 
         return unless receiver == :entity && legacy_receiver.is_a?(Hash)
 
@@ -68,23 +64,27 @@ module Hecks
       end
       private_class_method :take_legacy_route
 
+      # A case dispatch over the three closed receiver kinds (nil,
+      # :aggregate, :entity) plus the impossible-kind backstop — each
+      # branch is its own self-contained validation for that one kind.
+      # rubocop:disable-next Metrics/CyclomaticComplexity
       def validate_route!(route, receiver)
         case receiver
         when nil
           raise Runtime::TypeMismatch, "this command does not take a receiver in to:" unless route.nil?
         when :aggregate
           if route.nil? || route.to_s.empty? || route.is_a?(Hash)
-            raise Runtime::TypeMismatch, "to: must name the receiving aggregate identity"
+            raise Runtime::TypeMismatch,
+                  "to: must name the receiving aggregate identity"
           end
         when :entity
-          unless route.is_a?(Hash)
-            raise Runtime::TypeMismatch, "to: for an entity command must contain aggregate: and entity:"
-          end
+          raise Runtime::TypeMismatch, "to: for an entity command must contain aggregate: and entity:" unless route.is_a?(Hash)
 
           extra = route.keys - [:aggregate, :entity]
           missing = [:aggregate, :entity].select { |key| route[key].nil? || route[key].to_s.empty? }
           unless extra.empty? && missing.empty?
-            raise Runtime::TypeMismatch, "to: for an entity command must contain only aggregate: and entity:"
+            raise Runtime::TypeMismatch,
+                  "to: for an entity command must contain only aggregate: and entity:"
           end
         else
           raise ArgumentError, "unknown receiver kind #{receiver.inspect}"

data/lib/hecks/facade/handle.rb

@@ -18,10 +18,10 @@ module Hecks
     class Handle
       attr_reader :id
 
-      def initialize(dispatcher:, domain:, ir:, instance:)
+      def initialize(dispatcher:, domain:, aggregate:, instance:)
         @dispatcher = dispatcher
         @domain     = domain
-        @ir         = ir
+        @ir         = aggregate
         @id         = instance.id
         @state      = instance.state
         define_reference_accessors
@@ -72,7 +72,7 @@ module Hecks
       # A declared field not yet written arrives here too (nil, the way a
       # defined reader answered). Verbs are NOT handled here — see
       # `define_verb_methods` for why.
-      def method_missing(name, *args, **kwargs, &block)
+      def method_missing(name, *args, **kwargs, &)
         return @state[name] if @state.key?(name) || reader?(name)
 
         super

data/lib/hecks/facade/surface/aggregate_door.rb

@@ -13,14 +13,25 @@ module Hecks
       # `persisted_by`-style binding collector a `.hecksagon` lands on, and
       # the aggregate-scoped `port` a `.hecksagon` lands on beside it.
       module AggregateDoor
-        def aggregate_module(dispatcher, domain, ir)
-          fqn  = "#{domain}::#{ir.hecks_name}"
+        # One method building one `door` module's ~20 singleton methods
+        # looks like it splits along each `define_singleton_method` call,
+        # but three of those blocks (`:port`, `:method_missing`,
+        # `:const_missing`) are a single cross-referencing essay on the
+        # stale-facade-across-boots hazard — each one's comment explicitly
+        # points at "below"/"above" as part of the SAME method. Splitting
+        # into helper methods wouldn't break anything at runtime (no
+        # shared mutable state beyond the closed-over args, which just
+        # become parameters), but it would sever that narrative across
+        # method boundaries for no functional gain.
+        # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+        def aggregate_module(dispatcher, domain, aggregate)
+          fqn  = "#{domain}::#{aggregate.hecks_name}"
           door = Module.new
 
-          ir.attributes.each do |attribute|
+          aggregate.attributes.each do |attribute|
             next unless RESERVED.include?(attribute.name.to_sym)
 
-            warn "[hecks] #{ir.hecks_name}##{attribute.name} shadows a built-in — no reader defined"
+            warn "[hecks] #{aggregate.hecks_name}##{attribute.name} shadows a built-in — no reader defined"
           end
 
           # A creating verb is a MODULE method returning the new record in hand ;
@@ -33,9 +44,9 @@ module Hecks
           # accounts, a real same-aggregate collision this corpus already
           # has) — the suffix is what makes both nameable at all, not
           # merely a style choice.
-          ir.commands.select(&:creates?).each do |command|
+          aggregate.commands.select(&:creates?).each do |command|
             door.define_singleton_method("#{Naming.snake(command.hecks_name)}!") do |**args|
-              Handle.new(dispatcher: dispatcher, domain: domain, ir: ir,
+              Handle.new(dispatcher: dispatcher, domain: domain, aggregate: aggregate,
                          instance: dispatcher.dispatch("#{fqn}.#{command.hecks_name}", with: args).instance)
             end
           end
@@ -46,14 +57,14 @@ module Hecks
           # about the way `!` does for a command. Answers the raw row
           # array `dispatcher.query` itself answers, the same shape
           # `runtime.query("#{fqn}.Name")` already gave.
-          ir.queries.each do |query|
+          aggregate.queries.each do |query|
             door.define_singleton_method(Naming.snake(query.hecks_name)) do |**args|
               dispatcher.query("#{fqn}.#{query.hecks_name}", **args)
             end
           end
 
           door.define_singleton_method(:fqn)        { fqn }
-          door.define_singleton_method(:ir)         { ir }
+          door.define_singleton_method(:ir)         { aggregate }
 
           # THE SAME VERB THE CHAPTER ANSWERS, one level down. Every
           # construct emits its own IR (Hecks::IR), so an aggregate
@@ -67,39 +78,41 @@ module Hecks
           # `{"aggregates" => []}` for an aggregate.
           door.define_singleton_method(:project) do |target, out: nil, **options|
             key      = Projector.key_for(target)
-            artifact = Projector.call(key, bluebook: ir, options: options)
+            artifact = Projector.call(key, bluebook: aggregate, options: options)
             return artifact unless out
 
             Projector.write(artifact, out, as: Projector.emits_for(key))
           end
-          door.define_singleton_method(:repository) { dispatcher.registry.repository(domain, ir) }
-          door.define_singleton_method(:commands)   { ir.commands.map { |c| "#{Naming.snake(c.hecks_name)}!" }.sort }
-          door.define_singleton_method(:queries)    { ir.queries.map { |q| Naming.snake(q.hecks_name) }.sort }
+          door.define_singleton_method(:repository) { dispatcher.registry.repository(domain, aggregate) }
+          door.define_singleton_method(:commands) do
+            aggregate.commands.map { |c| "#{Naming.snake(c.hecks_name)}!" }.sort
+          end
+          door.define_singleton_method(:queries) { aggregate.queries.map { |q| Naming.snake(q.hecks_name) }.sort }
           # ONE AGGREGATE'S USAGE DOCUMENT — the same projection the chapter
           # answers with, narrowed to this head. `commands` above already
           # answers "what can I call"; this answers "and what does each one
           # want, refuse, and guarantee", which is the rest of the question.
           door.define_singleton_method(:docs) do |**options|
             Projector.call(:docs, bluebook: dispatcher.registry.bluebook(domain),
-                                  options:  options.merge(aggregate: ir.hecks_name))
+                                  options:  options.merge(aggregate: aggregate.hecks_name))
           end
           # ONE AGGREGATE, READ BACK IN ENGLISH — the same narrowing `:docs`
           # takes, aimed at `:narrate` instead.
           door.define_singleton_method(:narrate) do |**options|
             Projector.call(:narrate, bluebook: dispatcher.registry.bluebook(domain),
-                                     options:  options.merge(aggregate: ir.hecks_name))
+                                     options:  options.merge(aggregate: aggregate.hecks_name))
           end
-          door.define_singleton_method(:count)      { dispatcher.registry.repository(domain, ir).count }
+          door.define_singleton_method(:count)      { dispatcher.registry.repository(domain, aggregate).count }
           door.define_singleton_method(:events)     { dispatcher.events.select { |event| event.aggregate == fqn } }
 
           door.define_singleton_method(:find) do |id|
-            found = dispatcher.registry.repository(domain, ir).find(id)
-            found && Handle.new(dispatcher: dispatcher, domain: domain, ir: ir, instance: found)
+            found = dispatcher.registry.repository(domain, aggregate).find(id)
+            found && Handle.new(dispatcher: dispatcher, domain: domain, aggregate: aggregate, instance: found)
           end
 
           door.define_singleton_method(:all) do |**opts|
-            dispatcher.registry.repository(domain, ir).all(**opts).map do |instance|
-              Handle.new(dispatcher: dispatcher, domain: domain, ir: ir, instance: instance)
+            dispatcher.registry.repository(domain, aggregate).all(**opts).map do |instance|
+              Handle.new(dispatcher: dispatcher, domain: domain, aggregate: aggregate, instance: instance)
             end
           end
 
@@ -109,20 +122,20 @@ module Hecks
           # `ConstShim`/`const_missing`, so `Pizzas::Pizza.port(...)` lands
           # HERE instead once any boot has run before.
           #
-          # RE-RESOLVED, NOT THE CLOSED-OVER `ir` — this door can be a STALE
-          # one, built by a boot from earlier in this same process, sitting
-          # on the `Pizzas`/`Pizza` constants only because nothing has
-          # re-installed them since. Attaching to this door's OWN `ir` would
-          # attach the port to a discarded aggregate from that old boot,
-          # invisible to the CURRENT one actually being loaded — silently,
-          # the exact way `method_missing` below already has to avoid it for
-          # a plain bind, via `HecksagonBuilder.collector` rather than
-          # anything this door closes over. `Hecks.current_registry` is
-          # the same "whichever boot is actually in progress" indirection,
+          # RE-RESOLVED, NOT THE CLOSED-OVER `aggregate` — this door can be a
+          # STALE one, built by a boot from earlier in this same process,
+          # sitting on the `Pizzas`/`Pizza` constants only because nothing
+          # has re-installed them since. Attaching to this door's OWN
+          # `aggregate` would attach the port to a discarded aggregate from
+          # that old boot, invisible to the CURRENT one actually being
+          # loaded — silently, the exact way `method_missing` below already
+          # has to avoid it for a plain bind, via `HecksagonBuilder.collector`
+          # rather than anything this door closes over. `Hecks.current_registry`
+          # is the same "whichever boot is actually in progress" indirection,
           # and `BindingProxy#port` already re-resolves through it the same
           # way — this is that door's fallback twin, not a shortcut past it.
           door.define_singleton_method(:port) do |name, &block|
-            current = Hecks.current_registry&.bluebook(domain)&.aggregate(ir.hecks_name) or
+            current = Hecks.current_registry&.bluebook(domain)&.aggregate(aggregate.hecks_name) or
               raise Bluebook::DSL::Malformed, "#{fqn}.port(#{name.inspect}) called outside a boot"
 
             domain_port = Bluebook::DSL::ConstShim.with(->(const) { const }) do
@@ -163,16 +176,17 @@ module Hecks
           # const_missing directly, never `Object.const_missing`/`ConstShim::
           # Hook` at all: real modules resolve without ever calling that.
           #
-          # `ir.hecks_name`, NOT the qualified `fqn` — a scoped reference has to
-          # read the SAME either way, whether or not a stale door happens to be
-          # sitting on this process from an earlier boot; qualifying it here
-          # would make `Account::Debit`'s own meaning depend on incidental
-          # process history, which is the exact instability S0b exists to
-          # remove (docs/dsl-work-slices.md — "two domains in one registry" is
-          # this file's own reason for being owned by that slice).
+          # `aggregate.hecks_name`, NOT the qualified `fqn` — a scoped
+          # reference has to read the SAME either way, whether or not a stale
+          # door happens to be sitting on this process from an earlier boot;
+          # qualifying it here would make `Account::Debit`'s own meaning
+          # depend on incidental process history, which is the exact
+          # instability S0b exists to remove (docs/dsl-work-slices.md — "two
+          # domains in one registry" is this file's own reason for being
+          # owned by that slice).
           door.define_singleton_method(:const_missing) do |name|
             resolver = Bluebook::DSL::ConstShim.resolver
-            return resolver.call("#{ir.hecks_name}::#{name}") if resolver
+            return resolver.call("#{aggregate.hecks_name}::#{name}") if resolver
 
             super(name)
           end

data/lib/hecks/facade.rb

@@ -15,6 +15,10 @@ module Hecks
   # what GENERATED retains is one small facade module per name, not a graph
   # per boot.
   module Namespace
+    # NOT frozen — a real registry, mutated below
+    # (`GENERATED[[container, name]] = value`). False positive for
+    # Style/MutableConstant.
+    # rubocop:disable-next Style/MutableConstant
     GENERATED = {}
 
     module_function

data/lib/hecks/forms/app.rb

@@ -118,7 +118,8 @@ module Hecks
         return respond(405, "text/plain", "GET only") unless request.get?
 
         if format == "html"
-          html("#{chapter.name}::#{aggregate.hecks_name}", RecordRenderer.index(registry: @registry, domain: chapter.name, aggregate: aggregate),
+          html("#{chapter.name}::#{aggregate.hecks_name}",
+               RecordRenderer.index(registry: @registry, domain: chapter.name, aggregate: aggregate),
                breadcrumbs: [[chapter.name, "/"], [aggregate.hecks_name, nil]])
         else
           instances = @registry.repository(chapter.name, aggregate).all
@@ -196,7 +197,7 @@ module Hecks
       end
 
       def command_json(request, domain, aggregate, command)
-        return json(200, command.to_h) if request.get? && request.GET.reject { |k, _| k == "format" }.empty?
+        return json(200, command.to_h) if request.get? && request.GET.except("format").empty?
         return respond(405, "text/plain", "GET or POST only") unless request.post?
 
         _, envelope = submitted_command(request, aggregate, command)
@@ -213,7 +214,7 @@ module Hecks
         return respond(405, "text/plain", "GET only") unless request.get?
 
         params = request.GET
-        asked = params.reject { |k, _| k == "format" }
+        asked = params.except("format")
         return query_json(domain, aggregate, query, asked) if format != "html"
 
         query_html(domain, aggregate, query, asked)
@@ -252,7 +253,7 @@ module Hecks
       def run_query(domain, aggregate, query, fields, asked)
         args = Params.extract(fields, asked)
         rows = @dispatcher.query("#{domain}::#{aggregate.hecks_name}.#{query.hecks_name}", **args)
-        [rows.map { |row| Record.new(row[:id], row.reject { |k, _| k == :id }) }, nil]
+        [rows.map { |row| Record.new(row[:id], row.except(:id)) }, nil]
       # L10 (docs/audits/2026-08-10-main-bug-audit.md) — `Params.extract`
       # (params.rb's `extract_list`) reads a list-of-value-object line as
       # JSON (the honest fallback for a multi-attribute list element this
@@ -275,7 +276,8 @@ module Hecks
         # sites in this file (see aggregate_route's own comment).
         return json(200, instance.state.merge(id: instance.id)) if format != "html"
 
-        html("#{domain}::#{aggregate.hecks_name} #{id}", RecordRenderer.show(registry: @registry, domain: domain, aggregate: aggregate, id: id),
+        html("#{domain}::#{aggregate.hecks_name} #{id}",
+             RecordRenderer.show(registry: @registry, domain: domain, aggregate: aggregate, id: id),
              breadcrumbs: [[domain, "/"], [aggregate.hecks_name, "/#{domain}/#{aggregate.hecks_name}.html"], [id, nil]])
       end
 
@@ -283,7 +285,9 @@ module Hecks
         return json(404, { error: "NotFound", message: "no #{aggregate.hecks_name} #{id}" }) if format != "html"
 
         respond(404, "text/html; charset=utf-8",
-                Page.render(title: "not found", body: "<h1>Not found</h1><p>No #{Escape.html(aggregate.hecks_name)} #{Escape.html(id)}.</p>"))
+                Page.render(title: "not found",
+                            body:  "<h1>Not found</h1><p>No #{Escape.html(aggregate.hecks_name)} " \
+                                   "#{Escape.html(id)}.</p>"))
       end
 
       def find_aggregate(chapter, name)

data/lib/hecks/forms/command_form_renderer.rb

@@ -57,9 +57,9 @@ module Hecks
       def self.header(domain, aggregate, command)
         <<~HTML
           <h1>#{Escape.html("#{domain}::#{aggregate.hecks_name}.#{command.hecks_name}")}</h1>
-          #{command.role ? %(<span class="badge role" title="Declared on the command; this prototype dispatches with no caller bound, so the check does not run.">role: #{Escape.html(command.role)} (not enforced here)</span>) : ''}
-          #{command.creates? ? %(<span class="badge">creates a new #{Escape.html(aggregate.hecks_name)}</span>) : ''}
-          #{command.goal ? %(<p class="goal">#{Escape.html(command.goal)}</p>) : ''}
+          #{%(<span class="badge role" title="Declared on the command; this prototype dispatches with no caller bound, so the check does not run.">role: #{Escape.html(command.role)} (not enforced here)</span>) if command.role}
+          #{%(<span class="badge">creates a new #{Escape.html(aggregate.hecks_name)}</span>) if command.creates?}
+          #{%(<p class="goal">#{Escape.html(command.goal)}</p>) if command.goal}
           #{givens_callout(command)}
         HTML
       end

data/lib/hecks/forms/field_renderer.rb

@@ -28,7 +28,7 @@ module Hecks
       def self.group(field, values, errors, reference_options, tag:, css: nil)
         inner = field.children.map { |child| render(child, values: values, errors: errors, reference_options: reference_options) }
         <<~HTML
-          <#{tag}#{css ? %( class="#{css}") : ""}>
+          <#{tag}#{%( class="#{css}") if css}>
             <legend>#{Escape.html(field.label)}#{required_mark(field)}</legend>
             #{inner.join("\n")}
           </#{tag}>
@@ -43,7 +43,7 @@ module Hecks
             <label for="#{dom_id(field.path)}">#{Escape.html(field.label)}#{required_mark(field)}</label>
             <textarea id="#{dom_id(field.path)}" name="#{Escape.attr(field.path)}"
               #{aria(field)} placeholder="one #{Escape.attr(item.label.downcase)} per line">#{Escape.html(current)}</textarea>
-            <span class="help" id="#{dom_id(field.path)}-help">One #{Escape.html(item.label.downcase)} per line#{item.leaf? ? '' : ' — each line is one JSON object'}.</span>
+            <span class="help" id="#{dom_id(field.path)}-help">One #{Escape.html(item.label.downcase)} per line#{' — each line is one JSON object' unless item.leaf?}.</span>
           </div>
         HTML
       end
@@ -64,11 +64,11 @@ module Hecks
 
       def self.wrap(field, body, error)
         <<~HTML
-          <div class="field#{error ? ' has-error' : ''}">
-            #{field.kind == :boolean ? '' : %(<label for="#{dom_id(field.path)}">#{Escape.html(field.label)}#{required_mark(field)}</label>)}
+          <div class="field#{' has-error' if error}">
+            #{%(<label for="#{dom_id(field.path)}">#{Escape.html(field.label)}#{required_mark(field)}</label>) unless field.kind == :boolean}
             #{body}
-            #{field.help ? %(<span class="help" id="#{dom_id(field.path)}-help">#{Escape.html(field.help)}</span>) : ''}
-            #{error ? %(<span class="help" role="alert">#{Escape.html(error)}</span>) : ''}
+            #{%(<span class="help" id="#{dom_id(field.path)}-help">#{Escape.html(field.help)}</span>) if field.help}
+            #{%(<span class="help" role="alert">#{Escape.html(error)}</span>) if error}
           </div>
         HTML
       end
@@ -114,7 +114,8 @@ module Hecks
       def self.select(field, value)
         selected = value || field.default
         options = field.options.map do |option_value, option_label|
-          %(<option value="#{Escape.attr(option_value)}"#{option_value.to_s == selected.to_s ? ' selected' : ''}>#{Escape.html(option_label)}</option>)
+          %(<option value="#{Escape.attr(option_value)}"#{' selected' if option_value.to_s == selected.to_s}>) \
+            "#{Escape.html(option_label)}</option>"
         end
         blank = field.optional? ? %(<option value="">—</option>) : ""
         %(<select id="#{dom_id(field.path)}" name="#{Escape.attr(field.path)}" #{aria(field)}>#{blank}#{options.join}</select>)
@@ -124,9 +125,13 @@ module Hecks
         return input(field.tap { |f| f.html_type = "text" }, value) unless options && !options.empty?
 
         rendered = options.map do |id, label|
-          %(<option value="#{Escape.attr(id)}"#{id.to_s == value.to_s ? ' selected' : ''}>#{Escape.html(label)}</option>)
+          %(<option value="#{Escape.attr(id)}"#{' selected' if id.to_s == value.to_s}>#{Escape.html(label)}</option>)
         end
-        blank = field.optional? ? %(<option value="">—</option>) : %(<option value="" disabled#{value ? '' : ' selected'}>choose one…</option>)
+        blank = if field.optional?
+                  %(<option value="">—</option>)
+                else
+                  %(<option value="" disabled#{' selected' unless value}>choose one…</option>)
+                end
         %(<select id="#{dom_id(field.path)}" name="#{Escape.attr(field.path)}" #{aria(field)}>#{blank}#{rendered.join}</select>)
       end
 

data/lib/hecks/forms/field_shape.rb

@@ -24,6 +24,8 @@ module Hecks
       def required? = !optional
     end
 
+    # Turns a wire-spelled field or path segment into the plain-English text
+    # `FieldShape` embeds as a `Field`'s label or a group's legend.
     module Humanize
       # "given" -> "Given", "daily_limit" -> "Daily limit", "end_to_end" ->
       # "End to end" — the label a plain reader wants, not the wire spelling.
@@ -91,8 +93,11 @@ module Hecks
       def self.reference_field(attribute, common)
         target = attribute.type.resolve
         Field.new(**common, kind: :reference, html_type: "text", target_aggregate: target,
-                            help: target ? "References an existing #{target.hecks_name} by id." :
-                                  "References an aggregate in another domain — enter its id.")
+                            help: if target
+                                    "References an existing #{target.hecks_name} by id."
+                                  else
+                                    "References an aggregate in another domain — enter its id."
+                                  end)
       end
 
       # `admits:` names a closed set declared ELSEWHERE (`"Account::

data/lib/hecks/forms/html.rb

@@ -69,7 +69,7 @@ module Hecks
           next if value.nil? || value == false
           next name.to_s.tr("_", "-") if value == true
 
-          %(#{name.to_s.tr("_", "-")}="#{Escape.attr(value)}")
+          %(#{name.to_s.tr('_', '-')}="#{Escape.attr(value)}")
         end.join(" ")
       end
 
@@ -78,7 +78,10 @@ module Hecks
         rendered.empty? ? "<#{name}>" : "<#{name} #{rendered}>"
       end
 
-      def self.void(name, **pairs) = open(name, **pairs) # self-closing tags read the same; HTML5 needs no slash
+      # `self.open(...)`, not bare `open(...)` — this Html.open (an HTML tag
+      # renderer, right above) shadows Kernel#open safely either way, but the
+      # explicit receiver also settles Security/Open's static ambiguity.
+      def self.void(name, **pairs) = self.open(name, **pairs) # self-closing tags read the same; HTML5 needs no slash
     end
   end
 end

data/lib/hecks/forms/index_renderer.rb

@@ -26,7 +26,7 @@ module Hecks
           HTML
         end
         <<~HTML
-          <h2>#{Escape.html(name)}#{chapter.vision ? %( <span class="badge">#{Escape.html(chapter.vision)}</span>) : ''}</h2>
+          <h2>#{Escape.html(name)}#{%( <span class="badge">#{Escape.html(chapter.vision)}</span>) if chapter.vision}</h2>
           <ul class="verb-list">#{items.join}</ul>
         HTML
       end

data/lib/hecks/forms/page.rb

@@ -40,12 +40,16 @@ module Hecks
         return "" if crumbs.empty?
 
         items = crumbs.map do |label, href|
-          href ? %(<a href="#{Escape.attr(href)}">#{Escape.html(label)}</a>) : %(<span aria-current="page">#{Escape.html(label)}</span>)
+          if href
+            %(<a href="#{Escape.attr(href)}">#{Escape.html(label)}</a>)
+          else
+            %(<span aria-current="page">#{Escape.html(label)}</span>)
+          end
         end
         %(<nav class="breadcrumbs" aria-label="Breadcrumb">#{items.join(' <span class="sep">/</span> ')}</nav>)
       end
 
-      STYLE = <<~CSS
+      STYLE = <<~CSS.freeze
         :root {
           --bg: #fbfaf8; --surface: #ffffff; --border: #e2ddd3; --text: #24211c;
           --muted: #6b6355; --accent: #8a5a2b; --accent-contrast: #fff8ef;
@@ -131,7 +135,7 @@ module Hecks
       # Decorative only — every form here already works with JS disabled
       # (plain `<form method=post>`/`method=get`), matching this repo's own
       # "no ERB, nothing scripted" bar for the domain layer itself.
-      SCRIPT = <<~JS
+      SCRIPT = <<~JS.freeze
         document.addEventListener("click", (event) => {
           const button = event.target.closest("[data-copy]");
           if (!button) return;