hecks 2.8.0 → 3.0.0

data/lib/hecks/projector/cli_projector.rb

@@ -2,137 +2,77 @@ require_relative "../naming"
 
 module Hecks
   module Projector
-    # A bluebook, projected as its own command-line surface.
+    # Projects a bluebook as its own command-line surface: the verb tree, argument spec
+    # and usage text. Nothing executes here; the generic runner (`hecks run`) parses against it.
     #
-    # Every verb a domain declares is a subcommand; every argument is an
-    # option whose type, whose admitted values and whose required-ness are
-    # already stated in the chapter. A hand-written CLI restates all of it and
-    # then drifts — and the first thing to drift is the help text, which is the
-    # only part anybody reads.
-    #
-    # ## What is projected
-    #
-    # This answers the surface only — the verb tree, the argument spec, the
-    # usage text — and nothing executes here. One small generic runner
-    # (`bin/run`) boots a domain, asks for this, parses against it and
-    # dispatches.
-    #
-    # ## Why project rather than generate
-    #
-    # The alternative was generating an executable per domain, which is what
-    # `bin/project_rust` does for a whole runtime and would be the more
-    # spectacular version of this. It was not taken: a generated program is a
-    # second copy of the dispatch logic, and it needs regenerating on every
-    # bluebook edit — a second tax beside the era gate, paid for a file nobody
-    # reads. Projecting the surface keeps one dispatcher and a help text that
-    # cannot be stale, because it is computed at the moment it is printed.
-    #
-    # ## The typing is the point
-    #
-    # A CLI hands everything over as a String. `sequence.value=99` has to
-    # become the Integer 99 or the runtime refuses it, and the only honest
-    # place to learn that is the value object's own declared field type. A CLI
-    # that guessed — "it looks like a number" — would send 99 for a version
-    # string of "99" and be wrong in a way nobody could see.
+    # Argument types come from the declared field types, never from guessing at the
+    # string: `sequence.value=99` must become 99, and a version "99" must stay a String.
     module CliProjector
       module_function
 
-      # Two namespaces, not one — `{ verbs:, questions:, usage: }`.
-      #
-      # A chapter may legally declare a command and a query of one name: the
-      # language namespaces them and `Banking::Account.Open` is both, in the
-      # corpus, today. A single flat list of subcommands has to pick one, and
-      # picking silently is how `Ticket.Filed` sat undetected in this
-      # repository for a day.
-      #
-      # So a question is asked with `ask`: `bin/run ask account.open`. It is
-      # this codebase own word — `Query::AskOption`, "the ask" — it is
-      # shell-safe where a `?` suffix would be eaten by globbing, and it makes
-      # the collision impossible rather than detected. It also reads as what it
-      # is: everything under `ask` changes nothing.
+      # Projects the verb and question tables and the usage text. Commands and queries are
+      # separate namespaces (a chapter may declare both under one name); ask a query with `ask`.
       #
       # @param bluebook [Bluebook::Chapter] the booted domain to project
-      # @param options [Hash{Symbol => Object}] `:program` (String, defaults to
-      #   `"bin/run"`) is echoed into the usage text; `:verb` (String) and `:ask`
-      #   (Boolean) select one verb's `--help` text instead of the full usage
-      # @return [Hash{Symbol => Object}] `:verbs` and `:questions` map each projected
-      #   name to its spec hash; `:names` maps `:command`/`:question` to an alias table
-      #   (short and full spelling both keying the full name); `:usage` is the
-      #   pre-rendered help text
-      # @raise [Bluebook::DSL::Malformed] if two verbs project to the same command-line
-      #   name
+      # @param options [Hash{Symbol => Object}] `:program` (default `"hecks run"`) for the usage
+      #   text; `:verb` and `:ask` select one verb's `--help` text; `:names` maps a launcher
+      #   name to the command it stands for (`{ "mcp" => "serve_mcp" }`); `:mint_run_keys` makes a
+      #   creating verb's `run` key optional, since the launcher mints it
+      # @return [Hash{Symbol => Object}] `:verbs`, `:questions`, `:names` (alias tables) and
+      #   `:usage` (pre-rendered help text)
+      # @raise [Bluebook::DSL::Malformed] if two verbs project to the same command-line name
       def call(bluebook:, options: {})
         verbs     = {}
         questions = {}
 
-        bluebook.aggregates.each do |aggregate|
-          aggregate.commands.each { |c| claim(verbs, name_for(aggregate, c), command_spec(bluebook, aggregate, nil, c)) }
-          aggregate.queries.each  { |q| claim(questions, name_for(aggregate, q), query_spec(bluebook, aggregate, nil, q)) }
-
-          aggregate.entities.each do |entity|
-            entity.commands.each do |c|
-              claim(verbs, name_for(aggregate, c, entity), command_spec(bluebook, aggregate, entity, c))
-            end
-            entity.queries.each do |q|
-              claim(questions, name_for(aggregate, q, entity), query_spec(bluebook, aggregate, entity, q))
-            end
-          end
-
-          # A port is a verb too, and leaving it off the map was a real gap
-          # rather than a tasteful omission. The runtime has always dispatched
-          # a port operation by exactly the same name as a command — the
-          # projection simply never listed one, so `run_specs` and `file`
-          # answered "no such verb" while working perfectly through Ruby.
-          #
-          # It matters most for the caller with no other door. An agent that
-          # may not shell out reaches this domain only through the projected
-          # CLI, and a port it cannot see is a capability it does not have.
-          aggregate.ports.each do |port|
-            port.operations.each { |o| claim(verbs, name_for(aggregate, o), port_spec(bluebook, aggregate, port, o)) }
-          end
-        end
+        bluebook.aggregates.each { |aggregate| claim_aggregate(verbs, questions, bluebook, aggregate) }
 
-        # A report is a question too, and leaving it off was the same gap the
-        # ports had: `Dispatcher#query` has always answered `Domain.ReportName`,
-        # the projection simply never listed one — so the composed reads worked
-        # from Ruby and did not exist for anybody whose only door is the command
-        # line.
-        #
-        # It matters most for exactly what a report is for. Every other question
-        # here answers with rows and leaves the arithmetic to the reader; a
-        # `group_by` report is the one that counts. An agent that cannot reach
-        # it can list bugs all day and never answer "how are we doing".
-        #
-        # **One dot, not two** — a report belongs to the chapter rather than to any
-        # aggregate (that is what rootless means), so it is addressed
-        # `QualityControl.BugsByStatus` where a query is
-        # `QualityControl::Bug.Queue`. `Dispatcher#query` splits on precisely
-        # that difference.
+        # A report belongs to the chapter, not an aggregate, so it is addressed
+        # `Chapter.Report` (one dot) where a query is `Chapter::Aggregate.Query`.
         bluebook.read_models.each do |model|
           claim(questions, Naming.snake(model.hecks_name), report_spec(bluebook, model))
         end
 
-        # The short spelling, where it cannot be ambiguous. `pizzas
-        # create_pizza` rather than `pizzas order.create_pizza` — the
-        # aggregate is worth typing only when two of them declare the same
-        # verb, and in a one-aggregate domain it never is. Both spellings are
-        # always accepted; `names` maps every accepted one to its canonical
-        # key, and the display name is the shortest that is unambiguous.
-        shorten(verbs)
-        shorten(questions)
+        mint_run_keys(verbs) if options[:mint_run_keys]
+
+        # The display name is the shortest unambiguous one; both spellings are accepted.
+        display_names([verbs, questions], options[:names])
 
         { verbs: verbs, questions: questions,
           names: { command: aliases(verbs), question: aliases(questions) },
           usage: usage(bluebook, verbs, questions, options) }
       end
 
-      # A last segment is claimed only if exactly one verb ends in it. Two
-      # aggregates declaring `Close` keep `customer.close` and `account.close`,
-      # which is the honest answer — a CLI that picked one would be choosing
-      # for the caller.
+      # Claims the verbs and questions of one aggregate and its entities and ports.
+      #
+      # @param verbs [Hash{String => Hash}] the verb map, mutated in place
+      # @param questions [Hash{String => Hash}] the question map, mutated in place
+      # @param bluebook [Bluebook::Chapter] the booted domain
+      # @param aggregate [Bluebook::Aggregate] the aggregate to claim
+      # @return [void]
+      def claim_aggregate(verbs, questions, bluebook, aggregate)
+        aggregate.commands.each { |c| claim(verbs, name_for(aggregate, c), command_spec(bluebook, aggregate, nil, c)) }
+        aggregate.queries.each  { |q| claim(questions, name_for(aggregate, q), query_spec(bluebook, aggregate, nil, q)) }
+
+        aggregate.entities.each do |entity|
+          entity.commands.each do |c|
+            claim(verbs, name_for(aggregate, c, entity), command_spec(bluebook, aggregate, entity, c))
+          end
+          entity.queries.each do |q|
+            claim(questions, name_for(aggregate, q, entity), query_spec(bluebook, aggregate, entity, q))
+          end
+        end
+
+        # Port operations dispatch by the same name as a command, so they are verbs too.
+        aggregate.ports.each do |port|
+          port.operations.each { |o| claim(verbs, name_for(aggregate, o), port_spec(bluebook, aggregate, port, o)) }
+        end
+      end
+
+      # Sets `:short` on each spec: the last segment when exactly one verb ends in it,
+      # else the full name (two aggregates both declaring `Close` keep both spellings).
       #
-      # @param specs [Hash{String => Hash}] the verb or question map being projected,
-      #   mutated in place: each spec hash gains a `:short` key
+      # @param specs [Hash{String => Hash}] the verb or question map, mutated in place
       # @return [void]
       def shorten(specs)
         tails = specs.keys.group_by { |name| name.split(".").last }
@@ -142,30 +82,68 @@ module Hecks
         end
       end
 
-      # Builds the alias table `CliRunner` resolves a typed name against.
+      # Marks the `run` key of each creating verb `minted`: optional, and never filled by a bare
+      # word, since the launcher makes one when it is left out.
+      def mint_run_keys(verbs)
+        verbs.each_value do |spec|
+          next unless spec[:creates]
+
+          spec[:arguments] = spec[:arguments].map do |argument|
+            next argument unless argument[:path] == "run.value"
+
+            argument.merge(required: false, minted: true, note: "minted when omitted")
+          end
+        end
+      end
+
+      # Sets the display name of every spec in each map: shortened, then renamed by `names`.
       #
-      # @param specs [Hash{String => Hash}] a verb or question map whose specs already
-      #   carry `:short` (set by `shorten`)
-      # @return [Hash{String => String}] every accepted spelling — the full name and
-      #   its `:short` form — mapped to the full name
+      # @param maps [Array<Hash{String => Hash}>] the verb and question maps, mutated in place
+      # @param names [Hash, nil] the chapter's launcher names
+      # @return [void]
+      def display_names(maps, names)
+        maps.each do |specs|
+          shorten(specs)
+          rename(specs, names)
+        end
+      end
+
+      # Gives a command the launcher name a chapter's `names` table assigns it.
+      #
+      # The alias replaces the short name in help, so it is listed once; the spelling it
+      # replaced keeps working (`:short_was`, read by `aliases`). A table entry naming no
+      # command in `specs` belongs to the other namespace and is skipped.
+      #
+      # @param specs [Hash{String => Hash}] the verb or question map, mutated in place
+      # @param names [Hash{String, Symbol => String, Symbol}, nil] launcher name to command name
+      # @return [void]
+      # @raise [Bluebook::DSL::Malformed] if a launcher name is already another command's name
+      def rename(specs, names)
+        Hash(names).each do |launcher_name, command|
+          found = specs.find { |key, spec| [key, spec[:short]].include?(command.to_s) }
+          next unless found
+
+          taken = specs.values.any? { |spec| spec[:short] == launcher_name.to_s }
+          raise Bluebook::DSL::Malformed, "launcher name #{launcher_name.to_s.inspect} is already a command" if taken
+
+          found.last[:short_was] = found.last[:short]
+          found.last[:short]     = launcher_name.to_s
+        end
+      end
+
+      # Maps every accepted spelling (full name, `:short` and a renamed command's old short
+      # name) to the full name.
       def aliases(specs)
         specs.each_with_object({}) do |(name, spec), map|
           map[name]         = name
           map[spec[:short]] = name
+          map[spec[:short_was]] = name if spec[:short_was]
         end
       end
 
-      # A name is claimed once. A command and a query of one name are legal in
-      # a chapter — the language namespaces them — and ambiguous as
-      # subcommands. Refused here rather than silently resolving to whichever
-      # was walked first, which is how `Ticket.Filed` (a command) and
-      # `Ticket.Filed` (a query) sat undetected until something flattened them.
+      # Stores `spec` under `name`, refusing a second claim rather than silently
+      # keeping whichever verb was walked first.
       #
-      # @param verbs [Hash{String => Hash}] the verb or question map being built,
-      #   mutated in place
-      # @param name [String] the command-line name this spec claims
-      # @param spec [Hash{Symbol => Object}] the spec hash to store under `name`
-      # @return [void]
       # @raise [Bluebook::DSL::Malformed] if `name` is already claimed by another verb
       def claim(verbs, name, spec)
         if verbs.key?(name)
@@ -177,15 +155,7 @@ module Hecks
         verbs[name] = spec
       end
 
-      # Builds the dotted command-line name for one verb: `aggregate[.entity].verb`,
-      # snake-cased.
-      #
-      # @param aggregate [Bluebook::Aggregate] the verb's owning aggregate
-      # @param verb [Bluebook::Command, Bluebook::Query, Bluebook::PortOperation]
-      #   the command, query or port operation being named
-      # @param entity [Bluebook::Entity, nil] the entity the verb is declared on, or `nil`
-      #   for an aggregate-level verb
-      # @return [String] the dotted, snake-cased command-line name
+      # The dotted command-line name, `aggregate[.entity].verb`, snake-cased.
       def name_for(aggregate, verb, entity = nil)
         parts = [Naming.snake(aggregate.hecks_name)]
         parts << Naming.snake(entity.hecks_name) if entity
@@ -193,39 +163,15 @@ module Hecks
         parts.join(".")
       end
 
-      # Builds the verb's fully-qualified language name, `Bluebook::Aggregate[.Entity].Verb`,
-      # for display in help text.
-      #
-      # @param bluebook [Bluebook::Chapter] the verb's owning chapter
-      # @param aggregate [Bluebook::Aggregate] the verb's owning aggregate
-      # @param verb [Bluebook::Command, Bluebook::Query, Bluebook::PortOperation]
-      #   the command, query or port operation being named
-      # @param entity [Bluebook::Entity, nil] the entity the verb is declared on, or `nil`
-      #   for an aggregate-level verb
-      # @return [String] the fully-qualified name, as the language spells it
+      # The verb's language name, `Chapter::Aggregate[.Entity].Verb`, for help text.
       def fqn(bluebook, aggregate, verb, entity = nil)
         [bluebook.name, "::", aggregate.hecks_name, ".",
          entity ? "#{entity.hecks_name}." : "", verb.hecks_name].join
       end
 
-      # The arguments a receiver adds, before any verb-specific one. Shared by
-      # `command_spec` and `port_spec` — a port operation always addresses an
-      # aggregate record (`port_spec` passes `receiver: :aggregate`, never
-      # `:entity` or `nil`, because a port is declared on an aggregate, never
-      # an entity), and this is exactly the same "how do I name the record"
-      # question a command with a receiver already answers, so it is answered
-      # once, here, rather than duplicated.
-      #
-      # `nil` — a creating command — takes none: there is no existing record
-      # yet for `to=` to name.
-      #
-      # @param receiver [Symbol, nil] `:entity`, `:aggregate`, or `nil` for a creating
-      #   command that names no existing record
-      # @param aggregate [Bluebook::Aggregate] the aggregate the record belongs to
-      # @param entity [Bluebook::Entity, nil] the entity to name, required when
-      #   `receiver` is `:entity`
-      # @return [Array<Hash{Symbol => Object}>] the `to`/`to.aggregate`+`to.entity` option
-      #   specs this receiver needs, or `[]` for `nil`
+      # The options that name the record a verb acts on, before its own arguments.
+      # `nil` (a creating command) takes none: there is no record yet.
+      # Ports always pass `:aggregate`, since a port is declared on an aggregate.
       def receiver_options(receiver, aggregate, entity)
         case receiver
         when :entity
@@ -243,20 +189,6 @@ module Hecks
         end
       end
 
-      # ── one verb ──────────────────────────────────────────────────────
-
-      # Projects one command into the spec `verb_help` and `CliRunner` both read.
-      #
-      # @param bluebook [Bluebook::Chapter] the command's owning chapter
-      # @param aggregate [Bluebook::Aggregate] the command's owning aggregate
-      # @param entity [Bluebook::Entity, nil] the entity the command is declared on, or
-      #   `nil` for an aggregate-level command
-      # @param command [Bluebook::Command] the command being projected
-      # @return [Hash{Symbol => Object}] `:verb` (fully-qualified name), `:kind` (`:command`),
-      #   `:summary`, `:role` (String, nil if the command declares none), `:role_gated`
-      #   (Boolean), `:creates` (Boolean), `:receiver` (`:entity`, `:aggregate` or `nil`),
-      #   `:legacy_receiver` (`:id` or `nil`), `:legacy_arguments`, `:refusals`
-      #   (see `refusals`) and `:arguments` (see `options_for`)
       def command_spec(bluebook, aggregate, entity, command)
         holder    = entity || aggregate
         arguments = command.attributes.flat_map { |a| options_for(a, holder, aggregate) }
@@ -266,16 +198,9 @@ module Hecks
                       (command.creates? ? nil : :aggregate)
                     end
 
-        # The receiver is not a command argument. An aggregate command names
-        # its record through to; an entity command needs both the aggregate
-        # record and the entity element within it. Keeping those paths in the
-        # projected option list makes the human-facing request complete while
-        # CommandRequest can remove them before it builds with: from the
-        # command's declared facts.
-        #
-        # Existing aggregate scripts may still spell the receiver id=... .
-        # That alias is deliberately hidden from help and recorded separately
-        # as legacy_arguments; new help and examples teach only to=... .
+        # The receiver paths stay in the projected option list so the request is complete;
+        # CommandRequest strips them before building `with:`. `id=...` is still accepted
+        # for aggregate receivers but hidden from help, which teaches only `to=...`.
         arguments = receiver_options(receiver, aggregate, entity) + arguments
         legacy_arguments = receiver == :aggregate ? [{ path: "id", type: "String", required: true }] : []
 
@@ -284,55 +209,22 @@ module Hecks
           creates: command.creates?,
           receiver: receiver, legacy_receiver: (receiver == :aggregate ? :id : nil),
           legacy_arguments: legacy_arguments,
-          refusals: refusals(command, holder), arguments: arguments }
+          refusals: refusals(command, holder), requirements: requirements(command),
+          arguments: arguments }
       end
 
-      # A port operation reads as a verb but reports as a boundary.
-      #
-      # `creates: false` because it makes no record, and `refusals: []`
-      # because it has none in the sense every other verb means: a command's
-      # refusals are sentences the chapter will say back to you, and an
-      # outbound operation's failure is somebody else's sentence, unknowable
-      # from here.
-      #
-      # The summary names both endings, which is the one thing a caller most
-      # needs and cannot infer. `run_specs` looks like it either works or
-      # errors; what it actually does is answer `SpecsCompleted` even when the
-      # suite is red, and refuse only when rspec could not run. Somebody
-      # reading `--help` should not have to open the hecksagon to find that
-      # out.
-      #
-      # @param bluebook [Bluebook::Chapter] the port's owning chapter
-      # @param aggregate [Bluebook::Aggregate] the aggregate the port is declared on
-      # @param port [Bluebook::DomainPort] the port the operation is declared on
-      # @param operation [Bluebook::PortOperation] the operation being projected
-      # @return [Hash{Symbol => Object}] `:verb` (the `Aggregate.port.operation` name),
-      #   `:kind` (`:command`), `:creates` (`false`), `:receiver` (`:aggregate`),
-      #   `:refusals` (`[]`), `:role` (String, who calls whom through the port),
-      #   `:role_gated` (`false`), `:summary` (see `port_summary`) and `:arguments`
-      #   (see `options_for`)
+      # A port operation reads as a verb but reports as a boundary: it creates no
+      # record, and an outbound failure is the other side's sentence, so `refusals` is empty.
       def port_spec(bluebook, aggregate, port, operation)
         arguments = receiver_options(:aggregate, aggregate, nil) +
                     operation.attributes.flat_map { |a| options_for(a, aggregate, aggregate) }
 
-        # The wire name carries the port, the typed name does not.
-        #
-        # `Dispatcher#dispatch` splits a verb into head and sub and looks the
-        # head up as a port, so a port operation is addressed
-        # `Aggregate.Port.Operation` — three parts where a command has two.
-        # But nobody should have to type `sweep.toolchain.run_specs`: which
-        # port a verb goes out through is wiring, and the caller's business is
-        # what they want done. So the projection spells the verb in full and
-        # names it short, which is the same split `shorten` already makes.
+        # `Dispatcher#dispatch` looks the head up as a port, so the wire name is
+        # `Aggregate.Port.Operation`; the short name (see `shorten`) hides the port.
         { verb: [fqn(bluebook, aggregate, operation).sub(/\.[^.]+\z/, ""), port.name, operation.hecks_name].join("."),
           kind: :command, creates: false, receiver: :aggregate, refusals: [],
-          # `role:` here is descriptive text, not an authorization gate —
-          # who calls whom through the port, for `--help`/`verb_help`'s
-          # "issued by" line. A port operation never reaches
-          # `CommandRules::Authorization#refuse_role_mismatch` (only
-          # `CommandInterpreter`/`EntityInterpreter` call it, never the port
-          # dispatch path), so `role_gated: false` always, unlike
-          # `command_spec` where the same key name means a real one.
+          # `role:` is help text only; port dispatch never reaches the role check,
+          # so `role_gated` is always false here.
           role: if operation.outbound?
                   "#{aggregate.hecks_name} asking #{port.name}"
                 else
@@ -342,26 +234,16 @@ module Hecks
           summary: port_summary(port, operation), arguments: arguments }
       end
 
-      # Names both endings a port operation can have: what an inbound `tells` records,
-      # or what an outbound `asks` came back with and what it said instead.
-      #
-      # @param port [Bluebook::DomainPort] the operation's owning port
-      # @param operation [Bluebook::PortOperation] the operation being summarized
-      # @return [String] one line, worded for `--help`
+      # Names both endings of a port operation, since `--help` is where a caller
+      # learns that e.g. a spec run answers `SpecsCompleted` even when the suite is red.
       def port_summary(port, operation)
         return "#{port.name} reports it; emits #{operation.emits.join(', ')}" unless operation.outbound?
 
         "Ask #{port.name} — answers #{operation.answers}, refuses #{operation.refuses}"
       end
 
-      # A rootless report takes nothing; a rooted one takes the id of the
-      # record it is a view of, under the name the model gave that reference.
-      #
-      # @param bluebook [Bluebook::Chapter] the report's owning chapter
-      # @param model [Bluebook::ReadModel] the report being projected
-      # @return [Hash{Symbol => Object}] `:verb` (`Chapter.ReportName`), `:kind`
-      #   (`:query`), `:summary` and `:arguments` (`[]`, or one required id option
-      #   named after the model's `reference_name` when it declares a `reference_target`)
+      # A rootless report takes nothing; a rooted one takes the id of the record it
+      # is a view of, under the name the model gave that reference.
       def report_spec(bluebook, model)
         arguments =
           if model.reference_target
@@ -375,15 +257,6 @@ module Hecks
           summary: model.description, arguments: arguments }
       end
 
-      # Projects one query into the spec `verb_help` and `CliRunner` both read.
-      #
-      # @param bluebook [Bluebook::Chapter] the query's owning chapter
-      # @param aggregate [Bluebook::Aggregate] the query's owning aggregate
-      # @param entity [Bluebook::Entity, nil] the entity the query is declared on, or
-      #   `nil` for an aggregate-level query
-      # @param query [Bluebook::Query] the query being projected
-      # @return [Hash{Symbol => Object}] `:verb` (fully-qualified name), `:kind`
-      #   (`:query`), `:summary` and `:arguments` (see `options_for`)
       def query_spec(bluebook, aggregate, entity, query)
         arguments = Array(query.to_h[:attributes]).flat_map do |declared|
           attribute = query.attributes.find { |a| a.name.to_s == declared[:name].to_s }
@@ -391,38 +264,19 @@ module Hecks
         end
 
         { verb: fqn(bluebook, aggregate, query, entity), kind: :query,
-          summary: query.description, arguments: arguments }
+          summary: query.description, arguments: arguments, returns: query.returns }
       end
 
-      # ── one argument, flattened ───────────────────────────────────────
-
-      # A value object becomes one option per field, dotted. `commit` typed
-      # `CommitRef` is `--commit.value`, because that is the shape the runtime
-      # wants and a flat `--commit` would have to guess which field it meant.
-      # Single-field value objects — almost all of them — read fine either way,
-      # and the runner accepts the short form for exactly those.
-      # Recursive, and it has to be. A value object may hold another one —
-      # pizzas' `Pizza` holds a `Price` and a `Size` — so stopping after one
-      # level produced `pizza.price_cents=1500` and sent the string "1500"
-      # where `{ cents: 1500 }` belonged.
-      #
-      # The runtime took it. `qa/FINDINGS.md` #2 is exactly that gap —
-      # `Value::Coercion.build` does not validate nested value objects — so a
-      # one-level CLI is not merely inconvenient, it is a machine for writing
-      # malformed records into a real store, which is what it did on its first
-      # run against the pizzas database.
+      # Flattens an attribute into one option per leaf field. A value object becomes
+      # dotted options (`--commit.value`), recursing into nested value objects so
+      # `{ cents: 1500 }` is never sent as the string "1500".
       #
       # @param attribute [Bluebook::Attribute] the field being projected
-      # @param holder [Bluebook::Aggregate, Bluebook::Entity, Class] the construct
-      #   `attribute` is declared on; a `Bluebook::ValueObject` subclass on a recursive call
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity, Class] what declares `attribute`
       # @param aggregate [Bluebook::Aggregate] the top-level aggregate, kept across recursion
-      #   so a nested value object can still be found
-      # @param prefix [String, nil] the dotted path built so far, `nil` at the top level
-      # @param optional [Boolean, nil] whether an enclosing field already makes this one
-      #   optional; `nil` defers to `attribute.optional?`
-      # @return [Array<Hash{Symbol => Object}>] one option spec per leaf field, each with
-      #   `:path`, `:type`, `:required`, and optionally `:note`, `:enum`, `:pattern`,
-      #   `:default`, `:list`
+      # @param prefix [String, nil] the dotted path built so far
+      # @param optional [Boolean, nil] whether an enclosing field already makes this one optional
+      # @return [Array<Hash{Symbol => Object}>] one option spec per leaf field
       def options_for(attribute, holder, aggregate, prefix = nil, optional = nil)
         path = [prefix, attribute.name].compact.join(".")
         optional ||= attribute.optional?
@@ -431,19 +285,8 @@ module Hecks
         value_object = value_object_for(attribute, holder, aggregate)
         return [scalar_option(path, attribute, optional)] unless value_object
 
-        # A list says so, all the way down to its leaves.
-        #
-        # Without this a `list_of(Tag)` projected exactly like a single Tag:
-        # one option, `tags.value`, indistinguishable from a scalar. So the
-        # help said to pass one, `CliDoor#bury` overwrote the leaf each time,
-        # and passing two tags stored the second and lost the first without
-        # saying anything. A missing argument is refused loudly; a forgotten
-        # one is not, which makes it the more expensive of the two by far.
-        #
-        # The flag is carried on the leaf rather than kept beside the
-        # attribute because the leaf is all `CliDoor` ever sees — it is handed
-        # a path and a spec, and reuniting them with the attribute that
-        # produced them would be a lookup that exists only to answer this.
+        # The list flag rides on each leaf: without it a repeated flag overwrote the
+        # leaf silently, and CliDoor only ever sees a path and a spec.
         fields = value_object.attributes.flat_map do |field|
           nested = value_object_for(field, value_object, aggregate)
           next options_for(field, value_object, aggregate, path, optional) if nested
@@ -457,59 +300,31 @@ module Hecks
         fields.map { |option| option.merge(list: true, note: [option[:note], "repeatable"].compact.join("; ")) }
       end
 
-      # Projects a `reference_to` attribute as the id of the record it points at.
-      #
-      # @param attribute [Bluebook::Attribute] a `reference?` attribute
-      # @return [Hash{Symbol => Object}] `:path`, `:type` (`"String"`), `:required` and
-      #   `:note`
       def reference_option(attribute)
         { path: attribute.name.to_s, type: "String", required: !attribute.optional?,
           note: "id of a #{attribute.type.target_name}" }
       end
 
-      # Projects one leaf field — a plain attribute, or one field of a flattened
-      # value object.
-      #
-      # @param path [String] the dotted option path this field is reached at
-      # @param field [Bluebook::Attribute] the field being projected
-      # @param optional [Boolean] whether this option may be omitted
-      # @param enum [Array<Object>] the closed set of values this field admits, `[]` for
-      #   an open field
-      # @return [Hash{Symbol => Object}] `:path`, `:type`, `:required`, plus `:enum` when
-      #   `enum` is non-empty, `:pattern` when `field` declares one, and `:default` when
-      #   `field` declares a non-nil one
+      # A `list_of` scalar carries `list: true, words: true`: the launcher reads a comma-separated
+      # value or a repeated name as the list's elements, since the runtime refuses a lone scalar.
       def scalar_option(path, field, optional, enum: [])
         option = { path: path, type: field.type.to_s, required: !optional }
+        option.merge!(list: true, words: true, note: "list: comma-separated or repeated") if field.list?
         option[:enum]    = enum          unless enum.empty?
         option[:pattern] = field.pattern if field.respond_to?(:pattern) && field.pattern
         option[:default] = field.default if field.respond_to?(:default) && !field.default.nil?
         option
       end
 
-      # The values a `one_of` value object's field is closed to, for the option's
-      # `:enum`.
-      #
-      # @param value_object [Class] a `Bluebook::ValueObject` subclass
-      # @param field [Bluebook::Attribute] the value object's field being projected
-      # @return [Array<Object>] the distinct values every declared member gives this
-      #   field, or `[]` when the value object declares no closed set
+      # The values a `one_of` value object's field is closed to, or `[]` for an open one.
       def closed_members(value_object, field)
         return [] unless value_object.closed_set?
 
         value_object.members.filter_map { |member| member[field.name] }.uniq
       end
 
-      # Finds the value object type an attribute declares, if any — the fork between
-      # `scalar_option` (one option) and recursing into `options_for` (one option per
-      # field).
-      #
-      # @param attribute [Bluebook::Attribute] the field whose type is being resolved
-      # @param holder [Bluebook::Aggregate, Bluebook::Entity, Class, nil] the construct
-      #   `attribute` is declared on, searched first
-      # @param aggregate [Bluebook::Aggregate, nil] the top-level aggregate, searched when
-      #   `holder` does not declare the value object itself
-      # @return [Class, nil] the matching `Bluebook::ValueObject` subclass, or `nil` if
-      #   `attribute`'s type names no value object in scope
+      # The `Bluebook::ValueObject` subclass an attribute's type names, searching
+      # `holder` then `aggregate`, or `nil` for a plain scalar.
       def value_object_for(attribute, holder, aggregate)
         [holder, aggregate].compact.each do |scope|
           next unless scope.respond_to?(:value_objects)
@@ -520,15 +335,8 @@ module Hecks
         nil
       end
 
-      # Every way this verb can say no, in the chapter's own words — printed
-      # by `--help` before the caller spends a dispatch finding out.
-      #
-      # @param command [Bluebook::Command] the command whose refusals are being projected
-      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the aggregate or entity the
-      #   command's lifecycle guard, if any, is checked against
-      # @return [Array<String>] one sentence per way the command can refuse: a lifecycle
-      #   state mismatch, a missing referenced record per `reference_to` attribute, and
-      #   each declared `given`'s description, in that order
+      # The conditions that refuse the verb when they hold, in the chapter's own words: a
+      # lifecycle state mismatch and a missing referenced record per `reference_to`.
       def refusals(command, holder)
         out = []
         lifecycle = holder.lifecycle
@@ -537,28 +345,21 @@ module Hecks
         end.flatten.uniq
         out << "#{lifecycle.field} is not #{froms.join(' or ')}" if froms && !froms.empty?
         out += command.attributes.select(&:reference?).map { |r| "no #{r.type.target_name} has that #{r.name}" }
-        out + command.givens.map(&:description)
+        out
       end
 
-      # ── the help ──────────────────────────────────────────────────────
+      # The conditions the verb needs: each `given` states what must hold, so the verb is
+      # refused unless it does.
+      def requirements(command) = command.givens.map(&:description)
 
       # Renders the full verb/question table, or one verb's `--help` text when
       # `options[:verb]` names one.
-      #
-      # @param bluebook [Bluebook::Chapter] the projected chapter, for its name and vision
-      #   line
-      # @param verbs [Hash{String => Hash}] the projected, `shorten`ed command map
-      # @param questions [Hash{String => Hash}] the projected, `shorten`ed query map
-      # @param options [Hash{Symbol => Object}] `:program` (String), `:verb` (String, nil)
-      #   and `:ask` (Boolean) — see `call`
-      # @return [String] the rendered help text
       def usage(bluebook, verbs, questions, options)
-        program = options[:program] || "bin/run"
+        program = options[:program] || "hecks run"
         only    = options[:verb]
 
-        # Which namespace, when both hold the name. `options[:ask]` says so;
-        # without it a `--help` for a question would print the command that
-        # shares its name, which banking has and which is how this was found.
+        # `options[:ask]` picks the namespace when both hold the name; without it a
+        # question's `--help` would print the command sharing its name.
         if only
           pool = options[:ask] ? questions : verbs
           key  = aliases(pool)[only] || (options[:ask] ? nil : aliases(questions)[only])
@@ -582,40 +383,19 @@ module Hecks
         out.join("\n")
       end
 
-      # Picks one verb whose full spelling differs from its short one, to show the
-      # caller both forms exist.
-      #
-      # @param verbs [Hash{String => Hash}] the projected, `shorten`ed command map
-      # @return [String] `"<short> is also <full>"`, or `""` if every verb's short form
-      #   is its full name (a one-aggregate domain, where no name ever collides)
+      # One verb whose full spelling differs from its short one, or `""` when none does.
       def example_qualified(verbs)
         name, spec = verbs.find { |key, value| key != value[:short] } || verbs.first
         name ? "#{spec[:short]} is also #{name}" : ""
       end
 
-      # A query's `description` is written as a paragraph — it argues for why
-      # the list is worth reading. A verb table wants the first sentence of
-      # that argument; `--help` still prints the whole thing.
-      #
-      # @param text [String, nil] the full description, or `nil`
-      # @return [String] the text up to and including its first `.`, or `""` for `nil`
+      # The verb table wants a query description's first sentence; `--help` prints all.
       def first_sentence(text)
         text.to_s.split(/(?<=\.)\s/).first.to_s
       end
 
-      # Four text blocks, in fixed display order — meta (name/kind/role),
-      # invocation, arguments, refusals. Each block is independent of the
-      # others' content (only the output order is fixed, and stays fixed
-      # below), so each is its own method returning the lines it
-      # contributes — `[]` when it contributes none — concatenated in the
-      # same order the original inline version built them in.
-      #
-      # @param program [String] how the caller was invoked, echoed in the invocation line
-      # @param name [String] the verb's short display name
-      # @param spec [Hash{Symbol => Object}] the verb or question's projected spec (see
-      #   `command_spec`, `port_spec`, `report_spec` or `query_spec`)
-      # @param ask [Boolean] whether this is a question, reached through `ask`
-      # @return [String] the verb's full `--help` text
+      # Four independent blocks, concatenated in fixed order: meta, invocation,
+      # arguments, refusals.
       def verb_help(program, name, spec, ask: false)
         out = verb_help_meta_lines(name, spec)
         out.concat(verb_help_invocation_lines(program, name, spec, ask))
@@ -624,12 +404,6 @@ module Hecks
         out.join("\n")
       end
 
-      # Renders the name/summary heading, plus the dispatched or read verb and issuing
-      # role when the spec declares them.
-      #
-      # @param name [String] the verb's short display name
-      # @param spec [Hash{Symbol => Object}] the verb or question's projected spec
-      # @return [Array<String>] the meta block's lines
       def verb_help_meta_lines(name, spec)
         out = ["#{name} — #{spec[:summary]}", ""]
         out << "dispatches #{spec[:verb]}" if spec[:kind] == :command
@@ -638,26 +412,11 @@ module Hecks
         out
       end
 
-      # Renders the one-line example invocation, with every argument's path as a
-      # placeholder.
-      #
-      # @param program [String] how the caller was invoked
-      # @param name [String] the verb's short display name
-      # @param spec [Hash{Symbol => Object}] the verb or question's projected spec, read
-      #   for `:arguments`
-      # @param ask [Boolean] whether to show the `ask` form of the invocation
-      # @return [Array<String>] the invocation block's lines
       def verb_help_invocation_lines(program, name, spec, ask)
         invocation = ask ? "#{program} ask #{name}" : "#{program} #{name}"
         ["", "  #{invocation}#{spec[:arguments].map { |a| " #{a[:path]}=…" }.join}", ""]
       end
 
-      # Renders one line per declared argument: its type, admitted values, pattern,
-      # default and whether it is optional.
-      #
-      # @param spec [Hash{Symbol => Object}] the verb or question's projected spec, read
-      #   for `:arguments`
-      # @return [Array<String>] the argument block's lines, `[]` if the verb takes none
       def verb_help_argument_lines(spec)
         return [] if spec[:arguments].empty?
 
@@ -675,15 +434,10 @@ module Hecks
         lines << ""
       end
 
-      # Renders the "refused when:" block, one line per way the verb can say no.
-      #
-      # @param spec [Hash{Symbol => Object}] the verb or question's projected spec, read
-      #   for `:refusals`
-      # @return [Array<String>] the refusal block's lines, `[]` if the verb declares none
       def verb_help_refusal_lines(spec)
-        return [] if Array(spec[:refusals]).empty?
-
-        ["refused when:", *spec[:refusals].map { |refusal| "  #{refusal}" }, ""]
+        [["refused when:", spec[:refusals]], ["refused unless:", spec[:requirements]]].flat_map do |heading, items|
+          Array(items).empty? ? [] : [heading, *items.map { |item| "  #{item}" }, ""]
+        end
       end
     end
   end