hecks 5.0.0 → 7.0.0

data/lib/hecks/{cli → tools}/interview_draft.rb

@@ -5,7 +5,7 @@ require_relative "interview_record"
 require_relative "interview_aggregate"
 
 module Hecks
-  module CLI
+  module Tools
     # Turns an interview's accepted findings into the files of a first domain (ADR 0088).
     #
     # Pure: it answers the text of each file and writes none, so the command that runs an interview
@@ -17,6 +17,10 @@ module Hecks
     # turned into code from prose: it is a comment citing its source, to become a `given` by hand.
     module InterviewDraft
       ACCEPTED = "accepted".freeze
+      # A run of anything but letters and digits: the gaps between the words of a free-text name.
+      NAME_GAP = /[^A-Za-z0-9]+/
+      # The first character of a word.
+      INITIAL = /\A./
 
       extend InterviewRecord
       extend InterviewAggregate
@@ -96,7 +100,10 @@ module Hecks
 
       # A free-text name as a PascalCase word safe to write into Ruby: `lend a book` is `LendABook`.
       # @api private
-      def word(text) = text.to_s.split(/[^A-Za-z0-9]+/).reject(&:empty?).map { |part| part.sub(/\A./, &:upcase) }.join
+      def word(text)
+        parts = text.to_s.split(NAME_GAP).reject(&:empty?)
+        parts.map { |part| part.sub(INITIAL, &:upcase) }.join
+      end
 
       # @api private
       def cite(interview, finding) = "#{interview[:reference]} ##{finding[:source]}:"

data/lib/hecks/{cli → tools}/interview_record.rb

@@ -1,5 +1,7 @@
+require_relative "../text"
+
 module Hecks
-  module CLI
+  module Tools
     # The Markdown record of an interview, and the plain interview read out of a booted record.
     # `InterviewDraft` extends it.
     module InterviewRecord
@@ -11,6 +13,8 @@ module Hecks
         fields:      [:number, :thing, :name, :values, :source, :status],
         transitions: [:number, :thing, :action, :to, :from, :source, :status]
       }.freeze
+      # Any character a record's file name may not carry.
+      UNSAFE_FILE_CHARACTER = /[^A-Za-z0-9._-]/
 
       # The interview's record: every exchange in order, and every finding with how it was decided.
       #
@@ -25,7 +29,7 @@ module Hecks
         "#{lines.join("\n")}\n"
       end
 
-      # Reads the plain interview out of an `Interview` record booted from the SME chapter.
+      # Reads the plain interview out of an `Interview` record booted from the SME bluebook.
       #
       # @param interview [Object] the booted record
       # @return [Hash] the plain interview this module takes: `reference`, `subject`, `expert`,
@@ -51,7 +55,7 @@ module Hecks
       end
 
       # @api private
-      def file_stem(reference) = reference.to_s.gsub(/[^A-Za-z0-9._-]/, "_")
+      def file_stem(reference) = reference.to_s.gsub(UNSAFE_FILE_CHARACTER, "_")
 
       # @api private
       def exchange_lines(exchange, number)
@@ -113,7 +117,7 @@ module Hecks
       def clause(label, value) = value.to_s.strip.empty? ? "" : ", #{label} #{value}"
 
       # @api private
-      def one_line(text) = text.to_s.gsub(/\s+/, " ").strip
+      def one_line(text) = text.to_s.gsub(Text::WHITESPACE, " ").strip
 
       # @api private
       def plain(value)

data/lib/hecks/{cli → tools}/interview_run.rb

@@ -5,10 +5,11 @@ require_relative "interview_agent"
 require_relative "interview_session"
 
 module Hecks
-  module CLI
-    # The command behind `hecks interview <Name>` (ADR 0088): boots the SME chapter on demand, holds
-    # the interview at the terminal, then writes the first domain, or the next interview's proposed
-    # additions, and says what to type next. Nothing is written unless the interview concludes.
+  module Tools
+    # The command behind `hecks interview <Name>` (ADR 0088): boots the SME bluebook on demand,
+    # holds the interview at the terminal, then writes the first domain, or the next interview's
+    # proposed additions, and says what to type next. Nothing is written unless the interview
+    # concludes.
     module InterviewRun
       SME = File.expand_path("../sme", __dir__)
 
@@ -22,10 +23,10 @@ module Hecks
       # @param input [#gets] where the developer types
       # @param output [#puts, #print] where the session speaks
       # @param agent [#question, #proposals, nil] an interviewer to use instead of the real one
-      # @param runtime [Runtime, nil] a booted SME chapter to use instead of booting one
+      # @param runtime [Runtime, nil] a booted SME bluebook to use instead of booting one
       # @return [String] the report that was printed, or "" when nothing was written
       # @raise [ArgumentError] when the name or adapter is refused, or a file would be replaced
-      def call(name:, adapter: nil, dir: nil, expert: nil, use_ai: true, input: $stdin, output: $stdout, agent: nil, # rubocop:disable Metrics/ParameterLists -- one keyword per setting the command takes
+      def call(name:, adapter: nil, dir: nil, expert: nil, use_ai: true, input: $stdin, output: $stdout, agent: nil,
                runtime: nil)
         DomainStub.support_files(name: name, adapter: adapter)
         target = File.expand_path(dir || DomainStub.directory(name), Dir.pwd)
@@ -51,7 +52,8 @@ module Hecks
         return expert unless expert.to_s.strip.empty?
 
         output.print("Who is the expert? ")
-        input.gets.to_s.strip.then { |text| text.empty? ? "the expert" : text }
+        answer = input.gets.to_s.strip
+        answer.empty? ? "the expert" : answer
       end
 
       # @api private

data/lib/hecks/{cli → tools}/interview_session/agent_state.rb

@@ -1,5 +1,5 @@
 module Hecks
-  module CLI
+  module Tools
     class InterviewSession
       # What the session tells the agent: the interview so far, what was accepted, and the gaps.
       module AgentState

data/lib/hecks/{cli → tools}/interview_session/catalog.rb

@@ -1,5 +1,5 @@
 module Hecks
-  module CLI
+  module Tools
     class InterviewSession
       NOTICE = "Your answers are sent to a model through your own `claude` login. " \
                "Run with --no-ai to leave it out.".freeze

data/lib/hecks/{cli → tools}/interview_session/manual_findings.rb

@@ -1,5 +1,5 @@
 module Hecks
-  module CLI
+  module Tools
     class InterviewSession
       # The plain prompt: findings typed by the developer, accepted as they are entered.
       module ManualFindings

data/lib/hecks/{cli → tools}/interview_session/proposals.rb

@@ -1,9 +1,12 @@
 module Hecks
-  module CLI
+  module Tools
     class InterviewSession
       # Putting an agent's proposed finding to the developer: reading its fields, proposing it to
-      # the SME chapter, describing it, and recording the decision.
+      # the SME bluebook, describing it, and recording the decision.
       module Proposals
+        # The `Something refused — ` a refusal message opens with.
+        REFUSAL_LEAD = /\A[A-Z]\w* refused\s+[—-]\s+/
+
         private
 
         def review(proposal)
@@ -83,7 +86,7 @@ module Hecks
           "#{", taking #{fields["takes"]}" if fields["takes"]}#{", by #{fields["by"]}" if fields["by"]}"
         end
 
-        def reason(error) = error.message.sub(/\A[A-Z]\w* refused\s+[—-]\s+/, "").strip
+        def reason(error) = error.message.sub(REFUSAL_LEAD, "").strip
       end
     end
   end

data/lib/hecks/{cli → tools}/interview_session.rb

@@ -1,3 +1,4 @@
+require_relative "../text"
 require_relative "interview_draft"
 require_relative "interview_session/catalog"
 require_relative "interview_session/proposals"
@@ -5,7 +6,7 @@ require_relative "interview_session/manual_findings"
 require_relative "interview_session/agent_state"
 
 module Hecks
-  module CLI
+  module Tools
     # One interview, held at a terminal (ADR 0088).
     #
     # hecks drives: it asks the agent for a question, shows it, reads the answer the developer typed
@@ -20,14 +21,14 @@ module Hecks
       include ManualFindings
       include AgentState
 
-      # @param runtime [Runtime] the booted SME chapter
+      # @param runtime [Runtime] the booted SME bluebook
       # @param agent [#question, #proposals, nil] the interviewer; nil runs the plain prompts
       # @param input [#gets] where the developer types
       # @param output [#puts, #print] where the session speaks
       # @param reference [String] the interview's reference, such as `INT-1`
       # @param subject [String] the domain being discovered, as its bluebook will spell it
       # @param expert [String] who is being interviewed
-      def initialize(runtime:, agent:, input:, output:, reference:, subject:, expert:) # rubocop:disable Metrics/ParameterLists -- one keyword per collaborator and setting
+      def initialize(runtime:, agent:, input:, output:, reference:, subject:, expert:)
         @runtime = runtime
         @agent = agent
         @input = input
@@ -104,7 +105,7 @@ module Hecks
       def ask_agent
         yield
       rescue Ports::Agent::Unavailable, Ports::Agent::ValidationError => e
-        say("The AI could not answer (#{e.message.lines.first.to_s.strip}). Using a plain prompt for this turn.")
+        say("The AI could not answer (#{Text.first_line(e.message)}). Using a plain prompt for this turn.")
         nil
       end
 

data/lib/hecks/tools/interview_shape/lifecycle.rb

@@ -0,0 +1,92 @@
+require_relative "../../text"
+
+module Hecks
+  module Tools
+    module InterviewShape
+      # The lifecycle an interview's accepted transitions describe, and the state words it is
+      # written in. `InterviewShape` extends it, so each method answers on `InterviewShape`.
+      module Lifecycle
+        # A run of anything a state word may not hold.
+        NON_STATE_CHARACTERS = /[^a-z0-9]+/
+        # An underscore at either end of a word.
+        EDGE_UNDERSCORE = /\A_|_\z/
+
+        # The lifecycle the accepted transitions describe. The state a creating action's step
+        # leads to is where a thing starts; a step for an action the thing does not have is kept
+        # as a comment.
+        #
+        # @param steps [Array<Hash>] the thing's accepted transitions
+        # @param creating [Array<Hash>] the accepted actions that create it
+        # @param rest [Array<Hash>] its other accepted actions
+        # @return [Array<String>] the lines, or none when no step and start state can be placed
+        def lifecycle(steps, creating, rest)
+          starts, moves = steps.partition { |step| names_action?(creating, step) }
+          placed, loose = moves.partition { |step| names_action?(rest, step) }
+          placed = merged(placed)
+          start = beginning(starts, placed)
+          return [] if start.empty? || placed.empty?
+
+          lifecycle_block(start, placed, loose)
+        end
+
+        # @api private
+        def lifecycle_block(start, placed, loose)
+          ["", "    lifecycle :status, default: #{start.inspect} do", *placed.map { |step| transition_line(step) },
+           "    end", *loose.map { |step| loose_line(step) }]
+        end
+
+        # @api private
+        def names_action?(actions, step)
+          actions.map { |action| InterviewDraft.word(action[:name]) }.include?(InterviewDraft.word(step[:action]))
+        end
+
+        # One step for each action and state it leads to: the states it starts from are joined,
+        # and a step with no state to start from means it may be taken from any.
+        # @api private
+        def merged(steps)
+          steps.group_by { |step| [InterviewDraft.word(step[:action]), state_word(step[:to])] }.values.map do |group|
+            froms = group.map { |step| step[:from].to_s.strip }
+            group.first.merge(from: froms.any?(&:empty?) ? "" : froms.join(","))
+          end
+        end
+
+        # The state a thing starts in: where its creating action's step leads, else the first state
+        # a change is said to start from.
+        # @api private
+        def beginning(starts, placed)
+          from = placed.map { |step| step[:from].to_s.split(",").first }.find { |text| !text.to_s.strip.empty? }
+          state_word(starts.first&.fetch(:to) || from)
+        end
+
+        # @api private
+        def transition_line(step)
+          "      transition #{InterviewDraft.word(step[:action]).inspect} => #{state_word(step[:to]).inspect}" \
+            "#{from_clause(step)}"
+        end
+
+        # @api private
+        def loose_line(step)
+          "    # UNPLACED transition: #{InterviewDraft.word(step[:action])} to #{state_word(step[:to])}; " \
+            "no accepted action has that name."
+        end
+
+        # The states a step may start from: none, one, or several.
+        # @api private
+        def from_clause(step)
+          froms = step[:from].to_s.split(Text::COMMA).map { |text| state_word(text) }
+          states = froms.reject(&:empty?)
+          return "" if states.empty?
+
+          states.one? ? ", from: #{states.first.inspect}" : ", from: %w[#{states.join(" ")}]"
+        end
+
+        # A state as a lowercase word: `Not Yet Triaged` is `not_yet_triaged`.
+        # @api private
+        def state_word(text)
+          lowered = text.to_s.strip.downcase
+          lowered.gsub(NON_STATE_CHARACTERS, "_").gsub(EDGE_UNDERSCORE, "")
+        end
+      end
+    end
+  end
+end

data/lib/hecks/{cli → tools}/interview_shape.rb

@@ -1,7 +1,9 @@
 require_relative "../naming"
+require_relative "../text"
+require_relative "interview_shape/lifecycle"
 
 module Hecks
-  module CLI
+  module Tools
     # What an interview's fields, command inputs and state changes become in a drafted aggregate
     # (ADR 0088): its attributes and their value objects, the fields a command is told, a note of
     # who does it, and the lifecycle.
@@ -9,6 +11,13 @@ module Hecks
     # Pure, like `InterviewDraft`, which calls it: each method answers lines of bluebook text and
     # writes none. A name is written as `InterviewDraft.word` writes it.
     module InterviewShape
+      # An ` or ` between the alternatives an expert names.
+      ALTERNATIVE = /\s+or\s+/
+      # A comma or an ` or `: what separates the values an expert lists.
+      VALUE_SEPARATOR = /\s*,\s*|\s+or\s+/
+
+      extend Lifecycle
+
       module_function
 
       # The accepted fields of one thing, each with the type it will be written under. The
@@ -55,7 +64,8 @@ module Hecks
       # @param action [Hash] an accepted action
       # @return [Array<String>] snake-cased field names
       def takes(action)
-        action[:takes].to_s.split(/\s*,\s*/).map { |text| Naming.snake(InterviewDraft.word(text)) }.reject(&:empty?)
+        names = action[:takes].to_s.split(Text::COMMA).map { |text| Naming.snake(InterviewDraft.word(text)) }
+        names.reject(&:empty?)
       end
 
       # What an action is told that the thing has as a field, and what it names that the thing
@@ -99,35 +109,6 @@ module Hecks
         by.empty? ? [] : ["      # Who: #{by}. Declare it as a role once Governance is attached."]
       end
 
-      # The lifecycle the accepted transitions describe. The state a creating action's step
-      # leads to is where a thing starts; a step for an action the thing does not have is kept
-      # as a comment.
-      #
-      # @param steps [Array<Hash>] the thing's accepted transitions
-      # @param creating [Array<Hash>] the accepted actions that create it
-      # @param rest [Array<Hash>] its other accepted actions
-      # @return [Array<String>] the lines, or none when no step and start state can be placed
-      def lifecycle(steps, creating, rest)
-        starts, moves = steps.partition { |step| names_action?(creating, step) }
-        placed, loose = moves.partition { |step| names_action?(rest, step) }
-        placed = merged(placed)
-        start = beginning(starts, placed)
-        return [] if start.empty? || placed.empty?
-
-        lifecycle_block(start, placed, loose)
-      end
-
-      # @api private
-      def lifecycle_block(start, placed, loose)
-        ["", "    lifecycle :status, default: #{start.inspect} do", *placed.map { |step| transition_line(step) },
-         "    end", *loose.map { |step| loose_line(step) }]
-      end
-
-      # @api private
-      def names_action?(actions, step)
-        actions.map { |action| InterviewDraft.word(action[:name]) }.include?(InterviewDraft.word(step[:action]))
-      end
-
       # One action for each name: an expert who refines an answer gets the same action accepted more
       # than once, and a command can be declared only once. The first one's event and place in the
       # interview stay; what each takes is joined, who does it is joined, and it creates if any did.
@@ -143,8 +124,10 @@ module Hecks
 
       # @api private
       def joined(group, key, separator)
-        parts = group.flat_map { |a| a[key].to_s.split(separator == ", " ? /\s*,\s*/ : /\s+or\s+/) }
-        parts.map(&:strip).reject(&:empty?).uniq.join(separator)
+        pattern = separator == ", " ? Text::COMMA : ALTERNATIVE
+        parts = group.flat_map { |a| a[key].to_s.split(pattern) }
+        kept = parts.map(&:strip).reject(&:empty?)
+        kept.uniq.join(separator)
       end
 
       # @api private
@@ -155,51 +138,14 @@ module Hecks
         type = Naming.pascal(field)
         type = "#{type}Value" while taken.include?(type)
         taken << type
-        { name: field, type: type, values: finding[:values].to_s.split(/\s*,\s*|\s+or\s+/).map(&:strip).reject(&:empty?).uniq }
+        { name: field, type: type, values: listed_values(finding[:values]) }
       end
 
-      # One step for each action and state it leads to: the states it starts from are joined, and a
-      # step with no state to start from means it may be taken from any.
       # @api private
-      def merged(steps)
-        steps.group_by { |step| [InterviewDraft.word(step[:action]), state_word(step[:to])] }.values.map do |group|
-          froms = group.map { |step| step[:from].to_s.strip }
-          group.first.merge(from: froms.any?(&:empty?) ? "" : froms.join(","))
-        end
+      def listed_values(text)
+        parts = text.to_s.split(VALUE_SEPARATOR).map(&:strip)
+        parts.reject(&:empty?).uniq
       end
-
-      # The state a thing starts in: where its creating action's step leads, else the first state a
-      # change is said to start from.
-      # @api private
-      def beginning(starts, placed)
-        from = placed.map { |step| step[:from].to_s.split(",").first }.find { |text| !text.to_s.strip.empty? }
-        state_word(starts.first&.fetch(:to) || from)
-      end
-
-      # @api private
-      def transition_line(step)
-        "      transition #{InterviewDraft.word(step[:action]).inspect} => #{state_word(step[:to]).inspect}" \
-          "#{from_clause(step)}"
-      end
-
-      # @api private
-      def loose_line(step)
-        "    # UNPLACED transition: #{InterviewDraft.word(step[:action])} to #{state_word(step[:to])}; " \
-          "no accepted action has that name."
-      end
-
-      # The states a step may start from: none, one, or several.
-      # @api private
-      def from_clause(step)
-        states = step[:from].to_s.split(/\s*,\s*/).map { |text| state_word(text) }.reject(&:empty?)
-        return "" if states.empty?
-
-        states.one? ? ", from: #{states.first.inspect}" : ", from: %w[#{states.join(" ")}]"
-      end
-
-      # A state as a lowercase word: `Not Yet Triaged` is `not_yet_triaged`.
-      # @api private
-      def state_word(text) = text.to_s.strip.downcase.gsub(/[^a-z0-9]+/, "_").gsub(/\A_|_\z/, "")
     end
   end
 end

data/lib/hecks/{cli → tools}/ir.rb

@@ -4,7 +4,7 @@ require_relative "../../hecks"
 require_relative "../ports/persistence/plugins/era"
 
 module Hecks
-  module CLI
+  module Tools
     # The command behind `hecks ir`: a booted domain's IR as JSON, the
     # same `to_h` the golden specs pin and `StorageShape` hashes into an era.
     module Ir

data/lib/hecks/tools/lanes/files.rb

@@ -77,7 +77,7 @@ module Hecks
           end
 
           warn "lanes: out of date: #{out_of_date.map { |path| relative(path) }.join(", ")} " \
-               "(run hecks regeneration_run.project_lanes)"
+               "(run hecks regeneration_run.project_lanes!)"
           1
         end
 

data/lib/hecks/tools/lanes/prebuilt_workflow.rb

@@ -23,7 +23,7 @@ module Hecks
         def header(row)
           name = row["name"]
           ["name: Publish #{name}", "",
-           "# Generated by hecks project_lanes from the PrebuiltBinary rows of the Vocabulary chapter. Do not hand-edit.",
+           "# Generated by hecks project_lanes from the PrebuiltBinary rows of the Vocabulary bluebook. Do not hand-edit.",
            "#",
            "# Builds #{row["executable"]} from #{row["crate"]} for #{row["target"]} and publishes it as the release",
            "# #{name}-<key>, where the key is a hash of the crate's build inputs. A client that needs the same",

data/lib/hecks/tools/lanes/rows.rb

@@ -5,8 +5,14 @@ require "hecks/vocabulary"
 module Hecks
   module Tools
     module Lanes
-      # The `Lane` rows of the Vocabulary chapter, checked against what the projection can express.
+      # The `Lane` rows of the Vocabulary bluebook, checked against what the projection can express.
       module Rows
+        # Empty, or a trailer key of dash-joined words such as `Release-Approved-By`.
+        TRAILER_KEY = /\A([A-Za-z][A-Za-z0-9]*(-[A-Za-z0-9]+)*)?\z/
+
+        # Empty, or a whole number of hours.
+        WHOLE_HOURS = /\A\d*\z/
+
         module_function
 
         # @return [Array<Hash{String => String}>] the `Lane` rows
@@ -36,10 +42,10 @@ module Hecks
 
         # @return [Boolean] whether `release_trailer` is empty (nothing is released from the lane)
         #   or a git trailer key such as `Release-Approved-By`
-        def trailer?(lane) = lane["release_trailer"].to_s.match?(/\A([A-Za-z][A-Za-z0-9]*(-[A-Za-z0-9]+)*)?\z/)
+        def trailer?(lane) = lane["release_trailer"].to_s.match?(TRAILER_KEY)
 
         # @return [Boolean] whether `alert_after` is empty (never late) or whole hours
-        def hours?(lane) = lane["alert_after"].to_s.match?(/\A\d*\z/)
+        def hours?(lane) = lane["alert_after"].to_s.match?(WHOLE_HOURS)
 
         def follows_problem(lane, names)
           follows = lane["follows"].to_s

data/lib/hecks/tools/lanes/ruleset.rb

@@ -9,7 +9,7 @@ module Hecks
       # The ruleset GitHub is given for a guarded lane.
       #
       # A guarded lane cannot be deleted or rewound, and a `green` lane takes only a commit on
-      # which every `RequiredCheck` of the Vocabulary chapter has already passed. No actor is let
+      # which every `RequiredCheck` of the Vocabulary bluebook has already passed. No actor is let
       # past it: a push of a commit that passed is how a promotion moves the lane, and the GitHub
       # Actions app cannot be named as a bypass actor.
       module Ruleset

data/lib/hecks/tools/lanes/watch_workflow.rb

@@ -5,17 +5,17 @@ module Hecks
     module Lanes
       # The workflow that watches each lane with an alert threshold: every hour it asks
       # `PromotionRun` whether the lane has stood behind the lane it follows for longer than its
-      # `Lane` row allows. A late lane faults the run, and the fault files a finding, one a day: the
-      # alert key carries the date, and the journal in Postgres lets the next hour see it.
+      # `Lane` row allows. A late lane faults the run, and GitHub's failed-run status
+      # and email say so.
       module WatchWorkflow
         HEADER = <<~YAML.chomp
           name: Watch lanes
 
-          # Generated by hecks project_lanes from the Lane rows of the Vocabulary chapter. Do not hand-edit.
+          # Generated by hecks project_lanes from the Lane rows of the Vocabulary bluebook. Do not hand-edit.
           #
           # Every hour, asks `PromotionRun` whether a lane has stood behind the lane it follows for
           # longer than its Lane row allows (`alert_after`, in hours). The rule is decided there, not
-          # here. A late lane fails the run, files a finding (one a day) and asks Promote to try
+          # here. A late lane fails the run and asks Promote to try
           # again: a promotion that was dropped is picked up within the hour, and one that still
           # cannot go says why in its own run.
           on:
@@ -31,7 +31,6 @@ module Hecks
           permissions:
             contents: read
             checks: read
-            issues: write
             actions: write
 
           jobs:
@@ -71,10 +70,9 @@ module Hecks
 
         def watch_step(name)
           ["      - name: Watch #{name}", "        env:", "          GH_TOKEN: ${{ github.token }}",
-           "          HECKS_FINDINGS_REPO: ${{ github.repository }}", "        run: >-",
-           "          bundle exec exe/hecks promotion_run.watch lane=#{name}",
-           "          run=watch-#{name}-${{ github.run_id }}-${{ github.run_attempt }}",
-           "          alert_key=#{name}-lag-$(date -u +%Y-%m-%d) --wait"]
+           "        run: >-",
+           "          bundle exec exe/hecks promotion_run.watch! lane=#{name}",
+           "          run=watch-#{name}-${{ github.run_id }}-${{ github.run_attempt }} --wait"]
         end
       end
     end

data/lib/hecks/tools/lanes/workflow.rb

@@ -10,7 +10,7 @@ module Hecks
         HEADER = <<~YAML.chomp
           name: Promote
 
-          # Generated by hecks project_lanes from the Lane rows of the Vocabulary chapter. Do not hand-edit.
+          # Generated by hecks project_lanes from the Lane rows of the Vocabulary bluebook. Do not hand-edit.
           #
           # After CI finishes on a push to the lane a lane follows, asks `PromotionRun` to move the
           # lane onto the newest commit of that lane every RequiredCheck passed on. Which commit may
@@ -70,7 +70,7 @@ module Hecks
         def promote_step(name)
           ["      - name: Promote #{name}", "        env:", "          GH_TOKEN: ${{ github.token }}",
            "        run: >-",
-           "          bundle exec exe/hecks promotion_run.promote lane=#{name}",
+           "          bundle exec exe/hecks promotion_run.promote! lane=#{name}",
            "          run=#{name}-${{ github.event.workflow_run.head_sha || github.run_id }} --confirm --wait"]
         end
       end

data/lib/hecks/tools/lanes.rb

@@ -6,11 +6,11 @@ require_relative "../hecks/adapters/github_rulesets"
 
 module Hecks
   module Tools
-    # Projects the `Lane` rows of the Vocabulary chapter into what GitHub is told about them: a
+    # Projects the `Lane` rows of the Vocabulary bluebook into what GitHub is told about them: a
     # ruleset for each guarded lane (`.github/rulesets/<lane>.json`), one for the tag such a lane
     # feeds (`.github/rulesets/tag-<tag>.json`), and the workflow that promotes
     # each lane that follows another (`.github/workflows/promote.yml`). The workflow only runs
-    # `hecks promotion_run.promote`; the rule that decides a promotion is `PromotionRun.Accept`.
+    # `hecks promotion_run.promote!`; the rule that decides a promotion is `PromotionRun.Accept`.
     #
     # Without a flag the files are written. `--check` writes nothing and answers 1 for each file
     # that differs, which is the drift gate. `--live` compares the rulesets GitHub holds with the

data/lib/hecks/{cli → tools}/mcp.rb

@@ -1,7 +1,7 @@
 require_relative "../mcp_stdio_guard"
 
 module Hecks
-  module CLI
+  module Tools
     # The command behind `hecks mcp`: the MCP server onto the
     # storehouse bus, over stdio only.
     #