hecks 2.8.0 → 2.9.0

data/lib/hecks/naming.rb

@@ -1,19 +1,9 @@
 module Hecks
-  # Every derived-name and identity-joining rule the language relies on —
-  # pluralisation/singularisation, snake/Pascal casing, dotted-path and verb
-  # splitting, and the command/event reference rewrites — collected here so
-  # two readers never invent two different spellings for the same
-  # derivation.
+  # Derived-name and identity-joining rules: casing, pluralisation, dotted-path
+  # and verb splitting, command/event reference rewrites.
   module Naming
-    # What separates the parts of a derived identity.
-    #
-    # An identity of several parts is their join, and the join has to be spelled the
-    # same everywhere or two readers name two different records off one declaration.
-    # It was spelled three ways at once here — "::" for an aggregate under a
-    # chapter, "." for everything under an aggregate, "#" for the three that keyed
-    # off position — and each was written where it happened to be needed. Once the
-    # runtime derived the same identity, the runtime made a fourth, and a reference
-    # that resolved by string comparison found nothing.
+    # What separates the parts of a derived identity. Every reader must spell the
+    # join the same way, or string-compared references resolve to nothing.
     IDENTITY_JOIN = ":".freeze
 
     module_function
@@ -35,9 +25,8 @@ module Hecks
       type.to_s.split("::").last.to_s
     end
 
-    # snake_case -> PascalCase. The name a synthesised closed-set value object
-    # takes when an attribute declares one inline. The derivation is part of
-    # the IR contract: the same bluebook must always produce the same name.
+    # snake_case -> PascalCase. Names a closed-set value object synthesised from an
+    # inline attribute; the derivation is part of the IR contract.
     #
     # @param text [String, Symbol, #to_s] a snake_case (or already Pascal) name
     # @return [String] the PascalCase form
@@ -56,15 +45,8 @@ module Hecks
           .downcase
     end
 
-    # An identifier as a person would say it — `ATMCard` -> "ATM card",
-    # `AccrueInterest` -> "Accrue interest", `daily_limit` -> "Daily
-    # limit", `Back office` -> "Back office". The same two word-boundary
-    # splits `snake` uses, with a space instead of an underscore — plus
-    # the one thing `snake` cannot give back: an all-caps run stays an
-    # acronym ("ATM", "KYC") instead of being lowercased into a word
-    # nobody says ("Atm"). First word capitalized, the rest lowercased,
-    # so a headword reads as sentence case whatever casing it was
-    # declared in.
+    # An identifier as a sentence-cased phrase: `ATMCard` -> "ATM card",
+    # `daily_limit` -> "Daily limit". All-caps runs stay acronyms.
     #
     # @param text [String, Symbol, #to_s] a Pascal-, camel-, or snake-case identifier
     # @return [String] the space-separated, sentence-cased phrase
@@ -81,9 +63,7 @@ module Hecks
       end.join(" ")
     end
 
-    # Joins items into the Oxford-comma list — "A, B, and C" / "A or B" —
-    # every English sentence a projection writes wants; lived in
-    # `NarrateProjector` alone until a second projection needed it.
+    # Joins items into an Oxford-comma list: "A, B, and C" / "A or B".
     #
     # @param items [Array<#to_s>] the items to join
     # @param conj [String] the word before the last item, such as `"and"` or `"or"`
@@ -98,9 +78,8 @@ module Hecks
       end
     end
 
-    # Picks the article for `word` by its first letter — the vowel-letter
-    # heuristic, safe here for the same reason `Projections::Statements#article`
-    # gives: a construct name is a plain word, never "hour" or "university".
+    # Picks the article for `word` by its first letter. Construct names are plain
+    # words, never "hour" or "university", so the vowel-letter heuristic holds.
     #
     # @param word [String, Symbol, #to_s] the word the article precedes
     # @return [String] `"an"` if `word` starts with a vowel letter, `"a"` otherwise
@@ -108,15 +87,8 @@ module Hecks
       %w[a e i o u].include?(word.to_s[0].to_s.downcase) ? "an" : "a"
     end
 
-    # The name a collection of something takes.
-    #
-    # There were two of these and one was wrong. A read model's gathered heads
-    # derived their name with a bare `"#{snake(target)}s"`, so the meta-domain's
-    # own whole-bluebook read model handed back `querys`, `entitys`, `policys`
-    # and `dispatchs` — and every check was green, because the checks compared
-    # the wrong rule against itself. Agreement is not correctness; it never was.
-    #
-    # So: one pluraliser, three rules, and every collection name flows through it.
+    # The name a collection of something takes: "y" -> "ies", sibilants take "es",
+    # everything else "s". Every collection name must flow through this one rule.
     #
     # @param text [String, Symbol, #to_s] a singular name
     # @return [String] the pluralised name
@@ -128,13 +100,9 @@ module Hecks
       "#{word}s"
     end
 
-    # `has_many`'s undo — the plural written, back to the singular the target
-    # aggregate is actually named. Deliberately the crude half of a pair: `plural`
-    # above earns its precision (three suffix rules) because getting a collection
-    # name wrong reads as a typo forever ; this only ever recovers a name someone
-    # already wrote as a real aggregate, so "ies -> y, trailing s dropped" is the
-    # whole rule — enough for `has_many Invoices` to resolve to the aggregate
-    # actually named Invoice.
+    # Recovers the singular aggregate name from a `has_many` plural. Deliberately
+    # crude ("ies" -> "y", sibilant "es" and trailing "s" dropped): it only has to
+    # find a name someone already wrote.
     #
     # @param text [String, Symbol, #to_s] a plural name
     # @return [String] the singularised name
@@ -142,15 +110,8 @@ module Hecks
       word = text.to_s
       return "#{word[0..-4]}y" if word.length > 3 && word.end_with?("ies")
 
-      # `plural`'s own second rule adds "es" (not bare "s") after
-      # s/x/z/ch/sh — undone here the same way, or a word `plural`
-      # itself would have suffixed with "es" comes back missing its
-      # own trailing letter ("Boxes" -> "Boxe", not "Box") once this
-      # only ever knew how to drop a bare "s". Checked before the
-      # bare-"s" rule below: stripping "es" first and confirming what
-      # is left actually ends in one of those five shapes is what
-      # keeps an ordinary "-es" word (e.g. "Invoices" -> "Invoice")
-      # from also losing a letter it never doubled.
+      # Undo `plural`'s "es" after s/x/z/ch/sh before the bare-"s" rule, so "Boxes"
+      # gives "Box" while "Invoices" still gives "Invoice".
       return word[0..-3] if word.length > 3 && word.end_with?("es") && word[0..-3].match?(/(s|x|z|ch|sh)\z/)
 
       return word[0..-2] if word.length > 1 && word.end_with?("s")
@@ -199,29 +160,9 @@ module Hecks
 
     # Splits a domain-qualified verb into its domain, aggregate, and command parts.
     #
-    # Domain, aggregate, then the REST dot-joined into one command path.
-    #
-    # The `::` boundary between domain and aggregate is unambiguous by
-    # construction — every caller here has already prefixed the domain
-    # itself (`PolicyInterpreter#deliver`, `SagaInterpreter#qualified`,
-    # `Router#dispatch`'s own rebuilt string) before this ever runs. A
-    # third `::` segment can still show up past that boundary: a bare
-    # `ScopedConstant` naming a port operation (`command_ref`'s own
-    # comment — `Aggregate::Port::Operation`, three colon-joined
-    # segments with no `.` of its own) only gets its last `::` rewritten
-    # to `.` there, at DSL-build time, because nothing at that point
-    # knows yet whether the constant names a port operation or a
-    # domain-qualified command (`Domain::Aggregate::Command`, the other
-    # shape `command_ref` documents) — both are textually identical.
-    # Here, past the already-resolved domain boundary, any leftover
-    # `::` is unambiguous: it is that same rewrite artifact, and folding
-    # it into the dot-joined tail recovers exactly the
-    # `Aggregate::Port.Operation` shape a working port dispatch already
-    # expects (`spec/port_operation_interpreter_spec.rb`'s own
-    # `"Payments::Payment.PaymentGateway.Receive"`). `Outbox::Fanout
-    # .kind_for` and `ReactionInvocation#resolve_target` both already
-    # assume this contract on their own end; this is what actually
-    # delivers it to them.
+    # A `::` left after the domain and aggregate is the last-`::`-to-`.` rewrite
+    # `command_ref` leaves on a port operation; it folds into the dotted command
+    # tail (`Aggregate::Port.Operation`).
     #
     # @param verb [String, Symbol, #to_s] a `Domain::Aggregate.command` (or
     #   `.query`) path
@@ -239,26 +180,11 @@ module Hecks
       [domain, aggregate, command]
     end
 
-    # Rewrites a bare command constant's trailing `::` into `.`, matching a
-    # command's own FQN separator; a String or Symbol passes through unchanged.
+    # Rewrites a bare command constant's last `::` into `.`, matching a command's
+    # FQN separator (`Banking::Account::Debit` -> `Banking::Account.Debit`).
     #
-    # `trigger Account::Debit` / `dispatch Account::Debit` — a bare
-    # constant reference (`ConstShim`'s own `ScopedConstant`, S0b), not
-    # text (ADR 0025, "events and reactions" — command references become
-    # first-class). Ruby's `::` joins every segment the same way a
-    # constant path always does, but a command's own `hecks_fqn` joins
-    # its aggregate with `.` (`Construct#hecks_separator`'s default,
-    # only an aggregate overrides it to `::`) — so only the last `::`
-    # becomes a `.`; everything before it (the chapter, when a domain is
-    # spelled at all: `Banking::Account::Debit`) stays `::`-joined.
-    #
-    # A string passes through unchanged, on purpose — legacy era text
-    # (S0a's own shadow-parsed spelling) already mixes `::` (domain) and
-    # `.` (command) correctly on its own, e.g. `"Banking::Account.Debit"`,
-    # and re-splitting that by content rather than by type would corrupt
-    # it (its own last `::` sits between the domain and the aggregate,
-    # not the aggregate and the command). Only an actual constant object
-    # — never seen holding a `.` of its own — needs the rewrite at all.
+    # A String or Symbol passes through: era text already mixes `::` and `.`
+    # correctly, and re-splitting it by content would corrupt it.
     #
     # @param value [Symbol, String, Module] the command, as a bare constant (a
     #   `ScopedConstant` module `ConstShim` resolves) or already-dotted text
@@ -271,18 +197,8 @@ module Hecks
       path.empty? ? text : "#{path}.#{command}"
     end
 
-    # The event-side twin of `command_ref`, kept as its own name because an
-    # event name is not a command name that happens to share a format.
-    #
-    # `emits Account::AccountFrozen` / `on Account::AccountFrozen` — the
-    # event-side twin of `command_ref`, above (ADR 0025, S6 — "events
-    # first-class"). Identical transform (a bare `ScopedConstant`'s last
-    # `::` becomes `.`, a String passes through unchanged for legacy
-    # `shadow_parse` text and for corpus sites this pass didn't migrate —
-    # see that method's own comment for why both rules exist), given its
-    # own name because the two references mean different things even
-    # though the rewrite is byte-identical: an event name is not a
-    # command name that happens to share a format.
+    # The event-side twin of `command_ref`. Same rewrite, separate name, because an
+    # event reference is not a command reference that happens to share a format.
     #
     # @param value [Symbol, String, Module] the event, as a bare constant (a
     #   `ScopedConstant` module `ConstShim` resolves) or already-dotted text
@@ -291,32 +207,8 @@ module Hecks
 
     # Strips a process manager's event reference down to its bare event name.
     #
-    # `transition Account::AccountDebited => "state"` / `starts_on
-    # Transfer::TransferRequested` / `ends_on Transfer::TransferSettled`
-    # — a process manager's own event references (ADR 0025, S6),
-    # deliberately not `event_ref` — found live, not assumed, wiring a
-    # real migrated corpus site into `bin/model_check` for the first
-    # time (2026-08-28): `SagaInterpreter#begin_saga`/`#advance_saga`
-    # match `pm.starts_on`/`pm.handler_for` against `event.name`, which
-    # `CommandRules::Emission#emit` stamps bare — a command's own
-    # `emits AccountDebited` never carries its aggregate's name at all
-    # (unlike a policy's cross-aggregate `on`, matched instead by
-    # `Naming.demodulise(event.aggregate)` split apart from the bare
-    # name — `PolicyInterpreter#policies_for`). Handing a saga's own
-    # matcher the dotted `event_ref` form ("Account.AccountDebited")
-    # would silently name an event no command in the domain ever
-    # actually emits — caught by `bin/model_check`'s own `deaf_handler`/
-    # `deaf_trigger` findings the moment a real qualified corpus site
-    # existed to trip them, not by any unit test in isolation.
-    #
-    # A qualifier is still worth writing (`Account::`) — the same
-    # provenance a reader gets from `trigger Account::Debit` — it is
-    # only not worth keeping: `demodulise` drops everything but the
-    # final segment, so `Account::AccountDebited` and a bare
-    # `AccountDebited` resolve to the identical stored string. A String
-    # passes through unchanged either way, exactly like `command_ref`'s
-    # own legacy branch — this corpus never spelled one dotted to begin
-    # with, so there is nothing here to strip.
+    # Not `event_ref`: saga matching compares against `event.name`, which is stamped
+    # bare, so a dotted "Account.AccountDebited" would name an event nothing emits.
     #
     # @param value [Symbol, String, Module] the event, as a bare constant (a
     #   `ScopedConstant` module `ConstShim` resolves) or already-dotted text

data/lib/hecks/ports/access_control.rb

@@ -2,22 +2,9 @@ require_relative "../runtime/registry"
 
 module Hecks
   module Ports
-    # Who can sign in, and what role do they hold — the domain-specific
-    # half of sign-in `Ports::Authentication` deliberately stays out of
-    # (see that port's own header: it only ever talks to the external
-    # provider, never this registry's own data). Resolved the same way
-    # every other port here resolves its adapter: one adapter
-    # registry-wide answers this, since an app has no reason to want a
-    # different "who's allowed in" source per aggregate.
-    #
-    # Every domain shapes this differently — who its own "a person who
-    # can sign in" aggregate is, what admits them, what grants them
-    # access — so this port is pure delegation, same as every sibling
-    # port. The one piece of this that is generic (a live Governance
-    # grant should win over whatever an aggregate's own role field
-    # says) lives on `Ports::Authorization#live_role_for` instead —
-    # a domain's adapter here calls that directly, rather than this
-    # port re-deriving Governance-query logic another port already owns.
+    # Who can sign in and what role they hold: the domain-specific half of sign-in.
+    # Pure delegation to the one adapter bound registry-wide; adapters that need a
+    # live Governance grant call `Ports::Authorization#live_role_for`.
     module AccessControl
       NAME = "access_control".freeze
 
@@ -39,16 +26,13 @@ module Hecks
 
       # Admits a new person, in whatever way this domain's adapter defines admission.
       #
-      # The keywords carry the names of a verified sign-in (`Ports::Authentication.verify`
-      # answers `issuer`, `subject` and `email`), but nothing in this repository wires the
-      # two together, so their shapes here are adapter-defined.
+      # The keywords carry the names of a verified sign-in (`Ports::Authentication.verify`),
+      # but nothing here wires the two together, so their shapes are adapter-defined.
       #
       # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
       # @param email [Object] adapter-defined, forwarded unchanged; the person's email
-      # @param issuer [Object] adapter-defined, forwarded unchanged; the OIDC issuer that
-      #   authenticated the person
-      # @param subject [Object] adapter-defined, forwarded unchanged; the OIDC subject the
-      #   issuer vouches for
+      # @param issuer [Object] adapter-defined, forwarded unchanged; the OIDC issuer
+      # @param subject [Object] adapter-defined, forwarded unchanged; the OIDC subject
       # @return [Object] adapter-defined representation of the newly admitted person
       # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
       #   (see `adapter`)

data/lib/hecks/ports/agent/answers.rb

@@ -1,18 +1,8 @@
 module Hecks
   module Ports
     module Agent
-      # Where a raw hash becomes a struct — the one place, so every
-      # adapter (the real `claude_code` one, and any scripted double
-      # standing in for it in a spec) is held to the identical shape.
-      # An adapter's whole job ends at "here is what came back, already
-      # JSON"; whether that hash is usable is decided once, here, not
-      # re-decided per adapter.
-      #
-      # Every failure raises `ValidationError` — never lets a bare
-      # `NoMethodError` on nil, or a `KeyError`, reach a caller looking
-      # for an agent-shaped failure. `bin/interview` catches exactly one
-      # class for "the model answered badly," not a grab-bag of Ruby's
-      # own.
+      # Turns an adapter's raw reply hash into structs, so every adapter is held to
+      # one shape. Every failure raises `ValidationError`, never a bare `NoMethodError`.
       module Answers
         VERB_PATTERN = /\A[A-Za-z]+::[A-Za-z]+\.[A-Za-z]+\z/
 
@@ -77,8 +67,6 @@ module Hecks
           end
         end
 
-        # ── shared checks, each named for what it refuses ───────────────
-
         # Reads the array of rows an answer holds under one key, refusing any other shape.
         #
         # @param raw [Object] the adapter's reply; only a Hash is accepted
@@ -111,12 +99,8 @@ module Hecks
 
         # Reads a proposal row's verb, refusing one that is not fully qualified.
         #
-        # A verb the language could not even parse is an adapter fault,
-        # refused right here — the same `not_fully_qualified` shape the
-        # language's own grammar already refuses by, reused rather than
-        # reinvented. A verb naming a real category that turns out to
-        # describe the wrong fact is not this port's business: that one
-        # dispatches, and `Interview::Session#offer` is what says no.
+        # Only the shape is checked; whether the verb fits the fact is
+        # `Interview::Session#offer`'s call.
         #
         # @param row [Hash{String => Object}] one proposal row of the adapter's answer
         # @return [String] the row's `"verb"`, shaped `Chapter::Aggregate.Command`
@@ -157,9 +141,7 @@ module Hecks
 
         # Normalises a proposal row's arguments into symbol-keyed, all-String rows.
         #
-        # Rows shaped exactly as `Interview::Proposal::Argument` — a
-        # reference's `field` is legitimately blank (a reference is an
-        # id), so only `name` is required here.
+        # Only `name` is required: a reference's `field` is legitimately blank.
         #
         # @param row [Hash{String => Object}] one proposal row of the adapter's answer
         # @return [Array<Hash{Symbol => String}>] one `{name:, field:, value:}` Hash per

data/lib/hecks/ports/agent.rb

@@ -2,103 +2,28 @@ require_relative "../runtime/registry"
 
 module Hecks
   module Ports
-    # The interviewer — whatever asks the next good question, reads a
-    # sentence back into proposed declarations, judges a model on taste
-    # rather than structure, or suggests a name.
-    #
-    # ## Why a singleton port
-    #
-    # Resolved the same zero/one/many way every other port here is
-    # (`Ports::IdentityGeneration`'s own singleton adapter — one
-    # interviewer per process, never per-aggregate), because a second
-    # adapter answering this port is exactly as unchoosable as a second
-    # one minting identities.
-    #
-    # ## Why this exists
-    #
-    # Built last, on purpose, and still optional. `.claude/skills/
-    # interview/SKILL.md` conducts a whole session with none of this —
-    # Claude Code reads `bin/interview state` itself, asks the human
-    # directly with real conversation context, and calls `bin/interview
-    # ask`/`propose`/`accept` itself. This port exists for what that
-    # cannot reach: a headless run (`bin/interview suggest`, no model in
-    # the room otherwise), a batch `critique` over an already-written
-    # chapter, and — the actual point of building it at all — a
-    # scripted double (`spec/fixtures/scripted_agent.rb`) that makes the
-    # whole loop testable with no real model involved.
-    #
-    # ## What this port is not
-    #
-    # It does not judge whether a declaration is well-formed — that is
-    # the meta-domain's own job, answered by a real dispatch refusing or
-    # not (`Interview::Session#offer`). This port only ever produces
-    # shape: a question, a proposed declaration, a judgement about
-    # taste, a name. A proposal naming a category the language does not
-    # declare is an adapter fault, refused here, in `Answers`; a
-    # proposal naming a real category but describing the wrong domain
-    # fact is dispatched anyway, so the language gets to say why. That
-    # line is the whole design.
-    #
-    # ## Where parsing happens
-    #
-    # Parsing belongs to this file, not the adapter. An adapter answers
-    # with a plain, already-JSON-shaped Hash (a real model's parsed
-    # reply, or a spec double's own hand-built one) — never a Struct —
-    # so every adapter is validated identically here rather than trusting
-    # each one to refuse the same way. Two adapters that parsed
-    # differently would mean the same malformed answer passing through
-    # one and refusing through the other.
+    # The interviewer: asks questions, reads prose into proposed declarations, critiques a
+    # model on taste, and suggests names. One adapter per process.
     module Agent
       NAME = "agent".freeze
 
-      # The answer came back and could not be used — no JSON in it, a
-      # category the language does not declare, a severity outside the
-      # two that exist. A foreign failure (JSON::ParserError, a missing
-      # key) wrapped into something this port owns, the same shape
-      # `Ports::Authentication::ValidationError` already is, so no
-      # caller ever rescues a raw parser error leaking out of an
-      # adapter.
+      # The adapter's answer arrived but was unusable; retrying the same prompt will not help.
       class ValidationError < StandardError
       end
 
-      # Nothing answered at all — the binary is missing, the subprocess
-      # died, the call timed out. Separate from ValidationError on
-      # purpose: unavailable means retry or fall back to asking the
-      # human directly; malformed means the prompt is wrong, not the
-      # transport, and retrying identically will not fix it.
+      # Nothing answered (missing binary, dead subprocess, timeout); retry or ask the human.
       class Unavailable < StandardError
       end
 
-      # ── what the four operations hand back ──────────────────────────
-      #
-      # Structs, not hashes, for the reason `Bluebook::ModelCheck::Finding`
-      # already is one: a `keyword_init` Struct raises on a key nobody
-      # declared, which turns "the model invented a field" into a
-      # failure at the boundary rather than a nil three calls in.
-
-      # One question. `because` is the reasoning quoted back so a human
-      # can see it, not decoration — the same "show your work" the
-      # language's own refusal messages already practice.
+      # keyword_init Structs raise on an undeclared key, so an invented field fails at the edge.
+
+      # One question; `because` is the reasoning shown to the human.
       Question = Struct.new(:text, :because, keyword_init: true)
 
-      # One proposed declaration, already shaped as
-      # `Interview::Proposal`'s own `Argument` rows — `{name:, field:,
-      # value:}`, the exact triple `bin/interview propose --arg
-      # name:field:value` already takes and `Interview::Lowering`
-      # already knows how to lower. Nothing here decides how to address
-      # a record or whether a value is bare or wrapped — that was
-      # already the proposal-writer's job in `interview.bluebook`'s own
-      # design (see `Argument`'s own comment there); this only adds the
-      # prose reasoning a human typed does not carry on its own.
+      # `arguments` are `{name:, field:, value:}` rows, as `bin/interview propose --arg` takes.
       Proposal = Struct.new(:verb, :arguments, :rationale, keyword_init: true)
 
-      # Critique reuses `Bluebook::ModelCheck::Finding`'s own shape —
-      # same fields, same severities, so a mechanical finding
-      # (`Session#gaps`) and a judgement (this) print in one list and
-      # sort together. The kind vocabulary is not shared — ModelCheck's
-      # eleven kinds are structural facts about a graph; these are
-      # opinions about a model, closed here on purpose (an open kind
-      # field is an open prompt, and an open prompt drifts).
+      # Kinds are closed: an open kind is an open prompt, and an open prompt drifts.
       CRITIQUE_KINDS = %i[
         anemic_aggregate wrong_boundary crud_verb leaky_value_object
         missing_lifecycle missing_invariant ubiquitous_language
@@ -106,132 +31,82 @@ module Hecks
       ].freeze
       SEVERITIES = %i[error warning].freeze
 
+      # Same shape as `Bluebook::ModelCheck::Finding`, so gaps and critiques sort together.
       Finding = Struct.new(:kind, :severity, :subject, :message, keyword_init: true) do
         def to_s = "#{severity.to_s.upcase.ljust(7)} #{kind.to_s.ljust(20)} #{subject}  —  #{message}"
       end
 
-      # One suggested name. `rejected` carries the near-misses and why
-      # they were passed over — free at the point the model is choosing
-      # anyway, and the part a human actually learns from.
+      # `rejected` holds the near-misses and why each was passed over.
       Suggestion = Struct.new(:name, :because, :rejected, keyword_init: true)
 
+      # Adapters return plain Hashes; validating here makes every adapter refuse the same way.
       module_function
 
-      # Asks the adapter for the next best question and validates its raw answer into structs.
-      #
-      # `state` is the whole picture — normally
-      # `Interview::Session#declaration` plus `#gaps`, so an adapter
-      # needs no memory of its own between calls; that is what lets a
-      # headless run be a series of one-shot processes, same as
-      # `bin/interview` itself already is.
+      # Asks the adapter for the next question.
       #
       # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
-      # @param state [Hash] the interview's whole current picture (declaration plus gaps),
-      #   JSON-able because an adapter may serialise it into a prompt
-      # @param asked [Array<Object>] JSON-able record of the questions already asked, so the
-      #   adapter does not repeat one; `[]` when nothing has been asked
-      # @return [Array<Ports::Agent::Question>] the questions the adapter answered with, in
-      #   its order; `[]` if it offered none
-      # @raise [Ports::Agent::ValidationError] if the answer is not a Hash holding a
-      #   `"questions"` array whose rows each carry a non-blank `"text"` and `"because"`
-      # @raise [Ports::Agent::Unavailable] if the adapter cannot answer at all (missing
-      #   binary, failed subprocess, timeout, or an exhausted scripted queue)
-      # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
-      #   (see `adapter`)
+      # @param state [Hash] declaration plus gaps; adapters keep no memory between calls
+      # @param asked [Array<Object>] questions already asked, so the adapter does not repeat one
+      # @return [Array<Ports::Agent::Question>]
+      # @raise [Ports::Agent::ValidationError] unless the answer is a Hash whose `"questions"`
+      #   rows each carry a non-blank `"text"` and `"because"`
+      # @raise [Ports::Agent::Unavailable] if the adapter cannot answer
+      # @raise [Runtime::WiringError] unless exactly one adapter implements the port
       def ask(registry, state:, asked: [])
         Answers.questions(adapter(registry).ask(state: state, asked: asked))
       end
 
-      # Turns a human's sentence into proposed declarations, validated into structs.
-      #
-      # Returns `[]` when the sentence
-      # carried no declaration at all (a clarifying question back from
-      # the human, say) — a legitimate answer, not a failure.
+      # Turns a sentence into proposed declarations; `[]` when it named none.
       #
       # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
       # @param prose [String] a human's plain-English sentence
-      # @param state [Hash] the interview's whole current picture, JSON-able because an
-      #   adapter may serialise it into a prompt
-      # @return [Array<Ports::Agent::Proposal>] one proposal per declaration the sentence
-      #   named; `[]` when it named none
-      # @raise [Ports::Agent::ValidationError] if the answer is not a Hash holding a
-      #   `"proposals"` array, a row's `"verb"` is not `Chapter::Aggregate.Command`, its
-      #   `"rationale"` is blank, or one of its argument rows has no `"name"`
-      # @raise [Ports::Agent::Unavailable] if the adapter cannot answer at all (missing
-      #   binary, failed subprocess, timeout, or an exhausted scripted queue)
-      # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
-      #   (see `adapter`)
+      # @param state [Hash] declaration plus gaps
+      # @return [Array<Ports::Agent::Proposal>]
+      # @raise [Ports::Agent::ValidationError] unless the answer is a Hash whose `"proposals"`
+      #   rows have a `Chapter::Aggregate.Command` verb, a rationale and named arguments
+      # @raise [Ports::Agent::Unavailable] if the adapter cannot answer
+      # @raise [Runtime::WiringError] unless exactly one adapter implements the port
       def interpret(registry, prose:, state:)
         Answers.proposals(adapter(registry).interpret(prose: prose, state: state))
       end
 
-      # Asks the adapter to judge a declared model on taste, validated into structs.
-      #
-      # What is wrong with this as a model — handed everything already
-      # known (the language's own refusals, `Session#gaps`'s mechanical
-      # findings) so it spends its judgement on what neither of those
-      # can see, rather than restating them.
+      # Asks the adapter to judge a declared model on taste.
       #
       # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
-      # @param declared [Hash] the chapter as declared so far, JSON-able because an adapter
-      #   may serialise it into a prompt
-      # @param refusals [Array<Object>] JSON-able refusals the language itself already
-      #   raised; `[]` when there are none
-      # @param findings [Array<Object>] JSON-able mechanical findings `Session#gaps` already
-      #   found; `[]` when there are none
-      # @return [Array<Ports::Agent::Finding>] the adapter's judgements; `[]` when it has
-      #   nothing worth saying
-      # @raise [Ports::Agent::ValidationError] if the answer is not a Hash holding a
-      #   `"findings"` array, a row's `"kind"` is outside `CRITIQUE_KINDS`, its `"severity"`
-      #   is outside `SEVERITIES`, or its `"subject"` or `"message"` is blank
-      # @raise [Ports::Agent::Unavailable] if the adapter cannot answer at all (missing
-      #   binary, failed subprocess, timeout, or an exhausted scripted queue)
-      # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
-      #   (see `adapter`)
+      # @param declared [Hash] the chapter as declared so far
+      # @param refusals [Array<Object>] refusals the language already raised
+      # @param findings [Array<Object>] `Session#gaps` findings; both are passed so the
+      #   adapter spends its judgement on what neither can see
+      # @return [Array<Ports::Agent::Finding>]
+      # @raise [Ports::Agent::ValidationError] if a kind is outside `CRITIQUE_KINDS` or a
+      #   severity outside `SEVERITIES`
+      # @raise [Ports::Agent::Unavailable] if the adapter cannot answer
       def critique(registry, declared:, refusals: [], findings: [])
         Answers.findings(adapter(registry).critique(declared: declared, refusals: refusals, findings: findings))
       end
 
-      # Asks the adapter to suggest a name for a construct, validated into structs.
-      #
-      # Vocabulary help. `near` is what the chapter already calls
-      # things, so a suggestion cannot collide with a name in use.
+      # Suggests names for a construct.
       #
-      # Named `suggest_name`, not `name` — the plan's own word for this
-      # operation, but `Module#name` already exists and is load-bearing
-      # everywhere (backtraces, RSpec's own description building,
-      # `inspect`): a module-function called `name` shadows it the
-      # instant it's defined, and `SomeModule.name` (no args) then
-      # raises `ArgumentError: missing keywords` the next time anything
-      # — not this file, something else entirely — asks the module its
-      # own name. Measured, not theoretical: this exact collision broke
-      # RSpec's own failure-message formatting the first time it was
-      # named `name` here.
+      # Not called `name`: a module function of that name shadows `Module#name`.
       #
       # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
       # @param meaning [String] what the new name needs to mean
-      # @param kind [String] the kind of construct being named, such as `"event"`; an
-      #   adapter interpolates it into its prompt
-      # @param near [Array<String>] names already in use in this chapter, which a suggestion
-      #   must not collide with; `[]` when there are none
-      # @return [Array<Ports::Agent::Suggestion>] the suggested names, each with its
-      #   `rejected` near-misses as Strings
-      # @raise [Ports::Agent::ValidationError] if the answer is not a Hash holding a
-      #   `"names"` array whose rows each carry a non-blank `"name"` and `"because"`
-      # @raise [Ports::Agent::Unavailable] if the adapter cannot answer at all (missing
-      #   binary, failed subprocess, timeout, or an exhausted scripted queue)
-      # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
-      #   (see `adapter`)
+      # @param kind [String] the construct being named, such as `"event"`
+      # @param near [Array<String>] names already in use; a suggestion must not collide
+      # @return [Array<Ports::Agent::Suggestion>]
+      # @raise [Ports::Agent::ValidationError] unless the answer is a Hash whose `"names"`
+      #   rows each carry a non-blank `"name"` and `"because"`
+      # @raise [Ports::Agent::Unavailable] if the adapter cannot answer
       def suggest_name(registry, meaning:, kind:, near: [])
         Answers.suggestions(adapter(registry).suggest_name(meaning: meaning, kind: kind, near: near))
       end
 
-      # Finds the single adapter bound to this port, refusing an ambiguous wiring.
+      # Finds the single adapter bound to this port.
       #
       # @param registry [Runtime::Registry] the booted registry to search
       # @return [Module] the adapter module or class implementing this port
-      # @raise [Runtime::WiringError] if no adapter, or more than one, implements this port,
-      #   or the one that does has no Ruby implementation under `Hecks::Adapters`
+      # @raise [Runtime::WiringError] if none, or more than one, implements the port, or the
+      #   one that does has no Ruby implementation under `Hecks::Adapters`
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }