hecks 2.8.0 → 2.9.0

data/lib/hecks/language/oidc.json

@@ -236,6 +236,21 @@
       "verb": "Bluebook::Query.Option",
       "role": "Language"
     },
+    {
+      "scope": "bluebook:read_model.all",
+      "verb": "Bluebook::ReadModel.All",
+      "role": "Language"
+    },
+    {
+      "scope": "bluebook:read_model.any",
+      "verb": "Bluebook::ReadModel.Any",
+      "role": "Language"
+    },
+    {
+      "scope": "bluebook:read_model.avg",
+      "verb": "Bluebook::ReadModel.Avg",
+      "role": "Language"
+    },
     {
       "scope": "bluebook:read_model.count",
       "verb": "Bluebook::ReadModel.Count",
@@ -256,16 +271,36 @@
       "verb": "Bluebook::ReadModel.GroupBy",
       "role": "Language"
     },
+    {
+      "scope": "bluebook:read_model.max",
+      "verb": "Bluebook::ReadModel.Max",
+      "role": "Language"
+    },
     {
       "scope": "bluebook:read_model.median",
       "verb": "Bluebook::ReadModel.Median",
       "role": "Language"
     },
+    {
+      "scope": "bluebook:read_model.min",
+      "verb": "Bluebook::ReadModel.Min",
+      "role": "Language"
+    },
     {
       "scope": "bluebook:read_model.option",
       "verb": "Bluebook::ReadModel.Option",
       "role": "Language"
     },
+    {
+      "scope": "bluebook:read_model.percentile",
+      "verb": "Bluebook::ReadModel.Percentile",
+      "role": "Language"
+    },
+    {
+      "scope": "bluebook:read_model.sum",
+      "verb": "Bluebook::ReadModel.Sum",
+      "role": "Language"
+    },
     {
       "scope": "bluebook:syntax.argument",
       "verb": "Bluebook::Syntax.Argument",

data/lib/hecks/language/port.bluebook

@@ -25,14 +25,8 @@ Hecks.bluebook "Port" do
       attribute :value, String, one_of: ["reply", "effect"]
     end
 
-    # THE METHOD CONTRACT — what an adapter must actually `respond_to?`
-    # for a dispatch through this door to reach it, as opposed to `verb`
-    # and `signal`, which only ever describe the door itself. Optional
-    # the same way `verb` is (a port declared with none is exactly
-    # today's pre-existing behavior, unchecked past `verify!`'s existing
-    # gates), and a plain list of method names rather than a richer
-    # shape — the same restraint `AdapterField` already takes for
-    # `field`/`secret`.
+    # The method contract: what an adapter must `respond_to?` for a dispatch through this door.
+    # A port that declares none is unchecked beyond `verify!`.
     value_object "PortAnswer" do
       attribute :value, String
       invariant("an answer names a real method") { !value.to_s.empty? }
@@ -43,12 +37,7 @@ Hecks.bluebook "Port" do
       goal "Open a resource door a domain's own aggregates may call by verb"
 
       attribute :name,   PortName
-      # OPTIONAL — real, pre-existing PortBuilder behavior (spec/dsl_spec
-      # .rb's own "signal says whether the domain gets a value back..."
-      # builds a port with only `signal`, never calling `verb` at all;
-      # `def verb(value)` has no default, unlike `signal`'s `:reply`).
-      # Same asymmetry world.bluebook's own Declare command already has
-      # for `realm`/`latest`.
+      # Optional: a port may declare only `signal`; `verb` has no default, unlike `signal`.
       attribute :verb,   PortVerb, optional: true
       attribute :signal, PortSignal
 
@@ -71,9 +60,7 @@ Hecks.bluebook "Port" do
       emits "PortAnswerAdded"
     end
 
-    # HOW PORT IS SPELLED. These rows live with the concept
-    # they describe; SyntaxBoot discovers every aggregate-local seed table.
-    # Contexts represented here: File, Port.
+    # Keyword rows for File and Port; SyntaxBoot discovers every aggregate-local seed table.
     value_object "KeywordSeed" do
       attribute :word,          String
       attribute :context,       String, admits: "Syntax::Context"

data/lib/hecks/language/translation/translation.bluebook

@@ -24,12 +24,8 @@ Hecks.bluebook "Translation" do
       invariant("a name says something") { !value.to_s.empty? }
     end
 
-    # ARBITRARY, UNVALIDATED CAPTURE — `convert`'s own `values:` table and
-    # `backfill`'s own `default:` are open-ended (any literal a real
-    # migration needs), the same shape `AggregateBuilder#provenance`/
-    # `CommandBuilder#provenance` already capture as plain, unvalidated
-    # text (`LiteralText`, aggregate.bluebook) rather than a fixed
-    # attribute shape a closed self-hosted record could enumerate.
+    # `convert` values and `backfill` defaults are open-ended literals, so they are held as
+    # unvalidated text, like `provenance` (`LiteralText`, aggregate.bluebook).
     value_object "TranslationLiteralText" do
       attribute :value, String
     end
@@ -60,9 +56,7 @@ Hecks.bluebook "Translation" do
       emits "TranslationAggregateRetired"
     end
 
-    # HOW TRANSLATION IS SPELLED. These rows live with the concept
-    # they describe; SyntaxBoot discovers every aggregate-local seed table.
-    # Contexts represented here: File, Translation.
+    # Syntax seed rows for the words this aggregate spells; SyntaxBoot discovers them.
     value_object "KeywordSeed" do
       attribute :word,          String
       attribute :context,       String, admits: "Syntax::Context"

data/lib/hecks/language/translation/translation_aggregate.bluebook

@@ -6,22 +6,8 @@ Hecks.bluebook "Translation" do
 
     identified_by TranslationAggregateName, as: :name
 
-    # `TranslationAggregateName` — a DEDICATED type for the identity
-    # field, not the shared `TranslationName` every non-identity field
-    # below uses. Found live, not by inspection: reusing one value-
-    # object type for BOTH an aggregate's own identity field and a
-    # sibling non-identity field on the same aggregate broke the
-    # single-field-VO identity-unwrap path — the stored `id` came back
-    # as a stringified Hash (`"{:value=>\"Account\"}"`) instead of the
-    # bare scalar (`"Account"`), so a self-reference to this aggregate
-    # could never find the record `Declare` had just created. Reusing
-    # the SAME type across MULTIPLE identity fields (Translation's own
-    # `TranslationEraName`, for both `from` and `to`) is unaffected —
-    # confirmed directly, not assumed — so the real trigger is identity
-    # + non-identity sharing, not reuse itself. A genuine framework bug,
-    # out of scope to fix here; every other self-hosted construct in
-    # this language already avoids it by convention (a dedicated type
-    # per identity field), which this now matches too.
+    # A dedicated identity type: sharing `TranslationName` with a non-identity field breaks the
+    # single-field identity unwrap, storing the id as a stringified Hash instead of a scalar.
     attribute :was,  TranslationName, optional: true
 
     value_object "TranslationAggregateName" do
@@ -47,11 +33,8 @@ Hecks.bluebook "Translation" do
     attribute :rekeys,    list_of(TranslationRekey)
     attribute :backfills, list_of(TranslationBackfill)
 
-    # Field names throughout mirror lib/hecks/bluebook/translation.rb
-    # EXACTLY (`Struct.new(:from, :to)` etc.) — the real Ruby records
-    # TranslationJudge dispatches from, not the builder's own local
-    # parameter names (`move(old_path, to:)`'s `old_path` becomes the
-    # struct's own `from`).
+    # Field names mirror the Struct records in lib/hecks/bluebook/translation.rb, not the
+    # builder's parameter names (`move(old_path, to:)` stores `old_path` as `from`).
     value_object "TranslationRename" do
       attribute :from, TranslationName
       attribute :to,   TranslationName
@@ -199,9 +182,7 @@ Hecks.bluebook "Translation" do
       emits "TranslationBackfillAdded"
     end
 
-    # HOW TRANSLATIONAGGREGATE IS SPELLED. These rows live with the concept
-    # they describe; SyntaxBoot discovers every aggregate-local seed table.
-    # Contexts represented here: TranslationAggregate.
+    # Syntax seed rows for the words this aggregate spells; SyntaxBoot discovers them.
     value_object "KeywordSeed" do
       attribute :word,          String
       attribute :context,       String, admits: "Syntax::Context"

data/lib/hecks/language/world/wiring.bluebook

@@ -7,9 +7,7 @@ Hecks.bluebook "World" do
     # so the bare reference name would collide with it.
     belongs_to World, as: :world_ref
 
-    # THE WORLD IT IS IN, AND THE VERB IT ANSWERS. One world binds one adapter per
-    # verb — that is what a binding IS — so the verb names the wiring, and the
-    # world says whose.
+    # One world binds one adapter per verb, so the verb names the wiring and the world says whose.
     identified_by :world, :verb
 
     attribute :world,    WiringText

data/lib/hecks/language/world/world.bluebook

@@ -59,9 +59,8 @@ Hecks.bluebook "World" do
       emits "WorldDeclared"
     end
 
-    # HOW WORLD IS SPELLED. These rows live with the concept
-    # they describe; SyntaxBoot discovers every aggregate-local seed table.
-    # Contexts represented here: File, World.
+    # Spelling rows for World keywords; SyntaxBoot discovers every
+    # aggregate-local seed table like this one.
     value_object "KeywordSeed" do
       attribute :word,          String
       attribute :context,       String, admits: "Syntax::Context"
@@ -77,10 +76,9 @@ Hecks.bluebook "World" do
       member word: "world",           context: "File",     body: "keywords", inner: "World",          opens: "World",          fills: ""
       member word: "realm",           context: "World",     body: "none", inner: "", opens: "", fills: "realm", calls: "realm_impl"
       member word: "latest",          context: "World",     body: "none", inner: "", opens: "", fills: "latest", calls: "latest_impl"
-      # THE TWO CROSS-CHAPTER DEFAULTS — the same connection string and the
-      # same persistence adapter every chapter of a project repeats, written
-      # once. A chapter's own world (`persisted_by ... database`) and its own
-      # hecksagon bind still win; see docs/implemented/reference/world.md.
+      # The connection string and persistence adapter every chapter of a
+      # project would otherwise repeat, written once here; a chapter's own
+      # world or hecksagon bind still wins.
       member word: "default_database", context: "World", body: "none", inner: "", opens: "", fills: "default_database", calls: "default_database_impl"
       member word: "default_adapter",  context: "World", body: "none", inner: "", opens: "", fills: "default_adapter", calls: "default_adapter_impl"
 

data/lib/hecks/literal.rb

@@ -1,45 +1,13 @@
 module Hecks
-  # The one spelling for a captured Ruby literal on the wire.
-  #
-  # Several `to_h` fields hold a value the author wrote in a bluebook —
-  # `where(status: { eq: "open" })`, `then_set append: { direction: { value:
-  # "credit" } }`, `dispatch ... with: { number: :source }`, an attribute's
-  # `default:` — as text, because the export has to stand on its own and a
-  # String field cannot say "this one was a Symbol". Every such field is the
-  # same question and now gets the same answer.
-  #
-  # It was three answers before, and they disagreed on both axes that matter.
-  # `Mutation#appended_fields` spelled a Symbol bare and everything else
-  # `inspect`; `QuerySpecification.render_value` spelled a Symbol with a colon
-  # and everything else `to_s`. So `:amount` crossed as "amount" in a mutation
-  # and ":amount" in a saga binding — the same value, two spellings, and each
-  # reader had to know which field it was looking at. Worse, `to_s`/`inspect`
-  # on a Hash is Ruby's own rendering, which moved under us: 3.3 writes
-  # `{:value=>"credit"}` and 3.4 writes `{value: "credit"}` for the identical
-  # Hash, so the wire format was silently pinned to an interpreter version.
-  #
-  # Self-describing is the rule, stated once here rather than inherited from
-  # whatever `inspect` happens to do: a symbol wears its colon, a string wears
-  # its quotes, a hash wears `{key: value}` braces, a list wears its brackets,
-  # and a number, a boolean and nil are bare. `read` is the exact inverse, and
-  # is the only thing that should ever take one of these strings apart.
-  # A mutation source that reads the record's own state — `sets :positions,
-  # append: { knights: state(:knights) }`. A bare Symbol in a mutation
-  # source always names a command argument (and imports it as one when
-  # the target's own field carries the same name — `CommandBuilder
-  # #resolve_append_fields!`); before this there was no way to say "the
-  # value this field already holds", so a command could not snapshot its
-  # own record — chess's threefold repetition needs exactly that, a
-  # position copied off the board every ply. Spelled `state(:name)` on
-  # the wire, read back by `Literal.read`; classified `kind: "state"` in
-  # a set's own source (`Behaviour::Mutation#classified_source`).
+  # A mutation source that reads the record's own state: `append: { knights: state(:knights) }`.
+  # A bare Symbol in a mutation source names a command argument, so this is the only way to say it.
   StateRef = Struct.new(:name) do
     def to_s = "state(:#{name})"
   end
 
-  # The `render`/`read` pair the header above describes: `render` turns a
-  # Ruby value into its self-describing wire spelling, `read` is its exact
-  # inverse.
+  # The one wire spelling for a Ruby literal captured from a bluebook: a symbol wears its
+  # colon, a string its quotes, a hash `{key: value}`, a list brackets; the rest are bare.
+  # Stated here, not left to `inspect`, whose Hash rendering differs between Ruby 3.3 and 3.4.
   module Literal
     module_function
 
@@ -63,16 +31,9 @@ module Hecks
       end
     end
 
-    # Read one back. Tolerant of a bare word on purpose: the language stores a
-    # closed set's members and a few hand-written fields as plain text that was
-    # never rendered, and those must stay the strings they are.
+    # Parses a wire spelling back into a Ruby value; the exact inverse of `render`.
+    # A bare word stays a String, since some fields are stored as plain text, never rendered.
     #
-    # The exact inverse of `render`'s `case`, above — one ordered guard per
-    # spelling `render` can produce (plus the bare-word tolerance this
-    # comment already explains). Each guard is a single self-contained
-    # `return`; splitting them into named predicates would just rename
-    # each line without changing what it does, and would separate this
-    # method from the `render` it is the deliberate mirror of.
     # @param text [String, #to_s] wire spelling produced by `render`, or a bare word
     # @return [Object] nil, true, false, Integer, Float, Symbol, StateRef, String,
     #   Hash, or Array — or `text` itself, stripped, when it matches no known spelling
@@ -131,10 +92,7 @@ module Hecks
     # @return [Array<Object>] the parsed values, each read recursively via `read`
     def read_array(raw) = split_items(raw[1..-2]).map { |item| read(item) }
 
-    # Split on the commas that are actually separators — never one inside a
-    # quoted string or a nested brace/bracket. Scanned rather than
-    # `String#split(", ")`, which tore `"a, b"` in half and lost the second
-    # field of anything nested.
+    # Splits on separator commas only, never one inside a quoted string or nested brace/bracket.
     #
     # @param body [String] the text between a literal's outer braces or brackets
     # @return [Array<String>] each item's raw text, stripped, with empty items dropped

data/lib/hecks/mcp_door_scope.rb

@@ -1,42 +1,8 @@
 require_relative "runtime/errors"
 
 module Hecks
-  # What one spawned `bin/hecks_mcp_door` may do: every tool against any domain under
-  # `Storehouse::BOOT_ROOT` (the default), or, in reader mode, only the reader tools
-  # against the domains its spawner named. ADR 0072, decision 2.
-  #
-  # ## Reach, not identity
-  #
-  # This is a capability allowlist, not authentication. It identifies no one and adds no
-  # secret: whoever can spawn the door chooses its mode, and whoever can write to its stdin
-  # gets whatever that mode allows. What it buys is a smaller surface per agent. A reader
-  # door cannot dispatch, cannot run `.behaviors` files, and cannot `Kernel.load` Ruby from
-  # a domain its spawner did not name.
-  #
-  # ## Why `HECKS_DOOR_*` and not `HECKS_MCP_*`
-  #
-  # `McpStdioGuard` refuses every `HECKS_MCP_*` variable except
-  # `HECKS_MCP_TRANSPORT=stdio`, and every argument except `--stdio`, so that no option can
-  # ask a server for another transport. Those refusals belong to ADR 0062. The settings
-  # here live under their own prefix so the guard stays exactly as that ADR describes it,
-  # and an unknown `HECKS_DOOR_*` name is refused here, the same fail-closed way.
-  #
-  # ## The settings
-  #
-  # - `HECKS_DOOR_TOOLS=readers` turns reader mode on. Unset means every tool, as before.
-  #   Any other value refuses to start.
-  # - `HECKS_DOOR_DOMAINS` lists the domains a reader door may name, separated by
-  #   `File::PATH_SEPARATOR` (`:` on Unix), each resolved against `Storehouse::BOOT_ROOT`.
-  #   Required in reader mode and refused without it.
-  #
-  # ## The allowed set is named, not loaded
-  #
-  # The door boots a domain afresh on every call and keeps nothing loaded between calls,
-  # so there is no set of already-loaded domains to check against. The allowed set is the
-  # list the spawner named, resolved to absolute paths at startup. A call's `domain:` is
-  # resolved the same way and compared before anything boots, so a path outside the set
-  # never reaches `Kernel.load`. The comparison is on resolved path text: a symlink under a
-  # named path is followed when that domain boots, as it is for every domain today.
+  # What a spawned bin/hecks_mcp_door may do: every tool by default, or only
+  # reader tools against named domains in reader mode — reach, not identity (ADR 0072).
   class McpDoorScope
     ENV_PREFIX       = "HECKS_DOOR_".freeze
     TOOLS_VARIABLE   = "HECKS_DOOR_TOOLS".freeze
@@ -44,21 +10,12 @@ module Hecks
     READERS          = "readers".freeze
     EXIT_STATUS      = 2
 
-    # The tools a reader door serves. Each reads a domain or the door's own audit log and
-    # writes no domain state. `query` and `state` still append their call to that audit
-    # log. `validate` boots the domain it is given, so it is held to the allowed set like
-    # every other domain-scoped tool. `domains` lists directories and loads nothing.
+    # The tools a reader door serves — each reads a domain or the door's own
+    # audit log and writes no domain state. `validate` still boots its
+    # domain, so it stays bound to the allowed set like every other tool.
     READER_TOOLS = %w[query events state catalog describe validate domains history follow].freeze
 
-    # Reads the door's mode from its environment.
-    #
-    # @param env [Hash{String => String}] the process environment
-    # @return [McpDoorScope] an unrestricted scope when no `HECKS_DOOR_*` variable is set;
-    #   otherwise a reader scope over the named domains
-    # @raise [ArgumentError] with every problem found, one per line, when the settings are
-    #   not a mode this door knows
-    # @raise [Runtime::TypeMismatch] if a named domain resolves outside
-    #   `Storehouse::BOOT_ROOT`
+    # Unrestricted when no HECKS_DOOR_* variable is set.
     def self.from_env(env = ENV)
       problems = setting_problems(env)
       raise ArgumentError, problems.join("\n") unless problems.empty?
@@ -67,15 +24,7 @@ module Hecks
       new(allowed_domains: env[DOMAINS_VARIABLE].split(File::PATH_SEPARATOR).reject(&:empty?))
     end
 
-    # Reads the door's mode, or refuses to start on settings it does not know.
-    #
-    # Everything goes to `stderr`, because stdout carries the MCP protocol.
-    #
-    # @param server [String] the server's name, used as the line prefix
-    # @param env [Hash{String => String}] the process environment
-    # @param stderr [IO] where a refusal is written
-    # @return [McpDoorScope] the door's scope
-    # @raise [SystemExit] with status `EXIT_STATUS` when `from_env` refuses the settings
+    # Refuses to stderr, not stdout, which carries the MCP protocol.
     def self.start!(server:, env: ENV, stderr: $stderr)
       from_env(env)
     rescue ArgumentError, Runtime::TypeMismatch => e
@@ -83,7 +32,6 @@ module Hecks
       exit(EXIT_STATUS)
     end
 
-    # @api private
     def self.setting_problems(env)
       unknown = env.keys.select { |name| name.start_with?(ENV_PREFIX) } - [TOOLS_VARIABLE, DOMAINS_VARIABLE]
       problems = unknown.map do |name|
@@ -92,7 +40,6 @@ module Hecks
       problems + mode_problems(env[TOOLS_VARIABLE], env[DOMAINS_VARIABLE])
     end
 
-    # @api private
     def self.mode_problems(tools, domains)
       if tools.nil?
         domains.nil? ? [] : ["#{DOMAINS_VARIABLE} is set without #{TOOLS_VARIABLE}=#{READERS}; it only narrows a reader door"]
@@ -105,52 +52,28 @@ module Hecks
       end
     end
 
-    # The named domains, resolved against `Storehouse::BOOT_ROOT`; nil when unrestricted.
-    #
-    # @return [Array<String>, nil]
+    # The named domains, resolved against Storehouse::BOOT_ROOT; nil when unrestricted.
     attr_reader :allowed_domains
 
-    # @param allowed_domains [Array<String>, nil] the domains a reader door may name, as
-    #   given; nil for an unrestricted door
-    # @raise [Runtime::TypeMismatch] if a named domain resolves outside `Storehouse::BOOT_ROOT`
     def initialize(allowed_domains:)
       @allowed_domains = allowed_domains&.map { |path| Storehouse.confine!(path, DOMAINS_VARIABLE) }.freeze
     end
 
-    # Tells whether this door runs in reader mode.
-    #
-    # @return [Boolean] true when the spawner set `HECKS_DOOR_TOOLS=readers`
     def restricted?
       !@allowed_domains.nil?
     end
 
-    # Tells whether this door serves a tool.
-    #
-    # @param name [String] the tool name from a `tools/call` request
-    # @return [Boolean] true for every name on an unrestricted door; on a reader door, true
-    #   only for `READER_TOOLS`
     def permits_tool?(name)
       !restricted? || READER_TOOLS.include?(name)
     end
 
-    # Builds the answer to a call for a tool this door does not serve.
-    #
-    # @param name [String] the tool name from a `tools/call` request
-    # @return [Hash{Symbol => Object}] `{ok: false, error:}`, the error naming the mode and
-    #   the tools it serves
     def refusal(name)
       { ok:    false,
         error: "#{name.inspect} is refused: this door runs in reader mode (#{TOOLS_VARIABLE}=#{READERS}), " \
                "which serves only #{READER_TOOLS.join(', ')}" }
     end
 
-    # Checks a call's `domain:` against the allowed set, before anything boots.
-    #
-    # @param domain [String, nil] the caller's `domain:` argument
-    # @return [String, nil] `domain` unchanged, so an unrestricted door boots exactly what
-    #   it did before
-    # @raise [Runtime::TypeMismatch] on a reader door, if `domain` resolves outside
-    #   `Storehouse::BOOT_ROOT` or to a path its spawner did not name
+    # Checked before anything boots, so a path outside the allowed set never reaches Kernel.load.
     def admit_domain!(domain)
       return domain unless restricted?
       return domain if @allowed_domains.include?(Storehouse.confine!(domain, "domain"))
@@ -160,10 +83,6 @@ module Hecks
             "and reads only #{DOMAINS_VARIABLE}: #{@allowed_domains.join(', ')}"
     end
 
-    # The startup warning lines that describe this door's mode.
-    #
-    # @return [Array<String>] empty when unrestricted; on a reader door, what it serves,
-    #   what it refuses, the domains it reads, and that it identifies no one
     def notes
       return [] unless restricted?
 

data/lib/hecks/mcp_stdio_guard.rb

@@ -1,41 +1,8 @@
 require "socket"
 
 module Hecks
-  # The startup gate for the stdio MCP servers in `bin/` (`hecks_mcp_door`,
-  # `hecks_query_ir_mcp`): it refuses to run when the process was set up to
-  # speak to anything but a local parent, and it says on stderr what the
-  # process does and does not protect.
-  #
-  # ## Why a gate and not a comment
-  #
-  # Both servers have no authentication. What keeps a stranger away from
-  # them is that only a process that can spawn them can write to their
-  # stdin. That holds until someone wraps one in `socat TCP-LISTEN:... EXEC:`
-  # or an `inetd`-style listener, which hands the process a network socket
-  # as stdin/stdout without changing a line of the server. The gate turns
-  # that setup into a refusal at startup instead of an exposure nobody
-  # noticed.
-  #
-  # ## What it checks
-  #
-  # - **Arguments** — none, except `--stdio`. A `--port` or `--http` flag is
-  #   refused rather than ignored, so a caller that believes it started a
-  #   network server finds out immediately.
-  # - **Environment** — no `HECKS_MCP_*` variable except
-  #   `HECKS_MCP_TRANSPORT=stdio`. The servers take no configuration, so an
-  #   unknown option in that namespace fails closed.
-  # - **Descriptors** — stdin and stdout must not be internet-protocol sockets
-  #   (`AF_INET` or `AF_INET6`). A pipe, a file, a terminal and a Unix-domain socket all pass;
-  #   the last matters because some MCP clients spawn servers over a
-  #   `socketpair`, which is local to the machine.
-  #
-  # ## What it does not do
-  #
-  # It does not authenticate anyone and it cannot see a proxy that copies
-  # bytes from a network socket into an ordinary pipe. It closes the
-  # configurations that announce themselves; the ADR on MCP authentication
-  # (`docs/decisions/0062-mcp-servers-need-real-authentication-before-any-network-transport.md`)
-  # covers what a network transport would need.
+  # Startup gate for the stdio MCP servers in `bin/`: refuses network sockets, extra flags and
+  # unknown `HECKS_MCP_*` variables. It is not authentication (ADR 0062).
   module McpStdioGuard
     ACCEPTED_ARGS = %w[--stdio].freeze
     ENV_PREFIX    = "HECKS_MCP_".freeze
@@ -71,12 +38,8 @@ module Hecks
       (COMMON_NOTES + notes).map { |line| "#{server}: #{line}" }
     end
 
-    # Refuses to continue on a non-stdio setup.
-    #
-    # A server calls this before it requires anything heavy, so a misconfigured start
-    # fails in milliseconds and before any protocol byte is answered. Everything goes
-    # to `stderr`: stdout carries the MCP protocol, and one stray line there corrupts
-    # the client's framing.
+    # Refuses to continue on a non-stdio setup. Everything goes to `stderr`: stdout
+    # carries the MCP protocol, and a stray line there corrupts the client's framing.
     #
     # @param server [String] the server's name, used as the line prefix
     # @param argv [Array<String>] the command-line arguments