hecks 7.0.0 → 7.1.0

data/lib/hecks/projector/exporter/adapters.rb

@@ -33,13 +33,14 @@ module Hecks
           }.merge(optional_adapter_keys(adapter))
         end
 
-        # The keys only some adapters carry: `provides` when it names a capability, and a
-        # plugin's `answers` and `runs`.
+        # The keys only some adapters carry: `provides` when it names a capability, `stays_inside`
+        # when the adapter says it, and a plugin's `answers` and `runs`.
         #
         # @param adapter [Bluebook::Hecksagon::Adapter] the adapter to export
         # @return [Hash{String => Object}] the keys it carries beyond the five every adapter has
         def optional_adapter_keys(adapter)
           keys = adapter.capabilities.empty? ? {} : { "provides" => adapter.capabilities }
+          keys["stays_inside"] = true if adapter.stays_inside?
           return keys unless adapter.plugin?
 
           keys.merge("answers" => adapter.answered_queries, "runs" => adapter.runs)

data/lib/hecks/projector/narrate_projector/use_cases.rb

@@ -0,0 +1,74 @@
+module Hecks
+  module Projector
+    module NarrateProjector
+      # The prose for the goals an `.examples` file declares (ADR 0173): each goal as a use case,
+      # its first example the main scenario and the rest its extensions. Every line is quoted from
+      # the file; `hecks-parse examples` has already checked it against the bluebook.
+      module UseCases
+        GOAL    = /\A(\s*)Goal:\s*(.+?)\s*\z/
+        EXAMPLE = /\A\s*Example:\s*(.+?)\s*\z/
+        STEP    = /\A\s*(Given|When|Then|And)\s+(.+?)\s*\z/
+        INDENT  = /\A\s*/
+
+        module_function
+
+        # The "Use cases" section, or `nil` when no file declares a goal.
+        #
+        # @param paths [Array<String>] `.examples` files
+        # @param depth [Integer] the section's heading level
+        # @return [String, nil] Markdown
+        def narrative(paths, depth)
+          goals = Array(paths).flat_map { |path| goals_in(File.readlines(path, chomp: true)) }
+          return nil if goals.empty?
+
+          [DocsProjector.h(depth, "Use cases"), *goals.map { |goal| goal_text(goal, depth + 1) }].join("\n\n")
+        end
+
+        # @param lines [Array<String>] one `.examples` file
+        # @return [Array<Hash>] each goal with its examples, each example with its step lines
+        def goals_in(lines)
+          open = nil
+          lines.each_with_object([]) do |line, goals|
+            open = follow(line, open, goals) unless line.strip.empty?
+          end
+        end
+
+        # Reads one line against the goal still open, answering the goal open after it: a `Goal:`
+        # opens one, a line indented under it belongs to it, any other line closes it.
+        def follow(line, open, goals)
+          if (goal = line.match(GOAL))
+            goals << { indent: goal[1].size, goal: goal[2], examples: [] }
+            return goals.last
+          end
+          return nil unless open && indent_of(line) > open[:indent]
+
+          add_to(open, line)
+          open
+        end
+
+        # Files one line of a goal: an example under it, or a step of its latest example.
+        def add_to(goal, line)
+          if (example = line.match(EXAMPLE))
+            goal[:examples] << { title: example[1], steps: [] }
+          elsif (step = line.match(STEP)) && goal[:examples].any?
+            goal[:examples].last[:steps] << "#{step[1]} #{step[2]}"
+          end
+        end
+
+        def indent_of(line) = line[INDENT].size
+
+        def goal_text(goal, depth)
+          main, *extensions = goal[:examples]
+          [DocsProjector.h(depth, goal[:goal]), scenario("Main scenario", main),
+           *extensions.map { |extension| scenario("Extension", extension) }].compact.join("\n\n")
+        end
+
+        def scenario(label, example)
+          return nil unless example
+
+          ["**#{label}: #{example[:title]}**", *example[:steps].map { |step| "- #{step}" }].join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projector/narrate_projector.rb

@@ -11,8 +11,9 @@ module Hecks
       # Projects `bluebook` as prose; `options[:heading]` sets the top heading level.
       #
       # @param bluebook [Bluebook::Behaviour::Bluebook] the bluebook to narrate
-      # @param options [Hash] `:heading` (Integer, default 1) and `:aggregate` (narrows to one
-      #   aggregate, omitting the bluebook intro and reactions)
+      # @param options [Hash] `:heading` (Integer, default 1), `:aggregate` (narrows to one
+      #   aggregate, omitting the bluebook intro and reactions) and `:examples` (`.examples` files
+      #   whose goals are told as use cases, ADR 0173)
       # @return [String] Markdown prose ending in a newline
       # @raise [Runtime::NotFound] if `options[:aggregate]` names no declared aggregate
       def call(bluebook:, options: {})
@@ -22,10 +23,15 @@ module Hecks
         sections = []
         sections << bluebook_intro(bluebook, depth) unless only
         sections.concat(aggregate_narratives(bluebook, only, only ? depth : depth + 1))
-        sections << Reactions.narrative(bluebook, depth + 1) unless only
+        sections.concat(closing_sections(bluebook, options[:examples], depth + 1)) unless only
         "#{sections.compact.join("\n\n").rstrip}\n"
       end
 
+      # What the bluebook causes on its own, then the use cases its examples declare.
+      def closing_sections(bluebook, examples, depth)
+        [Reactions.narrative(bluebook, depth), UseCases.narrative(examples, depth)]
+      end
+
       # One narrative per aggregate, at heading level `depth`.
       def aggregate_narratives(bluebook, only, depth)
         Array(DocsProjector.aggregates(bluebook, only)).map { |aggregate| aggregate_narrative(aggregate, depth) }
@@ -140,3 +146,4 @@ end
 
 require_relative "narrate_projector/commands"
 require_relative "narrate_projector/reactions"
+require_relative "narrate_projector/use_cases"

data/lib/hecks/quality_control/adapters/main_maintenance.rb

@@ -138,12 +138,13 @@ module Hecks
       # @param request [Hash] the `MintRequested` attributes: `run`, `domain`, `era`, `sha`,
       #   `branch`,
       #   `watermark`, `rehearsal_verdict`, `refusal_total`, `ledger_dir` and `confirm`
-      # @return [Hash] `run`, `domain`, `era`, `sha`, `branch` and `label`
+      # @return [Hash] `run`, `domain`, `era`, `sha` and `label` as values; `branch` and
+      #   `ledger_dir` as the strings the landing takes
       def mint(**request)
         refuse_while_stranded!
         refuse_unrehearsed!(value_of(request[:rehearsal_verdict]))
-        label = run_mint!(request, authorize!(request))
-        %i[run domain era sha branch].to_h { |key| [key, wrap(request[key])] }.merge(label: wrap(label))
+        label = wrap(run_mint!(request, authorize!(request)))
+        %i[run domain era sha].to_h { |key| [key, wrap(request[key])] }.merge(label:, **request.slice(:branch, :ledger_dir))
       end
 
       # Answers a held mint's approval request: the mint waits for the owner, and nothing follows
@@ -160,9 +161,12 @@ module Hecks
       # mint
       # refuses until the owner removes it.
       #
+      # `ledger_dir` names the minted ledger's bluebook directory; an empty one is the
+      # QualityControl ledger, which lands in this checkout.
+      #
       # @return [Hash] `run`, `era`, `sha` and `branch`, which `MintStranded` takes on refusal
-      def land(run:, era:, sha:, branch:, **)
-        output, landed = @commands.land(@root, value_of(branch))
+      def land(run:, era:, sha:, branch:, **answer)
+        output, landed = @commands.land(QaAutoMint.checkout_for(@root, value_of(answer[:ledger_dir])), value_of(branch))
         strand!(run, era, sha, output) unless landed
         { run: wrap(run), era: wrap(era), sha: wrap(sha), branch: wrap(branch) }
       end

data/lib/hecks/quality_control/adapters/qa_auto_mint.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "open3"
 require_relative "qa_era_mint"
 require_relative "../../adapters/driven/postgres_era/lineage_manager/mint_decision"
 
@@ -49,10 +50,28 @@ module Hecks
       def held_bluebook(latest) = PostgresEra::LineageManager.held_bluebook(latest)
 
       # The bluebook directory a mint is for: the one the request names, or the QualityControl
-      # ledger.
+      # ledger when it names none or an empty one.
       #
       # @return [String]
-      def ledger_for(root, requested) = requested || File.join(root, QaEraMint::LEDGER)
+      def ledger_for(root, requested)
+        requested.to_s.empty? ? File.join(root, QaEraMint::LEDGER) : requested
+      end
+
+      # The checkout a minted ledger's branch lands in: `root` for the QualityControl ledger, else
+      # the git checkout around the ledger's directory.
+      #
+      # @param root [String] the Hecks checkout
+      # @param requested [String, nil] the ledger's bluebook directory, or nil or empty for QA's
+      # @return [String] the checkout's top directory
+      # @raise [Runtime::WiringError] if the ledger's directory is in no git checkout
+      def checkout_for(root, requested)
+        return root if requested.to_s.empty?
+
+        top, status = Open3.capture2e("git", "-C", requested, "rev-parse", "--show-toplevel")
+        raise Runtime::WiringError, "#{requested} is in no git checkout: #{top.strip}" unless status.success?
+
+        top.strip
+      end
 
       # The ledger a mint is for, refused by name when its world declares it disposable: its boot
       # holds every shape change itself, so there is no era to mint.

data/lib/hecks/quality_control/cli/qa_concurrency_racer.rb

@@ -10,7 +10,7 @@ module Hecks
     # The command behind `hecks quality_control sweep.race`: one racer of
     # `Hecks::Fuzzing::ConcurrentDispatch`, run as its own OS process.
     #
-    # It is spawned, not forked: the caller (`hecks quality_control query sweep.run`) holds live
+    # It is spawned, not forked: the caller (`hecks quality_control sweep.run`) holds live
     # `PostgresEra` connections, and fork duplicates their file descriptors and SSL state,
     # corrupting them when a child exits.
     #

data/lib/hecks/quality_control/cli/qa_domain_novelty.rb

@@ -99,7 +99,8 @@ module Hecks
         [argv.first(split), argv.drop(split + 1).reject { |arg| arg == "--against" }]
       end
 
-      # `hecks build.project_rust!` reads exactly `<name>/bluebook/<name>.bluebook`, so refuse anything
+      # `hecks build.project_rust!` reads exactly `<name>/bluebook/<name>.bluebook`, so refuse
+      # anything
       # else early.
       def refuse_unless_stress_domain_shaped!(path)
         expected = File.join(path, "bluebook", "#{File.basename(path)}.bluebook")

data/lib/hecks/quality_control/cli/qa_fix_main_bug/publishing.rb

@@ -3,9 +3,12 @@
 module Hecks
   module QualityControlCli
     class QaFixMainBug
-      # What happens after a fix is committed: the ledger records the investigation and the fix, the branch
-      # lands on local main, the ledger records the verification, and main is pushed through the push train.
-      # The push runs only after the quick gate is green on main's head, and origin's main is fetched right
+      # What happens after a fix is committed: the ledger records the investigation and the fix, the
+      # branch
+      # lands on local main, the ledger records the verification, and main is pushed through the
+      # push train.
+      # The push runs only after the quick gate is green on main's head, and origin's main is
+      # fetched right
       # before it.
       module Publishing
         private
@@ -62,7 +65,8 @@ module Hecks
           unpushed("the push train refused main: #{output.strip}")
         end
 
-        # Fetches origin's main right before the push. @return [String, nil] why main cannot be pushed as it is
+        # Fetches origin's main right before the push. @return [String, nil] why main cannot be
+        # pushed as it is
         def behind_origin
           QaMainGate::Worktree.git!(@root, "fetch", "origin", "main")
           return nil if QaMainGate::Worktree.git?(@root, "merge-base", "--is-ancestor", "origin/main", "main")

data/lib/hecks/quality_control/cli/qa_fix_main_bug.rb

@@ -11,14 +11,15 @@ require_relative "qa_fix_main_bug/publishing"
 
 module Hecks
   module QualityControlCli
-    # The command behind `hecks quality_control bug.fix_and_land --bug BUG#n`: takes one self-contained red-main
-    # bug through a fix on a fresh branch off main, the quick gate on that exact commit, a landing on local main,
-    # and a push through the push train. A bug triaged bigger, or one whose fixer changes nothing or leaves a
-    # check red, stops before anything lands and stays open for the owner. Nothing is landed unless the gate is
-    # green on the commit, and nothing is pushed unless the gate is green on main's head.
+    # The command behind `hecks quality_control bug.fix_and_land --bug BUG#n`: takes one
+    # self-contained red-main bug through a fix on a fresh branch off main, the quick gate on that
+    # exact commit, a landing on local main, and a push through the push train. A bug triaged
+    # bigger, or one whose fixer changes nothing or leaves a check red, stops before anything lands
+    # and stays open for the owner. Nothing is landed unless the gate is green on the commit, and
+    # nothing is pushed unless the gate is green on main's head.
     #
-    # Exit 0 when the fix is landed (pushed, or the push's refusal is printed), 1 when refused before any fix,
-    # 2 when the fix stays red.
+    # Exit 0 when the fix is landed (pushed, or the push's refusal is printed), 1 when refused
+    # before any fix, 2 when the fix stays red.
     class QaFixMainBug
       include Publishing
 
@@ -140,7 +141,8 @@ module Hecks
         QaMainGate::Worktree.git?(@root, "rev-parse", "--verify", "--quiet", "refs/heads/#{branch}")
       end
 
-      # The fixer runs, then the gate on the exact commit it makes. Returns the commit, or what kept it red.
+      # The fixer runs, then the gate on the exact commit it makes. Returns the commit, or what kept
+      # it red.
       def fix_in(dir, row)
         @shell.rubocop(dir, files_of(row))
         return Stuck.new("the fixer changed nothing") unless changed?(dir)

data/lib/hecks/quality_control/cli/qa_generated_domains/promotion.rb

@@ -67,7 +67,7 @@ module Hecks
           <<~NOTES
             # #{name}
 
-            Promoted from a `hecks quality_control query target.check_generated_domains` finding — #{origin_phrase(recorded)}, not
+            Promoted from a `hecks quality_control target.check_generated_domains` finding — #{origin_phrase(recorded)}, not
             hand-written. The bluebook is the minimal form of the domain that
             surprised; `QaGenerated` was renamed to `#{camelize(name)}` and nothing
             else changed.
@@ -102,7 +102,7 @@ module Hecks
         end
 
         def origin_phrase(recorded)
-          recorded&.key?("source") ? "written by `hecks quality_control query target.mine_combinations`' agent" : "generated"
+          recorded&.key?("source") ? "written by `hecks quality_control target.mine_combinations`' agent" : "generated"
         end
       end
     end

data/lib/hecks/quality_control/cli/qa_main_gate/gate_run.rb

@@ -5,8 +5,10 @@ require "hecks/tools/gate"
 module Hecks
   module QualityControlCli
     class QaMainGate
-      # Runs the quick gate's checks in a directory, all at once, and says which passed. The checks are
-      # the `GateStage` rows of the Vocabulary bluebook, so a red check is reported with the output it
+      # Runs the quick gate's checks in a directory, all at once, and says which passed. The checks
+      # are
+      # the `GateStage` rows of the Vocabulary bluebook, so a red check is reported with the output
+      # it
       # printed, the same way `hecks gate_run.gate! stage=quick` reports one.
       module GateRun
         # One check of the quick gate after it ran.
@@ -21,7 +23,8 @@ module Hecks
         #   @return [Boolean] whether it exited 0
         Result = Struct.new(:id, :title, :output, :passed)
 
-        # Stands in for the gate's progress lines, which go to standard error of a person's terminal.
+        # Stands in for the gate's progress lines, which go to standard error of a person's
+        # terminal.
         class Quiet
           # @return [nil]
           def start(_id) = nil

data/lib/hecks/quality_control/cli/qa_main_gate/logging.rb

@@ -3,17 +3,21 @@
 module Hecks
   module QualityControlCli
     class QaMainGate
-      # Turns one red check into one QA bug, proven by the check's own output, and triages it. A check the
+      # Turns one red check into one QA bug, proven by the check's own output, and triages it. A
+      # check the
       # command can fix mechanically is `self_contained`; every other is `bigger`, for the owner.
       module Logging
-        # Checks with a mechanical fixer. `rubocop -a` fixes style offenses it can fix; metrics and the
+        # Checks with a mechanical fixer. `rubocop -a` fixes style offenses it can fix; metrics and
+        # the
         # rest need a person.
         SELF_CONTAINED = %w[rubocop].freeze
         SUBMITTER = "qa_main_gate"
         NAME_PREFIX = "main-red-"
 
-        # A bug already open for the same check is not logged again: the commit moved, the red did not.
-        # @return [Array(String, String, Boolean)] the reference, its disposition, and whether it was new
+        # A bug already open for the same check is not logged again: the commit moved, the red did
+        # not.
+        # @return [Array(String, String, Boolean)] the reference, its disposition, and whether it
+        #   was new
         def log_red(sweep, result, sha)
           open = open_bug_named(bug_name(result.id))
           return [open, disposition(result.id), false] if open

data/lib/hecks/quality_control/cli/qa_main_gate/shell.rb

@@ -5,7 +5,8 @@ require "open3"
 module Hecks
   module QualityControlCli
     class QaMainGate
-      # The commands outside the ledger that a red-main fix runs: the mechanical fixer, the landing, and the
+      # The commands outside the ledger that a red-main fix runs: the mechanical fixer, the landing,
+      # and the
       # push through the push train. Each answers its output and whether it exited 0.
       module Shell
         # The push train's own launcher, in its detached checkout.
@@ -13,7 +14,8 @@ module Hecks
 
         module_function
 
-        # Applies `rubocop -a` to the files, which fixes what it can; whether the rest is fixed is the gate's
+        # Applies `rubocop -a` to the files, which fixes what it can; whether the rest is fixed is
+        # the gate's
         # to say.
         #
         # @return [Array(String, Boolean)]

data/lib/hecks/quality_control/cli/qa_main_gate/sweeping.rb

@@ -3,8 +3,10 @@
 module Hecks
   module QualityControlCli
     class QaMainGate
-      # The sweep a red run of the gate on main is written as. Main is not a bluebook, so the sweep runs
-      # against one standing target, `main-gate`, that is shelved: the rotation never claims it. Each gate
+      # The sweep a red run of the gate on main is written as. Main is not a bluebook, so the sweep
+      # runs
+      # against one standing target, `main-gate`, that is shelved: the rotation never claims it.
+      # Each gate
       # check is one `Check`, its expectation written before the answer is read.
       module Sweeping
         TARGET = "main-gate"
@@ -42,8 +44,10 @@ module Hecks
             dispatch("QualityControl::Sweep.Check.Held", id: sweep.id, sequence: { value: sequence },
                                                           observation: { value: "exit 0" })
           else
-            # Not `Check.Surprised`: its `SuspendOnSurprise` policy can only suspend a held target, and this
-            # one is shelved, so the policy would be refused on every red run. The red is carried by the
+            # Not `Check.Surprised`: its `SuspendOnSurprise` policy can only suspend a held target,
+            # and this
+            # one is shelved, so the policy would be refused on every red run. The red is carried by
+            # the
             # `MainCheck` record and the bugs logged from the output.
             dispatch("QualityControl::Sweep.Check.Unsettled", id: sweep.id, sequence: { value: sequence },
                                                                observation: { value: result.output })

data/lib/hecks/quality_control/cli/qa_main_gate/worktree.rb

@@ -7,7 +7,8 @@ require "tmpdir"
 module Hecks
   module QualityControlCli
     class QaMainGate
-      # A temporary git worktree, made for one block and removed when it returns, so a gate or a fix never
+      # A temporary git worktree, made for one block and removed when it returns, so a gate or a fix
+      # never
       # runs in the owner's checkout.
       module Worktree
         # Raised when a git command the worktree needs fails.
@@ -17,7 +18,7 @@ module Hecks
 
         # @param root [String] the repository the worktree belongs to
         # @param ref [String] the commit the worktree starts at
-        # @param branch [String, nil] a new branch checked out in it; nil leaves HEAD detached
+        # @param branch [String, nil] a new branch checked out in it; nil leaves head detached
         # @yieldparam dir [String] the worktree's directory
         # @return [Object] whatever the block returns
         def with(root:, ref:, branch: nil)

data/lib/hecks/quality_control/cli/qa_main_gate.rb

@@ -13,13 +13,17 @@ require_relative "qa_fix_main_bug"
 
 module Hecks
   module QualityControlCli
-    # The command behind `hecks quality_control main_check.check_main`, the tick's main step. It runs
-    # the quick gate on local main in a temporary worktree, records the verdict against the commit, and
+    # The command behind `hecks quality_control main_check.check_main`, the tick's main step. It
+    # runs
+    # the quick gate on local main in a temporary worktree, records the verdict against the commit,
+    # and
     # for each red check logs one bug proven by its output. A self-contained bug is handed to
-    # `QaFixMainBug`. A commit already on record is answered from the record, so a tick that finds it again
+    # `QaFixMainBug`. A commit already on record is answered from the record, so a tick that finds
+    # it again
     # logs nothing twice.
     #
-    # Exit 0 when main is green, 2 when a check is red (the bugs are on the ledger), 1 on an operational
+    # Exit 0 when main is green, 2 when a check is red (the bugs are on the ledger), 1 on an
+    # operational
     # error. `QA_SWEEP_DOMAIN_DIR` picks the ledger, as for the other QA commands.
     class QaMainGate
       include Sweeping
@@ -36,7 +40,8 @@ module Hecks
       # @param argv [Array<String>] no arguments
       # @param root [String] the repository root, whose local `main` is checked
       # @param env [Hash{String => String}] `QA_SWEEP_DOMAIN_DIR` picks another ledger
-      # @param gate [#run] runs the quick gate in a directory and answers its results; a spec injects one
+      # @param gate [#run] runs the quick gate in a directory and answers its results; a spec
+      #   injects one
       # @param shell [Module] the fixer, landing and push commands; a spec injects one
       # @return [Integer] the exit status
       def self.call(argv, root:, env: ENV, gate: GateRun, shell: Shell)

data/lib/hecks/quality_control/cli/qa_sweep/all_mode/children.rb

@@ -16,7 +16,7 @@ module Hecks
 
           private
 
-          # Spawns `hecks quality_control query sweep.run target=<target>` as a fresh process, not a
+          # Spawns `hecks quality_control sweep.run target=<target>` as a fresh process, not a
           # fork.
           def spawn_sweep_child(target_reference, flags, modes:, parity: false)
             # Unlinked at once: the open fd stays readable, nothing is left on disk, and no fixed

data/lib/hecks/quality_control/cli/qa_sweep/checks.rb

@@ -66,7 +66,7 @@ module Hecks
 
         # Coverage-guided generation's corpus, one JSON file per (target, mode): `--all`'s waves can
         # run a target's primary sweep and its persistence-parity/concurrency variants as separate
-        # `hecks quality_control query sweep.run` processes within the same tick, and each explores
+        # `hecks quality_control sweep.run` processes within the same tick, and each explores
         # a conceptually independent axis of the same domain, so each keeps its own file rather than
         # sharing one that nothing here locks.
         def coverage_corpus_path(target_reference, mode)

data/lib/hecks/quality_control/cli/qa_sweep.rb

@@ -28,7 +28,7 @@ require_relative "qa_sweep/conclusion"
 
 module Hecks
   module QualityControlCli
-    # The command behind `hecks quality_control query sweep.run`: runs one claim, sweep, conclude
+    # The command behind `hecks quality_control sweep.run`: runs one claim, sweep, conclude
     # and release cycle against a `QualityControl` target (`USAGE` lists the forms, from a bare
     # sweep of the least recently swept target to `--all` and `--release`). It stops with a report
     # and exit 2 on the first surprised check, and never logs a `Bug` itself.

data/lib/hecks/quality_control/cli/qa_tick.rb

@@ -122,7 +122,8 @@ module Hecks
         report(steps, reclaimed_holds(steps[1].output), write_tick_log!(steps))
       end
 
-      # The steps that look for findings, in the order the report prints them. The event pump is last.
+      # The steps that look for findings, in the order the report prints them. The event pump is
+      # last.
       def finding_steps
         [
           guarded("check_pull_requests") { run_pr_check },
@@ -161,7 +162,8 @@ module Hecks
         [output, exit_code]
       end
 
-      # The quick gate on local main, last: each red check it finds becomes a bug and a self-contained one
+      # The quick gate on local main, last: each red check it finds becomes a bug and a
+      # self-contained one
       # is fixed, landed and pushed by `QaMainGate`.
       def run_main_check
         banner "hecks quality_control check_main"
@@ -170,7 +172,8 @@ module Hecks
         [output, exit_code]
       end
 
-      # @return [Object] the dial's value from `qa/settings.yml`, or the fallback when it is not loaded
+      # @return [Object] the dial's value from `qa/settings.yml`, or the fallback when it is not
+      #   loaded
       def dial(name, fallback)
         return fallback unless defined?(::QualityControlDials) && ::QualityControlDials.const_defined?(name)
 

data/lib/hecks/quality_control/quality_control.bluebook

@@ -45,7 +45,7 @@ Hecks.bluebook "QualityControl" do
     attribute :last_swept, SweptIn
     # Recency-decayed count of how often this bluebook was worth sweeping; see `YieldScore`.
     attribute :yield_score, YieldScore
-    # Consecutive `Release`s that came back clean; `hecks quality_control query sweep.run` reads it to choose sweep depth.
+    # Consecutive `Release`s that came back clean; `hecks quality_control sweep.run` reads it to choose sweep depth.
     # Zero means no streak yet, shared on purpose by a never-swept target and a just-surprised one.
     attribute :clean_streak, CleanStreak
     # Comma-joined mode names recorded at release from what the runner inferred. Stored so
@@ -267,7 +267,7 @@ Hecks.bluebook "QualityControl" do
     end
 
     query "Suspended" do
-      description "Bluebooks a check surprised, waiting for a person — each with the reason the policy wrote. Nothing automatic touches these; hecks quality_control query sweep.run <target> --release --notes is how one comes back."
+      description "Bluebooks a check surprised, waiting for a person — each with the reason the policy wrote. Nothing automatic touches these; hecks quality_control sweep.run <target> --release --notes is how one comes back."
       where(status: "suspended")
       order_by :reference
     end
@@ -2287,7 +2287,7 @@ Hecks.bluebook "QualityControl" do
     # a boot never mints, and the mint names the commit its landing puts on main, so the ledger and main move
     # together. The rehearsal ref and the expected watermark are checked against the live ledger by the era check.
     # `refusal_total` is the rehearsal's refusal count and `ledger_dir` the bluebook directory of the ledger
-    # the era belongs to (the QualityControl ledger when omitted). A mint with no `confirm` runs only when
+    # the era belongs to (the QualityControl ledger when empty, its default, so it is always on the event). A mint with no `confirm` runs only when
     # the auto-mint rule (`AutoMintAdditive`) holds; the mint entry point checks it.
     command "MintEra" do
       role "QA engineer"
@@ -2301,7 +2301,7 @@ Hecks.bluebook "QualityControl" do
       attribute :watermark,      Integer
       attribute :rehearsal_verdict, MintVerdict
       attribute :refusal_total,  Integer, optional: true
-      attribute :ledger_dir,     String, optional: true
+      attribute :ledger_dir,     String, default: ""
       attribute :confirm,        Confirmation, optional: true
 
       emits "MintRequested"
@@ -3039,14 +3039,14 @@ Hecks.bluebook "QualityControl" do
   # Nothing reacts to `TicketRaised` on purpose: a ticket waits until somebody submits it.
 
   # The rotation's one automatic reaction. Releasing on `SweepConcluded` cannot work: that event
-  # carries no target id, `next_streak` or yield score, so `hecks quality_control query sweep.run` still releases.
+  # carries no target id, `next_streak` or yield score, so `hecks quality_control sweep.run` still releases.
   # `on Sweep::CheckSurprised`, not `Sweep::Check::...`: an entity command's event is stamped with
   # its parent aggregate. `Check.Surprised` restates `target` so the id rides in.
   policy "SuspendOnSurprise" do
     on      Sweep::CheckSurprised
     trigger Target::Suspend, with: {
       target: :target,
-      reason: { value: "a check surprised — a person releases with hecks quality_control query sweep.run <target> --release --notes" }
+      reason: { value: "a check surprised — a person releases with hecks quality_control sweep.run <target> --release --notes" }
     }
   end
 
@@ -3193,14 +3193,14 @@ Hecks.bluebook "QualityControl" do
   #   (d) no stranded marker exists.
   # Otherwise the mint is held: the entry point refuses it as "needs owner approval", and the policy below
   # asks for the approval, which answers `MintNeedsApproval` and stops. A stale watermark or a stranded
-  # marker is a refusal, never a held mint. The ask forwards no `ledger_dir`: an optional attribute a call
-  # leaves out is not on the event, so the entry point takes the QualityControl ledger by default.
+  # marker is a refusal, never a held mint. The ask forwards `ledger_dir`, empty for the QualityControl
+  # ledger, so a mint of another domain's ledger reaches that ledger.
   policy "AutoMintAdditive" do
     on      "Maintenance.MintRequested"
     where   { rehearsal_verdict.value == "would_mint" }
     ask     :mint, with: { run: :run, domain: :domain, era: :era, sha: :sha, branch: :branch,
                            watermark: :watermark, rehearsal_verdict: :rehearsal_verdict,
-                           refusal_total: :refusal_total, confirm: :confirm }
+                           refusal_total: :refusal_total, ledger_dir: :ledger_dir, confirm: :confirm }
   end
 
   # Holds a mint the auto-mint rule does not cover for the owner. Reads the refusal the entry point named.
@@ -3212,8 +3212,8 @@ Hecks.bluebook "QualityControl" do
 
   policy "LandOnMinted" do
     on      "Maintenance.Minted"
-    where   { branch.value != "" }
-    ask     :land, with: { run: :run, era: :era, sha: :sha, branch: :branch }
+    where   { branch != "" }
+    ask     :land, with: { run: :run, era: :era, sha: :sha, branch: :branch, ledger_dir: :ledger_dir }
   end
 
   # The release PR chain. A version bump opens its PR; the conditions judged on `ReleaseChecked` either

data/lib/hecks/quality_control/quality_control.ports.hecksagon

@@ -164,10 +164,13 @@ Hecks.hecksagon "QualityControl" do
       refuses "MintApprovalRefused"
     end
 
+    # The landing runs in the repository that holds the minted ledger: the Hecks checkout when
+    # `ledger_dir` is empty, else the git checkout around that directory.
     asks "Land", to: Maintenance do
-      attribute :era,    MintedEra
-      attribute :sha,    MaintenanceSha
-      attribute :branch, String
+      attribute :era,        MintedEra
+      attribute :sha,        MaintenanceSha
+      attribute :branch,     String
+      attribute :ledger_dir, String
       answers "Landed"
       refuses "MintStranded"
     end

data/lib/hecks/query_ir/touchpoints.rb

@@ -54,7 +54,8 @@ module Hecks
 
       # Whether the hand-typed Reconstruction method reads `field`. Answers nil, not false, for a
       # construct without one: nil means "not applicable", false means "applicable, and it fails",
-      # and the touchpoint reports each differently. Named without `?` because it is not a predicate.
+      # and the touchpoint reports each differently. Named without `?` because it is not a
+      # predicate.
       def reconstruction_reads(name, field)
         method_name = RECONSTRUCTION_METHODS[name]
         return nil unless method_name

data/lib/hecks/refused.rb

@@ -18,7 +18,8 @@ module Hecks
     # The last constant name of a class's path, such as `NotFound` of `Hecks::Runtime::NotFound`.
     LAST_NAME = /\w+\z/
 
-    # The boundary between a lower-case or digit letter and a capital, where a snake-case word starts.
+    # The boundary between a lower-case or digit letter and a capital, where a snake-case word
+    # starts.
     CAMEL_BOUNDARY = /([a-z\d])([A-Z])/
 
     # @return [Symbol, nil] the attribute the refusal is about, when it is about one; the