agentilda 2.0.3 → 2.0.4

data/lib/agentilda/presentation/documentation.rb

@@ -0,0 +1,439 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Presentation
+    # Generates the conventions document from the state machine itself.
+    #
+    # The tables and the diagram are DERIVED — from {STATUSES}, {StateMachine.inbound}
+    # and {Ordinal} — so they cannot drift from the tool the way three
+    # hand-maintained copies of the status table already did.
+    #
+    # The prose is not derived, because a machine cannot invent the reasoning: why
+    # the tool refuses rather than guesses, why a retroactive plan gets its own
+    # number shape, what happens to this scheme if a real issue tracker arrives.
+    # That lives in the heredocs below, in one place, and is emitted alongside the
+    # generated parts.
+    class Documentation
+      # @return [String] the whole document
+      def render
+        [
+          header,
+          numbering,
+          starting,
+          status_table,
+          blocking,
+          transitions,
+          diagram,
+          files_section,
+          pull_requests,
+          footer
+        ].join("\n")
+      end
+
+      private
+
+      # @return [String]
+      def header
+        <<~MARKDOWN
+          # Spec → Plan → Build
+
+          > [!IMPORTANT]
+          > **This file is auto generated.**
+          >
+          > To regenerate it, run `agentilda docs` (which by the default
+          > writes to `${HOME}/.agents/context/workflow.md`). To override
+          > the destination, use the `-o | --output <file>` option.
+          >
+          > After changing the state machine. Editing it by hand puts it back into the
+          > condition it was written to end: three copies of the same table, quietly
+          > disagreeing.
+
+          Every project keeps its plans in a `#{Agentilda::PLANS_DIR}/` directory at its root.
+          Each medium-to-large feature gets one folder, and the folder's **name is its
+          state**: the number identifies it forever, the emoji says what phase it is in,
+          and the slug says what it is.
+
+          There are three phases, and each one has a file that proves it happened:
+
+          | Phase | State | The file that proves it |
+          | :---- | :---- | :---------------------- |
+          | **spec** | #{status(:new).emoji} #{status(:new).label} | `spec.md` |
+          | **plan** | #{status(:planned).emoji} #{status(:planned).label} | `plan.md` |
+          | **build** | #{status(:building).emoji} → #{status(:ready_for_review).emoji} → #{status(:in_review).emoji} → #{status(:approved).emoji} | `pull-requests.md` |
+
+          Those files are not paperwork. They are what the tool checks: a folder may not
+          claim a phase whose file is missing, and `agentilda resync dirs` renames
+          any folder whose emoji its contents do not support.
+
+        MARKDOWN
+      end
+
+      # @return [String]
+      def numbering
+        <<~MARKDOWN
+          ## The number
+
+          A plan's number is its identity. It is set once, when the folder is created,
+          and never changes: branch names, pull request titles and every
+          `pull-requests.md` join on it, and renumbering breaks all of them silently.
+
+          The shape is always `NNN.MM`:
+
+          ```
+          #{Agentilda::PLANS_DIR}/000.00-#{status(:new).emoji}-initial-spec
+          #{Agentilda::PLANS_DIR}/001.00-#{status(:approved).emoji}-dev-foundation
+          #{Agentilda::PLANS_DIR}/001.01-#{status(:approved).emoji}-schedule-k1-backfill   <- shipped between 001 and 002,
+          #{Agentilda::PLANS_DIR}/002.00-#{status(:planned).emoji}-tenancy-households        specified afterwards
+          ```
+
+          - **`NNN` counts from `000`.** The first plan of a project is `000.00`; after
+            that it is the highest major plus one, zero-padded to three digits.
+          - **`MM` is `00` for an ordinary plan** — one specified before it was built.
+          - **`MM` from `01` to `99` marks a retroactive plan**: work that shipped with no
+            specification, documented after the fact. `agentilda create --after 001`
+            takes the next free slot in the gap after 001.
+
+          `001.01` is a **sibling of 001 that arrived later, not a part of 001**. The dot
+          reads as containment in almost every other numbering scheme, and here it does
+          not — which is worth saying wherever the scheme is described, because the
+          containment reading is the one a new reader brings.
+
+          Two digits, always. One would sort into the middle of the two-digit range —
+          `001.09` < `001.1` < `001.10` — so a single mixed-width folder silently
+          reorders the index. Two digits also retire the question of running out: 99
+          slots per gap, against a gap that closes the moment the next plan is created.
+
+          > [!NOTE]
+          > Padding every plan to `NNN.MM` is a deliberate choice, and it costs something.
+          > A bare `018` next to `018.01` would have told you at a glance which plan was
+          > specified in advance and which was written afterwards. With uniform padding
+          > that distinction is no longer readable from the number alone — it is carried
+          > by `MM > 0`, which you have to know to look for. What padding buys is
+          > alignment and one shape to parse everywhere.
+
+          **A retroactive `spec.md` must open with a dated line saying so**, naming the
+          pull requests it describes. It documents what exists; it does not pretend to
+          have decided anything in advance. Anchor by *when the work merged*, not by what
+          it is about — compare merge dates against folder creation dates
+          (`git log --diff-filter=A`). Anchoring by topic invites an argument nobody can
+          settle, and the number is a slot, not a claim about subject matter.
+
+        MARKDOWN
+      end
+
+      # @return [String]
+      def starting
+        headings = Agentilda::Lifecycle::Brief::HEADINGS.map { |h| "- `## #{h}`" }.join("\n")
+
+        <<~MARKDOWN
+          ## Starting a feature that does not exist yet
+
+          `agentilda create <two to five words>` mints the folder at #{status(:new).emoji} #{status(:new).label}
+          and, for a genuinely new feature, scaffolds `spec.md` with a title and four
+          headings, verbatim:
+
+          #{headings}
+
+          `#{Agentilda::Lifecycle::Brief::AGENT_NAME}` — a half-agent: it runs only inside `create` and
+          holds no roster entry — then makes a best-effort attempt at each from what
+          the project already has on disk — its own docs, `#{Agentilda::Lifecycle::Brief::BACKLOG_FILE}` when
+          the project keeps one, anything already downloaded or already built that
+          bears on the topic — and opens the result for a human to finish.
+          `--no-draft` skips the attempt and leaves the headings bare; `--no-open`
+          leaves the file for you to open.
+
+          **Nothing else belongs in that first pass.** It writes no `## Goals`, no
+          `## Non-Goals`, no conclusions — deciding those before `leah-researcher` and
+          `yoda-writer` have looked is choosing the answer before the research runs.
+          Above all, it writes no heading beginning with the word "Research": that
+          heading is not decoration, it is the #{status(:researched).emoji} #{status(:researched).label} invariant, so writing
+          one — even empty — flips the folder's state out from under whoever reads it
+          next, and the research nobody did gets skipped rather than assigned.
+
+          This is only for work that does not exist yet. `create --after <plan> --prs
+          <n,...>` is the other path — the work already shipped, so `yoda-writer`
+          reconstructs the specification from the pull requests instead of guessing at
+          a feature that has no facts yet to guess from.
+
+        MARKDOWN
+      end
+
+      # @return [String]
+      def status_table
+        rows = Agentilda::Plans::STATUSES.map do |s|
+          required = s.requires.empty? ? "—" : s.requires.map { |f| "`#{f}`" }.join(", ")
+          "| #{s.emoji} | **#{s.label}** | `#{s.key}` | #{required} | #{s.note} |"
+        end
+
+        <<~MARKDOWN
+          ## The states
+
+          | Symbol | Meaning | Key | Files required | Description |
+          | :----: | :------ | :-- | :------------- | :---------- |
+          #{rows.join("\n")}
+
+          "Files required" is a **minimum**, not an exact match: a #{status(:new).emoji} folder that
+          has grown a `plan.md` still satisfies #{status(:new).emoji}, and is #{status(:planned).emoji} anyway. That is
+          why `resync dirs` moves a folder to the furthest state its contents justify
+          rather than only fixing outright lies.
+
+          Some states share their requirements on purpose, and are told apart only by the
+          folder name. #{status(:blocked).emoji} #{status(:blocked).label} and #{status(:product_blocked).emoji} #{status(:product_blocked).label} both mean "a human must
+          decide before this can move"; *which* human is recorded nowhere but the emoji.
+          #{Plans::StateMachine::FAMILIES.last.map { |k| status(k).emoji }.join(" ")} all mean "the work exists and pull requests are open"; whether
+          anyone has started reviewing is written down nowhere either.
+
+          So nothing re-derives one of them from a folder's contents — otherwise every
+          #{status(:blocked).emoji} would silently become #{status(:product_blocked).emoji} the first time anything resynced. A folder
+          falling back into that group from outside lands on its weakest member,
+          #{status(Plans::StateMachine::FAMILIES.last.first).emoji} #{status(Plans::StateMachine::FAMILIES.last.first).label}, because that is all its contents can prove.
+
+          #{merged_note}
+
+        MARKDOWN
+      end
+
+      # @return [String]
+      def merged_note
+        "🟣 Merged is deliberately **not** a folder state. It describes a pull request, " \
+          "and a folder that claimed it would be claiming a pull request's condition as its own."
+      end
+
+      # Why this is prose rather than another derived table: the mechanism is a
+      # rule about the *contents* of one file, and the only part of it a program
+      # can see is the invariant. Everything that makes the rule safe — a human
+      # types the command, an agent never answers anything — is a decision, and
+      # decisions belong in sentences.
+      #
+      # @return [String]
+      def blocking
+        settled = Plans::StateMachine::SETTLED.map { |k| status(k).emoji }.join(" ")
+
+        <<~MARKDOWN
+          ## When a plan is stopped, and how it starts again
+
+          #{status(:blocked).emoji} #{status(:blocked).label} and #{status(:product_blocked).emoji} #{status(:product_blocked).label} mean an agent hit a question that was not
+          its to answer and wrote `blocked.md` instead of guessing past it. Both belong to
+          the settled group `agentilda run` leaves alone (#{settled}), so the loop
+          never offers a stopped plan to anybody. A loop that could move one would make
+          the state mean nothing.
+
+          Questions are numbered `B1`, `B2`, and that numbering is how the file gets
+          referenced in conversation and in pull requests. **`blocked.md` holds open
+          questions and nothing else.** That is what the #{status(:blocked).emoji}/#{status(:product_blocked).emoji} invariant reads, so a
+          file naming no question justifies neither state and `resync dirs` renames the
+          folder out of it.
+
+          Which is how a block drains, in pieces:
+
+          1. A human writes each answer under `## Answers` as it arrives, dated and
+             attributed to whoever decided.
+          1. `agentilda unblock NNN --commit` hands the folder to `lando-broker`.
+             Nothing else reaches it: answers arriving is not a fact the tool can
+             observe, so a human running the command *is* the signal.
+          1. `lando-broker` folds each answered question into the document that question
+             was stopping — `spec.md` when the answer changes what we are building or
+             why, `plan.md` when it changes how or in what order — and deletes the
+             question and its answer from `blocked.md`.
+          1. When the last question goes, the file goes with it, and the folder leaves
+             #{status(:blocked).emoji} on the resync that follows.
+
+          An entry that names no decider, carries no date, or restates the options
+          instead of choosing one is not an answer, and is left exactly where it is.
+          So is any question nobody has answered yet: two answers out of five is a
+          successful run, and the plan stays stopped on the other three, which is true.
+          `lando-broker` never answers a question itself, and never retires one for
+          being stale — dropping a question is a human's call, and it makes the plan
+          #{status(:deferred).emoji} #{status(:deferred).label} or #{status(:discarded).emoji} #{status(:discarded).label}, not quietly shorter.
+
+        MARKDOWN
+      end
+
+      # @return [String]
+      def transitions
+        rows = Agentilda::Plans::STATUSES.map do |s|
+          out = Plans::StateMachine.outbound(s.key)
+          targets = out.empty? ? "_terminal_" : out.map { |k| status(k).emoji }.join(" ")
+          spine = Plans::StateMachine::SPINE[s.key]
+          "| #{s.emoji} #{s.label} | #{targets} | #{spine ? "#{status(spine).emoji} #{status(spine).label}" : "—"} |"
+        end
+
+        <<~MARKDOWN
+          ## Transitions
+
+          | From | May become | `promote` goes to |
+          | :--- | :--------- | :---------------- |
+          #{rows.join("\n")}
+
+          A bare promote walks the **spine** — spec → plan → build. Everything off it
+          (blocking, deferring, rejecting) has to be named explicitly. That is the whole
+          reason there is a machine here rather than a rename: a transition is refused
+          when the destination's requirements are not already met, and that refusal is
+          information — it means the phase has not actually happened yet.
+
+        MARKDOWN
+      end
+
+      # The picture is a hand-drawn PNG, not the mermaid block, because mermaid
+      # lays fifteen states out in a way nobody wants to read.
+      #
+      # The mermaid source is still emitted underneath it, and still derived from
+      # the machine — which is precisely what makes it the staleness check for a
+      # hand-drawn image. Regenerating this document rewrites that block from
+      # {STATUSES} and {StateMachine.inbound}, so a diff there means the PNG no
+      # longer matches. No diff there, no redraw.
+      #
+      # @return [String]
+      def diagram
+        edges = Plans::StateMachine.inbound.flat_map { |to, froms|
+          froms.map { |from| "    #{from} --> #{to}" }
+        }
+
+        <<~MARKDOWN
+
+          <details>
+          <summary>Mermaid source for the diagram above</summary>
+
+          ```mermaid
+          stateDiagram-v2
+              direction LR
+          #{Agentilda::Plans::STATUSES.map { |s| "    #{s.key} : #{s.emoji} #{s.label}" }.join("\n")}
+
+          #{edges.join("\n")}
+          ```
+
+          </details>
+
+        MARKDOWN
+      end
+
+      # @return [String]
+      def files_section
+        known = Agentilda::Plans::STATUSES
+                .flat_map(&:requires)
+                .uniq
+                .map { |f| "| `#{f}` | #{holders_of(f)} |" }
+
+        <<~MARKDOWN
+          ## Files allowed in a plan folder
+
+          | File | Required by |
+          | :--- | :---------- |
+          | `spec.md` | the specification; written first |
+          | `plan.md` | the execution plan; written from the spec |
+          | `implementation-plan.md` | the contract between the two halves of building |
+          #{known.reject { |r| r.start_with?("| `spec.md`", "| `plan.md`") }.join("\n")}
+
+          `implementation-plan.md` is the one file no state requires. `luke-backend`
+          writes it before it writes code, and `rey-frontend` builds from it a round
+          later: the interfaces the back end landed, their shapes and their errors,
+          which files each half owns, which units may run concurrently, and the one
+          test that proves the halves are joined rather than merely both present. No
+          state requires it because a plan with no back-end work never needs one.
+
+          Nothing else belongs there. A folder holding notes, diagrams or scratch files
+          is a folder nobody can audit at a glance.
+
+        MARKDOWN
+      end
+
+      # @param file [String]
+      # @return [String]
+      def holders_of(file)
+        Agentilda::Plans::STATUSES
+          .select { |s| s.requires.include?(file) }
+          .map { |s| "#{s.emoji} #{s.label}" }
+          .join(", ")
+      end
+
+      # @return [String]
+      def pull_requests
+        <<~MARKDOWN
+          ## Pull requests carry the number
+
+          A pull request that implements a plan says so in its title:
+
+          ```
+          [003.00] Make the core deterministic and require as_of
+          ```
+
+          `pull-requests.md` is generated from these titles, so the prefix is the join key
+          between a pull request and a plan, not decoration. Name branches
+          `<user>/NNN.MM-slug` and the number carries itself from branch creation through
+          to a merged, squashed pull request with nobody having to remember it.
+
+          `agentilda resync prs` fills in missing prefixes. It reads the branch name
+          first and falls back to the diff only when that touches exactly one plan folder.
+          **It refuses rather than guessing.** A wrong number does not announce itself: it
+          files the work under a plan that did not do it, and leaves the plan that did
+          looking untouched.
+
+          ### `[#{Agentilda::NO_PLAN_PREFIX}]` when there is no plan
+
+          Not every pull request implements a feature. Dependency bumps, CI configuration,
+          hotfixes and developer tooling implement no plan, and forcing a number onto them
+          produces a number chosen to satisfy the rule. Those are titled:
+
+          ```
+          [#{Agentilda::NO_PLAN_PREFIX}] Bump json from 2.21.1 to 2.21.2
+          ```
+
+          `#{Agentilda::NO_PLAN_PREFIX}` means **"this deliberately belongs to no specification"**, and it
+          exists so that "no plan" is *asserted* rather than merely absent. A title with no
+          prefix is ambiguous between "no plan applies" and "nobody looked".
+
+          `resync prs` will propose it, but marks every such title as **assumed** and never
+          applies one without you seeing it. Emitting it silently on a failed lookup would
+          launder "I could not tell" into "there is definitely none", which is the same
+          lie as guessing a number, told in the other direction.
+
+          ### What does not deserve a retroactive plan
+
+          Most unmatched pull requests. The test is whether **somebody would need to read
+          it** — a capability with behaviour, an interface, or invariants that are not
+          obvious from the code. "Fix a typo", "remove dead code" and "bump a dependency"
+          are `[#{Agentilda::NO_PLAN_PREFIX}]` and always were. Backfilling those produces an index that is
+          longer without being more informative, which makes the real plans harder to find.
+
+        MARKDOWN
+      end
+
+      # @return [String]
+      def footer
+        <<~MARKDOWN
+          ## If a real issue tracker arrives, this scheme retires
+
+          This numbering is homegrown because there is nothing else to join on. If the
+          work moves to Linear or Jira, **the issue key replaces it**: `[EQL-142] <title>`
+          in pull request titles, `EQL-142-<status>-<slug>` for the folder, and the issue
+          becomes the thing `pull-requests.md` is generated against.
+
+          Recording that matters more than it looks. A numbering scheme with no stated
+          exit becomes permanent by default: it accretes tooling, the tooling accretes
+          rules, and by the time a real tracker shows up, migrating is a project rather
+          than a decision. The exit is cheap only while it is written down and unbuilt.
+
+          Two things to hold to when that day comes:
+
+          - **Existing numbers are not rewritten.** A plan's number is its identity and
+            merged pull request titles are immutable history. `000` stays `000` forever and
+            new plans start taking issue keys. A mixed index is ugly for a while and honest
+            permanently, which beats a renumbering that breaks every link that ever pointed
+            at a plan.
+          - **Do not teach the tooling to accept issue keys before the tracker exists.** A
+            validator that accepts `[EQL-142]` with nothing to check it against is a guard
+            that passes anything shaped like an answer, which is worse than one that fails
+            loudly on first use.
+
+          ______________________________________________________________________
+
+          Generated by `agentilda docs` — version #{Agentilda::VERSION}.
+        MARKDOWN
+      end
+
+      # @param key [Symbol]
+      # @return [Agentilda::Plans::Status]
+      def status(key) = Agentilda::Plans::STATUS_BY_KEY.fetch(key)
+    end
+  end
+end

data/lib/agentilda/presentation/keyboard.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+module Agentilda
+  module Presentation
+    # Listens for single keypresses while a run is in flight, and turns them
+    # into {Control} broadcasts.
+    #
+    # The listener is a thread reading STDIN in raw mode, which only makes
+    # sense when STDIN is a terminal: piped input must never be eaten one byte
+    # at a time, and a run under cron has nobody at the keys. {.listen} returns
+    # nil in both cases and every caller treats nil as "no keyboard".
+    #
+    # Raw mode swallows Ctrl-C along with everything else, so ETX is forwarded
+    # to the main thread as the Interrupt it would have been — the listener
+    # must never make a run harder to kill than it was without one.
+    class Keyboard
+      # Key → what it does, rendered by {#help} and dispatched by {#handle}.
+      BINDINGS = [
+        ["h", "this help"],
+        ["?", "about agentilda"],
+        ["s", "select the next running agent; arrows move the selection"],
+        ["k", "mark the selected agent to be killed (STOP, 15s, then kill -9)"],
+        ["x", "extend the selected agent's clock by 10 minutes, per press"],
+        ["ENTER", "apply the pending changes in the dialog"],
+        ["ESC", "discard the dialog, then clear the selection"],
+        ["w", "ask every running agent to wrap up as fast as possible"],
+        ["n", "ask agents to write out what they have and stop; the loop continues"],
+        ["q", "write out, stop everything, and quit after a #{Execution::Control::GRACE}s grace"],
+        ["ctrl-c", "agents leave a resume note and stop, then quit; press again to abort now"]
+      ].freeze
+
+      # @param input [IO]
+      # @param sink [Agentilda::Presentation::Console, nil] where the table keys go; nil
+      #   when there is no screen, in which case they do nothing
+      # @return [Agentilda::Presentation::Keyboard, nil] a running listener, or nil when
+      #   STDIN is not a terminal
+      def self.listen(input: $stdin, sink: nil)
+        return nil unless input.tty?
+
+        new(input:, sink:).start
+      end
+
+      # @param input [IO]
+      # @param sink [Agentilda::Presentation::Console, nil]
+      def initialize(input: $stdin, sink: nil)
+        @input = input
+        @sink = sink
+      end
+
+      # @return [self]
+      def start
+        @thread = Thread.new do
+          Thread.current.report_on_exception = false
+          loop { handle(read_key) }
+        rescue IOError, Errno::EIO
+          # STDIN went away; a keyboard with no keys just stops listening.
+        end
+        self
+      end
+
+      # @return [void]
+      def stop
+        @thread&.kill
+        @thread = nil
+        restore
+      end
+
+      # `getch` puts the terminal in raw mode for the length of one read and
+      # restores it afterwards — but the listener spends almost all its life
+      # blocked inside that read, and {#stop} kills it there, which leaves
+      # the mode behind. Raw mode has output post-processing off, so a "\n"
+      # written after it drops a line without returning the cursor to column
+      # zero: the run report then starts wherever the previous line ended and
+      # staircases down the screen. Nothing else puts the mode back, so this
+      # does.
+      #
+      # @return [void]
+      def restore
+        @input.cooked! if @input.tty?
+      rescue IOError, SystemCallError
+        # No terminal left to put back; there is nothing to restore it to.
+      end
+
+      # @param key [String, nil]
+      # @return [void]
+      def handle(key)
+        case key
+        when "h" then @sink ? @sink.toggle_help : UI.popup("Keys", help)
+        when "?" then @sink ? @sink.toggle_about : UI.popup("About", about)
+        when "s", "\e[B" then @sink&.select_next
+        when "\e[A" then @sink&.select_prev
+        when "k" then @sink&.toggle_kill
+        when "x" then @sink&.extend
+        when "\r", "\n" then @sink&.apply
+        when "\e" then @sink&.escape
+        when "w" then acted("w — agents asked to wrap up") { Execution::Control.wrap_up! }
+        when "n" then acted("n — agents asked to write out and stop") { Execution::Control.stop! }
+        when "q" then acted("q — quitting; #{Execution::Control::GRACE}s grace to write out") { Execution::Control.quit! }
+        when "\u0003" then interrupt
+        end
+      end
+
+      # @return [String] the bindings, one per line, widest key first
+      def help
+        width = BINDINGS.map { |key, _| key.length }.max
+        BINDINGS.map { |key, does| "#{key.ljust(width)}   #{does}" }.join("\n")
+      end
+
+      # @return [String] the version and a reminder of how to leave
+      def about = "Agentilda Version #{Agentilda::VERSION}\n\nThanks for using this! Press 'q' to exit and stop all agents."
+
+      private
+
+      # ESC alone and ESC-[-A are the same first byte. Wait a few
+      # milliseconds for the rest before deciding it was a bare ESC.
+      #
+      # @return [String]
+      def read_key
+        key = @input.getch
+        return key unless key == "\e"
+
+        if IO.select([@input], nil, nil, 0.05)
+          rest = @input.read_nonblock(2, exception: false)
+          return "\e#{rest}" if rest.is_a?(String)
+        end
+        key
+      end
+
+      # Raw mode swallows the signal, so the key stands in for it: the first
+      # press lets agents write down where they got to, the second aborts.
+      #
+      # @return [void]
+      def interrupt
+        return Thread.main.raise(Interrupt) if Execution::Control.interrupted?
+
+        acted("ctrl-c — agents leaving resume notes; #{Execution::Control::GRACE}s grace, ctrl-c again to abort") { Execution::Control.interrupt! }
+      end
+
+      # A keypress with no acknowledgement looks like a keypress that did
+      # nothing, so each one says what it just asked for.
+      #
+      # @param note [String]
+      # @return [void]
+      def acted(note)
+        yield
+        UI.log(note)
+        # Under the dashboard, RatatuiRuby.run owns the alternate screen and
+        # repaints it continuously, so this raw `$stderr` write either never
+        # appears or is immediately overwritten — `UI.log` above is the only
+        # guaranteed record of w/n/q there. The line still matters without a
+        # screen (a dry run, a pipe), where this is all the feedback there is.
+        UI.line(note)
+      end
+    end
+  end
+end