hecks 6.0.0 → 7.0.0

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

@@ -5,7 +5,7 @@ require_relative "../../hecks"
 require_relative "persistence_notice"
 
 module Hecks
-  module CLI
+  module Tools
     # The command behind `hecks history` and `hecks history`: every journal entry a domain's
     # append-only adapters hold, as JSON, the full write history rather than the current head.
     module History

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

@@ -2,7 +2,7 @@ require_relative "../runtime/registry"
 require_relative "../ports/agent"
 
 module Hecks
-  module CLI
+  module Tools
     # The interviewer an interview session talks to: the agent port, resolved against a registry
     # that holds one adapter (ADR 0088). The session never sees the adapter, only validated
     # questions and proposals, so a spec can stand a scripted adapter in for the real one.

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

@@ -2,7 +2,7 @@ require_relative "../naming"
 require_relative "interview_shape"
 
 module Hecks
-  module CLI
+  module Tools
     # The bluebook text of one accepted thing: its aggregate, with its value objects, commands and
     # lifecycle. `InterviewDraft` extends it, and supplies the naming and citing helpers it calls.
     module InterviewAggregate

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

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

@@ -1,7 +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

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

@@ -5,7 +5,7 @@ require_relative "interview_agent"
 require_relative "interview_session"
 
 module Hecks
-  module CLI
+  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
@@ -26,7 +26,7 @@ module Hecks
       # @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)

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,5 +1,5 @@
 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 bluebook, describing it, and recording the decision.

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

@@ -6,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
@@ -28,7 +28,7 @@ module Hecks
       # @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

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

@@ -1,7 +1,7 @@
 require_relative "../../text"
 
 module Hecks
-  module CLI
+  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`.

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

@@ -3,7 +3,7 @@ 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.

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/watch_workflow.rb

@@ -5,8 +5,8 @@ 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
@@ -15,7 +15,7 @@ module Hecks
           #
           # 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

@@ -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

@@ -10,7 +10,7 @@ module Hecks
     # 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.
     #

data/lib/hecks/{cli → tools}/model_check/examination.rb

@@ -1,7 +1,7 @@
 require_relative "../../projections/context_relationships"
 
 module Hecks
-  module CLI
+  module Tools
     module ModelCheck
       # Examining booted domains: each one's findings against the allowlist, then the language's
       # own bluebooks, printed as the check goes. `ModelCheck` extends it.

data/lib/hecks/{cli → tools}/model_check/sources.rb

@@ -1,5 +1,5 @@
 module Hecks
-  module CLI
+  module Tools
     module ModelCheck
       # Boots a domain's source into a registry of its own, so the checks read IR and nothing runs.
       # `ModelCheck` extends it.

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

@@ -4,7 +4,7 @@ require_relative "model_check/sources"
 require_relative "model_check/examination"
 
 module Hecks
-  module CLI
+  module Tools
     # The command behind `hecks model_check`: static analysis
     # over the IR, printed per domain, exiting non-zero when any error-severity
     # finding is left — unreachable lifecycle states, dead transitions, unreached

data/lib/hecks/tools/move_disables/reasons.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Tools
+    module MoveDisables
+      # Why each cop is departed from, written once in the config. A cop moved without an entry here
+      # refuses the move, so a reason is never left out.
+      REASONS = {
+        "Metrics/AbcSize"                => "spec boot helpers wire a whole runtime; splitting them hides the wiring",
+        "Metrics/MethodLength"           => "spec boot helpers wire a whole runtime; splitting them hides the wiring",
+        "Metrics/CyclomaticComplexity"   => "spec boot helpers wire a whole runtime; splitting them hides the wiring",
+        "Metrics/PerceivedComplexity"    => "spec boot helpers wire a whole runtime; splitting them hides the wiring",
+        "Metrics/ParameterLists"         => "keyword and positional signatures callers spell out; a parameter object hides them",
+        "Naming/PredicateMethod"         => "returns the operation's outcome, a row, value or verdict; the name is the verb",
+        "Naming/PredicatePrefix"         => "the DSL verb is the name a bluebook author writes",
+        "Style/MutableConstant"          => "registries and caches are mutable by design (see the ThreadSafety override)",
+        "Style/GlobalStdStream"          => "a forked child reopens the standard streams to capture its output",
+        "Style/FormatStringToken"        => "the text is curl's own token or table row text, not a Ruby format string",
+        "Style/EvalWithLocation"         => "deliberately without file and line: exercises the untraceable-source refusal",
+        "Style/ComparableBetween"        => "the bluebook expression language refuses between?; the spelling is under test",
+        "Lint/UnusedBlockArgument"       => "the block parameter's name is read by reflection",
+        "Lint/RescueException"           => "rolls back, then re-raises",
+        "Lint/InheritException"          => "deliberately escapes `rescue => e`, which catches StandardError only",
+        "Lint/IneffectiveAccessModifier" => "`private` does not reach `def self.`; the entry point is public on purpose",
+        "Lint/StructNewOverride"         => "the member shadows a Struct or Enumerable method on purpose; the file says which",
+        "RSpec/Output"                   => "the spec exercises console output",
+        "RSpec/RemoveConst"              => "the probe constant must not outlive the example",
+        "RSpec/ExampleLength"            => "a scenario example carries its whole bluebook fixture",
+        "Security/MarshalLoad"           => "reads our own cache or the gem's own file, never external input",
+        "Layout/LineLength"              => "characterization tables with one long row per line",
+        "Layout/HashAlignment"           => "the multi-line procs overrun LineLength under table alignment"
+      }.freeze
+    end
+  end
+end

data/lib/hecks/tools/move_disables.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "hecks"
+require_relative "../tools"
+require_relative "move_disables/reasons"
+
+module Hecks
+  module Tools
+    # Moves justified inline RuboCop disables into `.rubocop.yml`, one entry per cop, each carrying
+    # its reason once. A file in `SKIP` keeps its inline disables until someone decides or refactors
+    # it; the move does not touch them.
+    #
+    #   hecks ScriptRun.plan_script! script=move_disables      # what would move, writing nothing
+    #   hecks ScriptRun.apply_script! script=move_disables confirm=true
+    module MoveDisables
+      CONFIG = ".rubocop.yml"
+
+      CONFIG_HEADING = "# Overrides moved from inline `rubocop:disable` comments; each cop states its reason once."
+
+      # Files whose disables need a decision or a refactor first.
+      SKIP = %w[
+        lib/hecks/runtime/registry.rb
+        lib/hecks/runtime/registry/context_maps.rb
+        lib/hecks/adapters/driving/ruby/aggregate_module.rb
+        lib/hecks/bluebook/dsl/generic_dispatch.rb
+        lib/hecks/query_ir/touchpoints.rb
+        spec/adapters/driven/postgres_era/era_resolver_role_spec.rb
+      ].freeze
+
+      DIRECTIVE = /^\s*#\s*rubocop:(disable-next|disable)\s+(.+)$/
+      TRAILING = /\s+#\s*rubocop:disable(?:-next)?\s+(.+)$/
+      TRAILING_COMMENT = /\s+#\s*rubocop:disable.*$/
+      ENABLE = /^\s*#\s*rubocop:enable\s+(.+)$/
+
+      # A cop that would move has no reason written in `REASONS`.
+      class MissingReason < StandardError; end
+
+      module_function
+
+      # Runs from a checkout's root, as a script: `hecks ... move_disables [--apply]`.
+      #
+      # @param argv [Array<String>] `--apply` writes the files; without it, the plan only
+      # @param root [String] the checkout to work on
+      # @return [Integer] 0
+      def main(argv, root: ROOT)
+        puts transform(root: root, apply: argv.include?("--apply"))
+        0
+      end
+
+      # Plans the move, and writes it when `apply` is true.
+      #
+      # @param root [String] the checkout to work on
+      # @param apply [Boolean] whether to write the files and the config
+      # @return [String] the plan: each cop with the files it moves from, and what was written
+      # @raise [MissingReason] when a cop that would move has no reason in `REASONS`
+      def transform(root:, apply:)
+        edits, moves = scan(root)
+        refuse_missing_reasons(moves)
+
+        config, merged, blocks = config_with(root, moves)
+        report = plan_report(edits, moves, merged)
+        return "#{report}\ndry run; apply with confirm=true" unless apply
+
+        write(root, edits, written_config(config, blocks))
+        "#{report}\napplied"
+      end
+
+      # @param moves [Hash{String => Array<String>}] the files each cop moves from
+      # @raise [MissingReason] when a cop that would move has no reason in `REASONS`
+      def refuse_missing_reasons(moves)
+        missing = moves.keys - REASONS.keys
+        raise MissingReason, "no reason written for: #{missing.join(", ")}" unless missing.empty?
+      end
+
+      # @param root [String] the checkout
+      # @param edits [Hash{String => String}] the new text of each file that changes
+      # @param config [String] the config's new text
+      # @return [void]
+      def write(root, edits, config)
+        edits.each { |path, text| File.write(File.join(root, path), text) }
+        File.write(File.join(root, CONFIG), config)
+      end
+
+      # @param edits [Hash{String => String}] the new text of each file that changes
+      # @param moves [Hash{String => Array<String>}] the files each cop moves from
+      # @param merged [Array<String>] the cops merged into blocks already in the config
+      # @return [String] one line per cop, with its file count
+      def plan_report(edits, moves, merged)
+        lines = ["files to edit: #{edits.size}"]
+        moves.keys.sort.each do |cop|
+          lines << format("  %<cop>-32s %<count>2d file(s)", cop: cop, count: moves[cop].uniq.size)
+        end
+        lines << "merged into existing blocks: #{merged.join(", ")}" unless merged.empty?
+        lines.join("\n")
+      end
+
+      # Each Ruby file under lib and spec with a directive to move, with the text it becomes.
+      #
+      # @param root [String] the checkout
+      # @return [Array(Hash{String => String}, Hash{String => Array<String>})] the new text of each
+      #   file, and the files each cop moves from
+      def scan(root)
+        moves = Hash.new { |hash, cop| hash[cop] = [] }
+        edits = {}
+        scanned_paths(root).each do |path|
+          touched, text = strip(File.readlines(File.join(root, path), chomp: true))
+          next if touched.empty?
+
+          touched.uniq.each { |cop| moves[cop] << path }
+          edits[path] = text
+        end
+        [edits, moves]
+      end
+
+      # @param root [String] the checkout
+      # @return [Array<String>] the Ruby files under lib and spec, in order, outside `SKIP`
+      def scanned_paths(root)
+        Dir.glob(%w[lib/**/*.rb spec/**/*.rb], base: root).sort.reject { |path| SKIP.include?(path) }
+      end
+
+      # Removes the directives from one file's lines.
+      #
+      # @param lines [Array<String>] the file's lines, without their newlines
+      # @return [Array(Array<String>, String)] the cops the directives named, and the file's new text
+      def strip(lines)
+        touched = []
+        out = lines.filter_map { |line| keep_line(line, touched) }
+        out = out.reject { |line| closes_removed?(line, touched) }
+        [touched, "#{out.join("\n")}\n"]
+      end
+
+      # @param line [String] one line of the file
+      # @param touched [Array<String>] the cops removed so far; this line's cops are added to it
+      # @return [String, nil] the line without its directive, or nil when the line is a directive
+      def keep_line(line, touched)
+        if (match = DIRECTIVE.match(line))
+          touched.concat(cops_from(match[2]))
+          return nil
+        end
+        return line unless (match = TRAILING.match(line))
+
+        touched.concat(cops_from(match[1]))
+        line.sub(TRAILING_COMMENT, "")
+      end
+
+      # A block-form enable is closed by a disable that was removed; it goes once its cops are gone.
+      #
+      # @param line [String] one line of the file
+      # @param touched [Array<String>] the cops the file's removed directives named
+      # @return [Boolean] whether the line is an enable whose cops were all removed
+      def closes_removed?(line, touched)
+        match = ENABLE.match(line)
+        match && (cops_from(match[1]) - touched).empty?
+      end
+
+      # @param text [String] the cops of one directive, possibly followed by a ` -- reason`
+      # @return [Array<String>] the cop names
+      def cops_from(text)
+        reason_free = text.split(" -- ").first
+        reason_free.split(",").map(&:strip).reject(&:empty?)
+      end
+
+      # Adds each moved cop to the config: a new block, or an `Exclude` under an existing one.
+      #
+      # @param root [String] the checkout
+      # @param moves [Hash{String => Array<String>}] the files each cop moves from
+      # @return [Array(String, Array<String>, Array<String>)] the config text with the existing
+      #   blocks filled, the cops merged into existing blocks, and the new blocks to append
+      def config_with(root, moves)
+        config = File.read(File.join(root, CONFIG))
+        merged, added = moves.keys.sort.partition { |cop| config.match?(header_line(cop)) }
+        [fill_blocks(config, merged, moves), merged, added.map { |cop| new_block(cop, excluded_paths(moves[cop])) }]
+      end
+
+      # @param config [String] the config's text
+      # @param merged [Array<String>] the cops whose blocks already exist in the config
+      # @param moves [Hash{String => Array<String>}] the files each cop moves from
+      # @return [String] the config with each existing block given its `Exclude`
+      def fill_blocks(config, merged, moves)
+        merged.inject(config) { |text, cop| text.sub(header_line(cop)) { merged_block(cop, excluded_paths(moves[cop])) } }
+      end
+
+      # @param cop [String] a cop name
+      # @return [Regexp] the config line that opens the cop's block
+      def header_line(cop) = /^#{Regexp.escape("#{cop}:")}$/
+
+      # @param files [Array<String>] the files a cop moves from
+      # @return [Array<String>] the `Exclude` entries, sorted and unique
+      def excluded_paths(files) = files.uniq.sort.map { |path| %(    - "#{path}") }
+
+      # @param cop [String] a cop name
+      # @param paths [Array<String>] the `Exclude` entries
+      # @return [String] the cop's header, its reason, and its `Exclude`, to replace an existing header
+      def merged_block(cop, paths) = ["#{cop}:", "  # #{REASONS.fetch(cop)}", "  Exclude:", *paths].join("\n")
+
+      # @param cop [String] a cop name
+      # @param paths [Array<String>] the `Exclude` entries
+      # @return [String] a new block for the cop, with its reason above it
+      def new_block(cop, paths) = ["# #{REASONS.fetch(cop)}", "#{cop}:", "  Exclude:", *paths].join("\n")
+
+      # @param config [String] the config as it stands, with existing blocks filled
+      # @param blocks [Array<String>] the new blocks to append
+      # @return [String] the config with the new blocks appended under a heading
+      def written_config(config, blocks)
+        return config if blocks.empty?
+
+        "#{config.rstrip}\n\n#{CONFIG_HEADING}\n#{blocks.join("\n\n")}\n"
+      end
+    end
+  end
+end

data/lib/hecks/tools/move_former_name.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative "../tools"
+require_relative "../naming"
+
+module Hecks
+  module Tools
+    # Moves an aggregate's `formerly_known_as "Old"` out of the bluebook and into the world that
+    # names the domain, as `stored_as Name: "old"`: the physical name an aggregate's rows are
+    # stored under is a storage fact, so the world says it. The bluebook line is removed, the world
+    # line is added (the world file is created beside the bluebook when the domain has none), and
+    # nothing else changes: a translation edge already carries the rename for the data.
+    #
+    #   hecks move_former_name [--dry-run]
+    module MoveFormerName
+      # One aggregate-level `formerly_known_as` found in a bluebook.
+      Candidate = Struct.new(:file, :domain, :aggregate, :former, keyword_init: true)
+
+      SKIPPED          = %r{(^|/)(\.claude|\.git|node_modules|rust|spec|tmp|vendor)/}
+      DOMAIN_LINE      = /^\s*Hecks\.bluebook\s+"([^"]+)"/
+      AGGREGATE_LINE   = /^\s*aggregate\s+"([^"]+)"/
+      FORMERLY_LINE    = /^\s*formerly_known_as\s+"([^"]+)"\s*$/
+      WORLD_LINE_START = /^(\s*Hecks\.world\s+"%<domain>s"\s+do\n)/
+      BLUEBOOK_EXT     = /\.bluebook\z/
+
+      module_function
+
+      # @param argv [Array<String>] `--dry-run` to print what would change and write nothing
+      # @param root [String] the checkout whose bluebooks are read
+      # @return [Integer] 0
+      def main(argv, root: Tools::ROOT)
+        dry_run = argv.include?("--dry-run")
+        found = candidates(root)
+        puts "no aggregate-level formerly_known_as found" if found.empty?
+        found.group_by(&:file).each { |file, group| move(file, group, root, dry_run) }
+        0
+      end
+
+      # @param root [String] the checkout
+      # @return [Array<Candidate>] every aggregate-level `formerly_known_as` under the root
+      def candidates(root) = files_under(root, "bluebook").flat_map { |file| in_file(file) }
+
+      # @param root [String] the checkout
+      # @param extension [String] `bluebook` or `world`
+      # @return [Array<String>] the files with that extension, outside the folders left alone
+      def files_under(root, extension)
+        Dir.glob(File.join(root, "**/*.#{extension}")).reject { |file| file.delete_prefix("#{root}/").match?(SKIPPED) }
+      end
+
+      # @param file [String] a bluebook
+      # @return [Array<Candidate>] its aggregates that carry the word
+      def in_file(file)
+        text = File.read(file)
+        domain = text[DOMAIN_LINE, 1]
+        return [] unless domain
+
+        owner = nil
+        text.each_line.filter_map do |line|
+          owner = Regexp.last_match(1) if line =~ AGGREGATE_LINE
+          next unless owner && line =~ FORMERLY_LINE
+
+          Candidate.new(file: file, domain: domain, aggregate: owner, former: Regexp.last_match(1))
+        end
+      end
+
+      # Rewrites one bluebook and writes or prints the world lines that replace its words.
+      def move(file, group, root, dry_run)
+        world = world_file_for(file, group.first.domain, root)
+        lines = group.map { |c| "#{c.aggregate}: #{Naming.snake(c.former).inspect}" }
+        puts "#{rel(file, root)}: remove #{group.size} formerly_known_as line(s)"
+        puts "#{rel(world, root)}: add `stored_as #{lines.join(", ")}`"
+        write(file, world, group, lines) unless dry_run
+      end
+
+      def write(file, world, group, lines)
+        File.write(file, strip(File.read(file), group))
+        File.write(world, with_stored_as(world, group.first.domain, lines))
+      end
+
+      def strip(text, group)
+        group.reduce(text) { |t, c| t.sub(/^[ \t]*formerly_known_as\s+"#{Regexp.escape(c.former)}"[ \t]*\n/, "") }
+      end
+
+      # The world file that already names the domain, else `<bluebook>.world` beside the bluebook.
+      def world_file_for(file, domain, root)
+        named = files_under(root, "world").sort.find { |world| names_domain?(world, domain) }
+        named || file.sub(BLUEBOOK_EXT, ".world")
+      end
+
+      def names_domain?(world, domain)
+        !world.include?(".local.") && File.read(world).match?(/^\s*Hecks\.world\s+"#{Regexp.escape(domain)}"/)
+      end
+
+      def with_stored_as(world, domain, lines)
+        statement = "  stored_as #{lines.join(", ")}\n"
+        return "Hecks.world #{domain.inspect} do\n#{statement}end\n" unless File.exist?(world)
+
+        start = Regexp.new(format(WORLD_LINE_START.source, domain: Regexp.escape(domain)))
+        File.read(world).sub(start) { "#{Regexp.last_match(1)}#{statement}" }
+      end
+
+      def rel(path, root) = path.delete_prefix("#{root}/")
+    end
+  end
+end

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

@@ -3,7 +3,7 @@
 require "json"
 
 module Hecks
-  module CLI
+  module Tools
     # The command behind `hecks record_pattern_cases`: records the expected match results for
     # `pattern:` cases, which `spec/pattern_subset_spec.rb` reads from
     # `spec/corpus/fixtures/patterns.json`.

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

@@ -1,7 +1,7 @@
 require_relative "../../hecks"
 
 module Hecks
-  module CLI
+  module Tools
     # The notice `hecks stores` and `hecks history` print when nothing is persisted. Hecks is in
     # Memory unless a local hecksagon opts it in (ADR 0136), so a fresh process holds no records and
     # no journal, and the plain JSON they print would read as an empty store rather than as a store

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

@@ -4,7 +4,7 @@ require_relative "../forms"
 require_relative "../forms/banking_presentation"
 
 module Hecks
-  module CLI
+  module Tools
     # The command behind `hecks present` and `hecks present`: serves the banking example's rendered
     # forms and views, backed by the in-memory adapter
     # (docs/command-form-and-query-form-bluebook.md).