hecks 6.0.0 → 7.0.0

data/lib/hecks/tickets/bluebook/tickets.bluebook

@@ -11,12 +11,14 @@
 # or not GitHub answers: each lifecycle event asks the port, and a refused ask is recorded on the
 # finding as a sync failure that a later run retries.
 #
-# An Adr is a decision record with its own lifecycle, linked to the finding it settles.
+# An Adr is a decision record with its own lifecycle, linked to the finding it settles. A Work is a
+# step of the plan a decision carries, and stays inside Hecks.
 Hecks.bluebook "Tickets" do
   vision "Track what Hecks needs, decide it, ship it, and drive GitHub from the record."
 
   aggregate "Finding" do
     description "One thing observed about Hecks that needs a decision or a fix: reported, triaged, then resolved or dismissed."
+    created_by "Finding.report!"
 
     attribute :finding,         FindingKey
     attribute :title,          Title
@@ -109,22 +111,6 @@ Hecks.bluebook "Tickets" do
       emits "RunFindingReported"
     end
 
-    # A lane that stood behind the lane it follows for longer than its Lane row allows reports
-    # itself. The alert key names the finding and carries the day, so a lane that stays late files
-    # one finding a day: the same key again is the same finding.
-    command "ReportLag" do
-      goal "Record a lane that has stood behind the lane it follows too long as a finding"
-
-      attribute :finding, FindingKey, sets: true
-      attribute :body,    Body, sets: true
-
-      sets :fingerprint, to: "lane-lag"
-      sets :title,  to: "A lane is behind the lane it follows"
-      sets :source, to: "qa_loop"
-
-      emits "LagFindingReported"
-    end
-
     command "Triage" do
       role "Maintainer"
       goal "Give a finding its kind and severity"
@@ -179,6 +165,7 @@ Hecks.bluebook "Tickets" do
 
     command "RecordIssue" do
       goal "Record the GitHub issue number once the issue is opened"
+      audience :record
 
       reference_to Finding
       attribute :issue_number, Number, sets: true
@@ -189,6 +176,7 @@ Hecks.bluebook "Tickets" do
 
     command "RecordSyncFailure" do
       goal "Record that GitHub could not be driven, so a later run retries"
+      audience :record
 
       reference_to Finding
       attribute :sync_failure, Body, sets: true
@@ -206,6 +194,7 @@ Hecks.bluebook "Tickets" do
 
   aggregate "Adr" do
     description "A decision record: drafted, accepted, and possibly superseded, linked to the tickets it settles."
+    created_by "Adr.draft!"
 
     attribute :adr,       AdrNumber
     attribute :title,     AdrTitle
@@ -269,6 +258,237 @@ Hecks.bluebook "Tickets" do
     end
   end
 
+  # A step of a plan, held under the decision it carries out. It drives nothing outside: planned
+  # work is the maintainer's own list, not an issue.
+  aggregate "Work" do
+    description "One step of a plan: planned, started, then done or dropped, under the decision it carries out."
+    created_by "Work.plan!"
+
+    attribute :work,   WorkKey
+    attribute :title,  WorkTitle
+    attribute :detail, WorkText, optional: true
+    attribute :step,   Step, optional: true
+    attribute :reason, WorkText, optional: true
+    attribute :claimed_by, Claimant, optional: true
+    attribute :claimed_at, ClaimedAt, optional: true
+    attribute :area,   list_of(Word), optional: true
+    attribute :budget_minutes, Minutes, optional: true
+    reference_to Adr, as: :decision, optional: true
+    identified_by :work
+
+    # A path prefix or glob a claim covers. Two areas overlap by `Hecks::Adapters::AreaOverlap`;
+    # a row with no area claims nothing.
+    value_object "Word" do
+      attribute :value, String, matches: :present
+    end
+
+    # The session that claimed a started step, named as the session names itself. A step back in the
+    # plan holds the empty claimant; `Start` refuses one that names nobody.
+    value_object "Claimant" do
+      attribute :value, String, default: ""
+    end
+
+    # When the claim was taken, as the caller reads the clock: an ISO 8601 instant. Empty while the
+    # step is unclaimed.
+    value_object "ClaimedAt" do
+      attribute :value, String, default: ""
+    end
+
+    # How long a claim may run, in whole minutes. A row with none, or zero, has no budget; a step
+    # back in the plan holds zero.
+    value_object "Minutes" do
+      attribute :value, Integer
+
+      invariant("a time budget is not negative") { !value.negative? }
+    end
+
+    # What a query answered from outside the domain returns: its lines.
+    value_object "Document" do
+      attribute :text, String
+    end
+
+    value_object "WorkKey" do
+      attribute :value, String, matches: :present
+
+      invariant("a piece of work is named") { !value.to_s.empty? }
+    end
+
+    value_object "WorkTitle" do
+      attribute :value, String
+
+      invariant("a piece of work has a title") { !value.to_s.empty? }
+    end
+
+    value_object "WorkText" do
+      attribute :value, String
+    end
+
+    # Where the work stands in its plan: step 0 comes first.
+    value_object "Step" do
+      attribute :value, Integer
+
+      invariant("a step is not negative") { !value.negative? }
+    end
+
+    lifecycle :status, default: "planned" do
+      transition "Start"   => "started", from: "planned"
+      transition "Release" => "planned", from: "started"
+      transition "Yield"   => "planned", from: "started"
+      transition "Finish" => "done",    from: %w[planned started]
+      transition "Drop"   => "dropped", from: %w[planned started]
+      transition "Lapse"  => "dropped", from: %w[planned started]
+      transition "Reopen" => "planned", from: %w[done dropped]
+    end
+
+    command "Plan" do
+      role "Maintainer"
+      goal "Enter a step of a plan, optionally under the decision it carries out"
+
+      attribute :work,   WorkKey, sets: true
+      attribute :title,  WorkTitle, sets: true
+      # The detail and area default to none, so the event always carries them and
+      # ComposeBriefWhenPlanned in Coder can read them from any plan.
+      attribute :detail, WorkText, optional: true, sets: true, default: { value: "" }
+      attribute :step,   Step, optional: true, sets: true
+      attribute :area,   list_of(Word), optional: true, sets: true, default: []
+      reference_to Adr, as: :decision, optional: true
+
+      sets :decision
+
+      emits "WorkPlanned"
+    end
+
+    # A step still open takes what a later look at it found: the row stays one, its title and
+    # detail move.
+    command "Revise" do
+      goal "Replace an open step's title and detail with what a later look found"
+
+      reference_to Work
+      attribute :title,  WorkTitle, sets: true
+      attribute :detail, WorkText, sets: true
+
+      emits "WorkRevised"
+    end
+
+    # A started step is claimed: the second Start on it is refused, since only a planned step starts.
+    command "Start" do
+      role "Maintainer"
+      goal "Claim a planned step for one session, recording who claimed it and when"
+
+      reference_to Work
+      attribute :claimed_by, Claimant, sets: true
+      attribute :claimed_at, ClaimedAt, sets: true
+      attribute :area,       list_of(Word), optional: true, sets: true
+      attribute :budget_minutes, Minutes, optional: true, sets: true
+
+      given("a claim names its claimant") { !claimed_by.value.to_s.empty? }
+      given("a claim records when it was taken") { !claimed_at.value.to_s.empty? }
+
+      emits "WorkStarted"
+    end
+
+    # The claim's area overlapped another started step's, or it would start more steps than the
+    # cap allows: the WorkAreas or WorkLimits port refuses it by name, and the step goes back to
+    # the plan with the refusal as its reason.
+    command "Yield" do
+      goal "Return a step whose area another started step holds, with the refusal"
+
+      reference_to Work
+      attribute :reason, WorkText, sets: true
+
+      sets :claimed_by, to: ""
+      sets :claimed_at, to: ""
+      sets :area, to: []
+      sets :budget_minutes, to: 0
+
+      emits "WorkYielded"
+    end
+
+    # A claim gone stale returns its step to the plan, so the next session can claim it.
+    command "Release" do
+      goal "Return a started step to planned, releasing its claim"
+
+      reference_to Work
+
+      sets :claimed_by, to: ""
+      sets :claimed_at, to: ""
+      sets :area, to: []
+      sets :budget_minutes, to: 0
+
+      emits "WorkReleased"
+    end
+
+    command "Finish" do
+      role "Maintainer"
+      goal "Record that a step is done"
+
+      reference_to Work
+
+      emits "WorkFinished"
+    end
+
+    command "Drop" do
+      role "Maintainer"
+      goal "Set a step aside without doing it, with the reason"
+
+      reference_to Work
+      attribute :reason, WorkText, sets: true
+
+      emits "WorkDropped"
+    end
+
+    # A step whose cause came back (a spec red again after it was cleared) is planned again, with
+    # the new title and detail.
+    command "Reopen" do
+      goal "Return a finished or dropped step to planned because its cause returned"
+
+      reference_to Work
+      attribute :title,  WorkTitle, sets: true
+      attribute :detail, WorkText, optional: true, sets: true
+
+      emits "WorkReopened"
+    end
+
+    # A superseded decision's plan no longer stands, so its undone steps are dropped with it.
+    command "Lapse" do
+      goal "Drop a step whose decision was superseded"
+
+      reference_to Work
+
+      sets :reason, to: "its decision was superseded"
+
+      emits "WorkLapsed"
+    end
+
+    query "Undone" do
+      description "Every step not yet done or dropped, in plan order."
+      where(status: { in: "planned,started" })
+      order_by :step
+    end
+
+    # The first step still planned in plan order: the next one a coder session claims.
+    query "NextPlanned" do
+      description "The oldest step not yet claimed, in plan order: the brief a coder session reads next."
+      where(status: "planned")
+      order_by :step
+      limit 1
+    end
+
+    query "Under" do
+      description "Every step of the plan one decision carries, in plan order."
+      attribute :adr, String
+      where(decision: :adr)
+      order_by :step
+    end
+
+    query "UndoneUnder" do
+      description "The steps of one decision's plan not yet done or dropped: the ones its superseding drops."
+      attribute :adr, String
+      where(decision: :adr, status: { in: "planned,started" })
+      order_by :step
+    end
+  end
+
   # Each lifecycle event drives GitHub. A finding's own state never waits on the answer.
   policy "OpenIssueWhenReported" do
     on      "Finding.FindingReported"
@@ -280,11 +500,6 @@ Hecks.bluebook "Tickets" do
     ask     :open_issue, with: { finding: :finding }
   end
 
-  policy "OpenIssueWhenLagReported" do
-    on      "Finding.LagFindingReported"
-    ask     :open_issue, with: { finding: :finding }
-  end
-
   policy "LabelIssueWhenTriaged" do
     on      "Finding.FindingTriaged"
     ask     :label_issue, with: { finding: :finding }
@@ -310,23 +525,103 @@ Hecks.bluebook "Tickets" do
     ask     :reopen_issue, with: { finding: :finding }
   end
 
+  # A started step with an area asks the WorkAreas port whether another started step holds any of it.
+  policy "CheckAreaWhenStarted" do
+    on      "Work.WorkStarted"
+    ask     :check_area, with: { work: :work }
+  end
+
+  policy "YieldWhenAreaTaken" do
+    on      "Work.AreaRefused"
+    trigger Work::Yield, with: { reason: :refusal }
+  end
+
+  # A started step asks the WorkLimits port whether it is one too many for the concurrency cap. It is
+  # declared after the area check, so a step that clashes is already back in the plan when the cap
+  # looks, and the cap yields only a step still started.
+  policy "CheckCapWhenStarted" do
+    on      "Work.WorkStarted"
+    ask     :check_cap, with: { work: :work }
+  end
+
+  policy "YieldWhenCapReached" do
+    on      "Work.CapRefused"
+    trigger Work::Yield, with: { reason: :refusal }
+  end
+
+  # A superseded decision takes its undone steps with it.
+  policy "LapseWorkWhenSuperseded" do
+    on       "Adr.AdrSuperseded"
+    for_each "Work.UndoneUnder"
+    trigger  Work::Lapse, with: { work: :work }
+  end
+
+  # A coder's submitted branch is named for its work step, so the branch is the step's key and the
+  # policy routes it with no parsing (`with:` only routes fields). A branch naming no step is refused
+  # by the Finish command: the refusal names Work.
+  policy "FinishWhenWorkSubmitted" do
+    on      "Submission.WorkSubmitted"
+    trigger Work::Finish, with: { work: :branch }
+  end
+
+  # A branch that landed on local main finishes the step it was cut for. The Landing's LandedWork
+  # port found the open step the branch names (the whole branch name, else the name without a leading
+  # `qa/`) and answered its key; a branch with no open step is refused there and never reaches here.
+  policy "FinishWorkWhenBranchLanded" do
+    on      "Landing.LandedWorkFound"
+    trigger Work::Finish, with: { work: :branch }
+  end
+
   # A conformance or gate run that faults files its own finding.
   policy "ReportWhenConformanceFaulted" do
     on      "ConformanceRun.ConformanceFaulted"
     trigger Finding::ReportFailedRun, with: { finding: :run, body: :refusal }
   end
 
-  # A watch that finds a lane late faults it, and the fault files its finding.
-  policy "ReportWhenLaneLags" do
-    on      "PromotionRun.LaneLagged"
-    trigger Finding::ReportLag, with: { finding: :alert_key, body: :refusal }
-  end
-
   policy "ReportWhenGateFaulted" do
     on      "GateRun.GateFaulted"
     trigger Finding::ReportFailedRun, with: { finding: :run, body: :refusal }
   end
 
+  # A spec file that went red on main is a step QA picks up: `Work.undone` lists it. The spec's own key is
+  # the step's key, so a second red run, which only updates the spec, plans nothing twice.
+  policy "PlanWorkWhenSpecWentRed" do
+    on      "RedSpec.SpecWentRed"
+    trigger Work::Plan, with: { work: :spec, title: :title, detail: :detail }
+  end
+
+  # A file that fails again after it was cleared plans its finished step again.
+  policy "ReopenWorkWhenSpecWentRedAgain" do
+    on      "RedSpec.SpecWentRedAgain"
+    trigger Work::Reopen, with: { work: :spec, title: :title, detail: :detail }
+  end
+
+  # The run that no longer fails the file closes its step.
+  policy "FinishWorkWhenSpecWentGreen" do
+    on      "RedSpec.SpecWentGreen"
+    trigger Work::Finish, with: { work: :spec }
+  end
+
+  # QA's push check: a push that is due beyond the world's thresholds is one step, `push-due`. A look
+  # that finds it already open revises its detail; a look that finds it no longer due finishes it.
+  policy "PlanWorkWhenPushDue" do
+    on      "PushNudge.PushDueRead"
+    where   { due.value == "yes" && raised.value == "no" }
+    trigger Work::Plan, with: { work: :work, title: :title, detail: :detail }
+  end
+
+  policy "ReviseWorkWhenPushStillDue" do
+    on      "PushNudge.PushDueRead"
+    where   { due.value == "yes" && raised.value == "yes" }
+    trigger Work::Revise, with: { work: :work, title: :title, detail: :detail }
+  end
+
+  policy "FinishWorkWhenPushSettled" do
+    on      "PushNudge.PushDueRead"
+    where   { due.value == "no" && raised.value == "yes" }
+    trigger Work::Finish, with: { work: :work }
+  end
+
   policy "RecordTheIssue" do
     on      "Finding.IssueOpened"
     trigger Finding::RecordIssue, with: { issue_number: :issue_number }

data/lib/hecks/tickets/bluebook/tickets.hecksagon

@@ -3,6 +3,13 @@
 Hecks.hecksagon "Tickets" do
   attaches "Governance"
   persisted_by "Memory"
+
+  # The coder's submitted branch, which finishes its work step. Declarative: the Coder domain
+  # emits it, and the FinishWhenWorkSubmitted policy reacts.
+  subscribe "Coder.WorkSubmitted"
+
+  # The Hecks domain's landing found the step a landed branch was cut for: FinishWorkWhenBranchLanded reacts.
+  subscribe "Hecks.LandedWorkFound"
 end
 
 # The anti-corruption layer for Governance, which the bluebook's roles are checked against.

data/lib/hecks/tickets/bluebook/tickets.ports.hecksagon

@@ -23,4 +23,21 @@ Hecks.hecksagon "Tickets" do
       end
     end
   end
+  Tickets::Work.port "WorkAreas" do
+    asks "CheckArea", to: Work do
+      attribute :work, WorkKey
+      answers "AreaCleared"
+      refuses "AreaRefused"
+    end
+  end
+
+  # The cap on started rows, which reads the other rows, as a bluebook rule cannot. The cap is the
+  # world's `work_limit` setting.
+  Tickets::Work.port "WorkLimits" do
+    asks "CheckCap", to: Work do
+      attribute :work, WorkKey
+      answers "CapCleared"
+      refuses "CapRefused"
+    end
+  end
 end

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

@@ -2,7 +2,7 @@ require_relative "../../hecks"
 require_relative "../behaviors"
 
 module Hecks
-  module CLI
+  module Tools
     # The command behind `hecks run_behaviors` and Custodian's `Operation.RunBehaviors`: runs
     # `.behaviors` files and reports pass, fail or error per test (docs/guides/behaviors.md).
     module Behaviors

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

@@ -3,7 +3,7 @@
 require_relative "../canonical_json"
 
 module Hecks
-  module CLI
+  module Tools
     # The command behind `hecks canonicalise`: prints a JSON document with every object's keys
     # sorted, recursively. Key order is not semantics, so a diff a person reads should not have
     # to notice it moved.

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

@@ -4,7 +4,7 @@ require_relative "../../hecks"
 require_relative "../engine_agreement"
 
 module Hecks
-  module CLI
+  module Tools
     # The command behind `hecks check_engine_agreement`: fails when a query engine re-grows its
     # own comparator dispatch, or when a declared comparator lacks a shared `Comparison` case or
     # a cross-engine agreement spec. Grep-based.

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

@@ -1,14 +1,14 @@
 require_relative "expected_era"
 
 module Hecks
-  module CLI
+  module Tools
     # The check behind Custodian's `Host.CheckEra`: asks a running host which era it reports and
     # compares it with an allow-list file. Read-only: one GET, no writes.
     module CheckEra
       # What a check found.
       #
       # @!attribute [r] verdict
-      #   @return [CLI::ExpectedEra::Verdict] the era compared with the list
+      #   @return [Tools::ExpectedEra::Verdict] the era compared with the list
       # @!attribute [r] version
       #   @return [String] the gem version the host reports, empty when it reports none
       # @!attribute [r] line
@@ -24,17 +24,17 @@ module Hecks
       # @param timeout [Numeric] seconds allowed for connecting and for reading
       # @return [Finding] the comparison, whether or not the era is listed
       # @raise [Errno::ENOENT, Errno::EACCES] if the file cannot be read
-      # @raise [CLI::ExpectedEra::Unreachable] if the host cannot be reached
-      # @raise [CLI::ExpectedEra::BadResponse] if it answers no era
+      # @raise [Tools::ExpectedEra::Unreachable] if the host cannot be reached
+      # @raise [Tools::ExpectedEra::BadResponse] if it answers no era
       def assess(url, file, timeout:)
-        expected = CLI::ExpectedEra
+        expected = Tools::ExpectedEra
         allowed  = expected.parse(File.read(file))
         document = expected.fetch_version(url, timeout: timeout)
         verdict  = expected.verdict(document.fetch("era"), allowed)
         Finding.new(verdict, document.fetch("version"), sentence(verdict, file))
       end
 
-      # @param verdict [CLI::ExpectedEra::Verdict] the comparison
+      # @param verdict [Tools::ExpectedEra::Verdict] the comparison
       # @param file [String] the allow-list file, named in the sentence
       # @return [String] the one line that says what the comparison found
       def sentence(verdict, file)

data/lib/hecks/tools/ci_gates.rb

@@ -91,7 +91,9 @@ module Hecks
         [*job_header(gate, name), *JOB_BODY, *job_footer(gate, name)].join("\n")
       end
 
-      # The job's static middle: its outputs and the steps up to the one that decides.
+      # The job's static middle: its outputs and the steps up to the one that decides. Every job
+      # in the run waits on a detector, so it installs only what it uses (Ruby, no Rust toolchain)
+      # and starts `hecks` warm when an earlier run saved the boot caches for this `lib/`.
       JOB_BODY = [
         "    outputs:",
         "      touched: ${{ steps.diff.outputs.touched }}",
@@ -101,6 +103,10 @@ module Hecks
         "          # Full history: the diff needs both endpoints present as real objects.",
         "          fetch-depth: 0",
         "      - uses: ./.github/actions/setup-ruby",
+        "        with:",
+        "          # The decision diffs files and calls an API; it formats and builds no Rust.",
+        "          rust-toolchain: \"false\"",
+        "      - uses: ./.github/actions/hecks-boot-cache",
         "      - uses: ./.github/actions/hecks-environment",
         "      - id: diff"
       ].freeze
@@ -119,7 +125,7 @@ module Hecks
       def job_footer(gate, name)
         ["        name: #{quoted(gate.fetch("label"))}",
          *job_env(gate),
-         "        run: bundle exec exe/hecks regeneration_run.decide_ci_gate gate=#{name} --wait",
+         "        run: bundle exec exe/hecks regeneration_run.decide_ci_gate! gate=#{name} --wait",
          "  # END GENERATED ci_gate #{name}"]
       end
 

data/lib/hecks/tools/ci_workflows.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "hecks"
+require "fileutils"
+require_relative "../tools"
+require_relative "../projections/ci_pipeline/workflows"
+
+module Hecks
+  module Tools
+    # Projects the workflow rows of the CiWorkflows bluebook into the workflow files under
+    # `.github/workflows`: each `Workflow` row becomes one file, written whole from its rows
+    # (`Projections::CiPipeline::Workflows`, the `:ci_workflows` projection).
+    #
+    #   hecks regeneration_run.project_ci_pipeline! [--confirm]
+    #
+    # A workflow with no row is hand-written and left alone. With `--check` nothing is written: the
+    # tool answers 1 and names each file that differs from its rows.
+    module CiWorkflows
+      # The directory of the bluebook that declares the rows, which attaches the CiPipeline bluebook.
+      BLUEBOOK_DIRECTORY = File.expand_path("../ci_workflows", __dir__)
+
+      # The directory `ports/` and `adapters/` live under, loaded before the rows are.
+      LIB_HECKS = File.expand_path("..", __dir__)
+
+      # What a hecksagon that binds a store loads first.
+      WIRING = %w[ports/persistence.port ports/extraction.port adapters/driven/memory.adapter
+                  adapters/driven/prism.adapter].freeze
+
+      module_function
+
+      # Projects the rows, writes what differs and prints a line for each file written.
+      #
+      # @param argv [Array<String>] `--check` to compare without writing
+      # @param root [String] the checkout the files are written under
+      # @return [Integer] 0, or 1 when `--check` finds a file out of date
+      # @raise [SystemExit] with the reason on stderr when the rows are refused
+      def main(argv, root: Tools::ROOT)
+        files = projection(root)
+        stale = files.reject { |path, text| File.file?(path) && File.read(path) == text }.keys
+        return report(stale, root) if argv.include?("--check")
+
+        write(files, stale, root)
+        0
+      end
+
+      # @param root [String] the checkout the files belong under
+      # @return [Hash{String => String}] each workflow's absolute path to the text it should hold
+      # @raise [SystemExit] when the rows are refused
+      def projection(root)
+        registry = registry_for
+        bluebook = Projections::CiPipeline::Table.bluebook(registry)
+        table = Projections::CiPipeline::Table.read(bluebook, registry: registry)
+        files = Projector.call(:ci_workflows, bluebook: bluebook, options: { table: table })
+        files.transform_keys { |path| File.join(root, path) }
+      rescue Projections::CiPipeline::Table::Invalid => e
+        abort "project_ci_pipeline: #{e.message}"
+      end
+
+      # Loads the bluebook that declares the rows the way a deploy loads a project: the bluebooks,
+      # then the hecksagons that attach the bluebooks they need.
+      #
+      # @return [Hecks::Runtime::Registry] the registry
+      def registry_for
+        registry = Hecks::Runtime::Registry.new(root: BLUEBOOK_DIRECTORY)
+        Hecks.with_registry(registry) do
+          WIRING.each { |file| Kernel.load(File.join(LIB_HECKS, file)) }
+          Dir.glob(File.join(BLUEBOOK_DIRECTORY, "*.bluebook")).each { |file| Kernel.load(file) }
+          Dir.glob(File.join(BLUEBOOK_DIRECTORY, "*.hecksagon")).each { |file| Kernel.load(file) }
+        end
+        registry
+      end
+
+      # Writes each stale file and prints a line for it.
+      def write(files, stale, root)
+        stale.each do |path|
+          FileUtils.mkdir_p(File.dirname(path))
+          File.write(path, files.fetch(path))
+          puts "wrote #{path.delete_prefix("#{root}/")}"
+        end
+        puts "ci_pipeline: every workflow current" if stale.empty?
+      end
+
+      # @param stale [Array<String>] absolute paths whose text differs from the rows
+      # @param root [String] the checkout
+      # @return [Integer] 0 when current, else 1 with the stale workflows on stderr
+      def report(stale, root)
+        if stale.empty?
+          puts "ci_pipeline: every workflow current"
+          return 0
+        end
+
+        warn "ci_pipeline: out of date: #{stale.map { |path| path.delete_prefix("#{root}/") }.join(", ")} " \
+             "(run hecks regeneration_run.project_ci_pipeline! --confirm)"
+        1
+      end
+    end
+  end
+end

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

@@ -5,7 +5,7 @@ require "irb"
 require_relative "../ports/persistence/plugins/era"
 
 module Hecks
-  module CLI
+  module Tools
     # The command behind `hecks console` and Custodian's `Operation.OpenConsole`: boots a domain
     # (pizzas on Memory by default) and drops into IRB with its Ruby adapter installed, for
     # dispatching a

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

@@ -4,7 +4,7 @@ require "optparse"
 require_relative "../projections/deploy/template_diff"
 
 module Hecks
-  module CLI
+  module Tools
     # The command behind `hecks deploy template_comparison.diff`: compares two
     # CloudFormation templates offline and reports differences by logical id; `--strict` also
     # counts cosmetic differences (comments, key order).