hecks 3.1.0 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29694d3639f1ad69a3d0a81bf4e6494c5a6d60a88ca9897af3a01224944d654e
-  data.tar.gz: b9fb1376266fe98b2d09c6127bbbbe3a954c11e9441c3f01976e54f44b63eaf7
+  metadata.gz: e8bfb40ad9e9760533d77e179154821128fee28930877e35118b5e87c5c32731
+  data.tar.gz: 49fd0e562e846d8633c11101d7b11c6d751089c8ca0f281907f1c669e1d19438
 SHA512:
-  metadata.gz: 6eea28ed2426948aeca13df88967f06a5d64acf29dbb376a16b53d82367e90383f3646928ee4940ff9d93969ea7721ed29fb4467096eb8a2b88bc14f7f7ede47
-  data.tar.gz: 52d5f117ce1b1bae946f939dad3c73567a44c5c466257c37cbaf5bb7bcecb0cb3a3ea92e9c41b3edde78efbdb674669d08f56305287f46313c1cb4ce813d3042
+  metadata.gz: e584bed9d83942763f583530d44910d6a988c7b55af6a4177f257ba017562957f373ea7ea726340b7ae845e2811d7217665ab6815991ae9cffb0e6cb437928c2
+  data.tar.gz: 6cac69c95c6dedc28736d5401d64a6597327c27b8d3ed1909c225ad6191c4cb0cac929ac9f3896f5c648c890d75b10d6d4b3d5431498e82e560bd682f2dc312d

data/exe/hecks

@@ -24,7 +24,7 @@ end
 # These commands keep nothing worth a database, so they run on Memory unless told otherwise.
 # A person is at them: they wait for their result, say why when they are refused, and print
 # no record when they end well.
-MEMORY_COMMANDS = %w[console init].freeze
+MEMORY_COMMANDS = %w[console init interview].freeze
 ENV["HECKS_ENVIRONMENT"] ||= "memory" if MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))
 ARGV << "--wait" if MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!")) && !ARGV.include?("--wait")
 

data/lib/hecks/chapters.rb

@@ -5,8 +5,8 @@ require_relative "bluebook/meta_validator"
 
 module Hecks
   # The chapters the gem carries that a hecksagon can attach by name (ADR 0080): the language
-  # declared in itself, Expression, Tenancy, Deploy, Site and QualityControl. Framework members stay
-  # in `Framework`; `table` and `attach!` find a name across both.
+  # declared in itself, Expression, Tenancy, Deploy, Site, Tickets and QualityControl. Framework
+  # members stay in `Framework`; `table` and `attach!` find a name across both.
   #
   # A chapter is named by the `Hecks.bluebook "Name"` header of its files, and may span several.
   # Beside its bluebook a chapter may carry what every hecksagon attaching it needs, whatever
@@ -15,7 +15,8 @@ module Hecks
   module Chapters
     # Where attachable chapters live, relative to `lib/hecks/`.
     GLOBS = %w[language/**/*.bluebook grammar/expression.bluebook tenancy/bluebook/*.bluebook
-               deploy/bluebook/*.bluebook site/bluebook/*.bluebook quality_control/*.bluebook].freeze
+               deploy/bluebook/*.bluebook site/bluebook/*.bluebook tickets/bluebook/*.bluebook
+               quality_control/*.bluebook].freeze
 
     # Every attachable chapter, by name, with the files that declare it.
     #

data/lib/hecks/cli/domain_writer.rb

@@ -0,0 +1,39 @@
+require "fileutils"
+
+module Hecks
+  module CLI
+    # Writes the files `hecks init` and `hecks interview` produce, never replacing one (ADR 0087).
+    #
+    # Every target is checked before the first is written, so a refusal leaves nothing half-written.
+    module DomainWriter
+      module_function
+
+      # @param files [Hash{String => String}] each file's path under the target, and its text
+      # @param target [String] the absolute path of the domain directory
+      # @return [Array<String>] the paths written, relative to the target
+      # @raise [ArgumentError] when any file, or a bluebook the files would add, is already there
+      def write!(files, target)
+        taken = taken(files, target)
+        raise ArgumentError, "nothing written; already there: #{taken.join(', ')}" unless taken.empty?
+
+        files.each do |path, text|
+          full = File.join(target, path)
+          FileUtils.mkdir_p(File.dirname(full))
+          File.write(full, text)
+        end
+        files.keys
+      end
+
+      # @param files [Hash{String => String}] the files about to be written
+      # @param target [String] the domain directory
+      # @return [Array<String>] the paths in the way, relative to the target
+      def taken(files, target)
+        taken = files.keys.select { |path| File.exist?(File.join(target, path)) }
+        if files.keys.any? { |path| path.match?(%r{\Abluebook/[^/]+\.bluebook\z}) }
+          taken |= Dir.glob(File.join(target, "bluebook", "*.bluebook")).map { |full| full.delete_prefix("#{target}/") }
+        end
+        taken
+      end
+    end
+  end
+end

data/lib/hecks/cli/interview_agent.rb

@@ -0,0 +1,59 @@
+require_relative "../runtime/registry"
+require_relative "../ports/agent"
+
+module Hecks
+  module CLI
+    # 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.
+    class InterviewAgent
+      PORT = File.expand_path("../ports/agent.port", __dir__)
+      CLAUDE_CODE = File.expand_path("../adapters/driven/claude_code.adapter", __dir__)
+
+      # The agent a real interview uses: the developer's own `claude`, no key or model of hecks's.
+      #
+      # @return [InterviewAgent] one resolved against the Claude Code adapter
+      def self.claude
+        require_relative "../adapters/driven/claude_code"
+        new(registry_with(CLAUDE_CODE))
+      end
+
+      # @param adapter_files [Array<String>] adapter declarations to load beside the agent port
+      # @return [Runtime::Registry] a registry in which exactly those adapters implement the port
+      def self.registry_with(*adapter_files)
+        registry = Runtime::Registry.new
+        Hecks.with_registry(registry) do
+          Kernel.load(PORT)
+          adapter_files.each { |file| Kernel.load(file) }
+        end
+        registry
+      end
+
+      # @return [Boolean] whether a `claude` executable is on the path, so a model can be tried
+      def self.claude_available?
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? { |dir| File.executable?(File.join(dir, "claude")) }
+      end
+
+      # @param registry [Runtime::Registry] a registry with the agent port and one adapter for it
+      def initialize(registry)
+        @registry = registry
+      end
+
+      # @param state [Hash] the interview so far, as the session describes it
+      # @param asked [Array<String>] the questions already asked
+      # @return [Ports::Agent::Question, nil] the next question, or nil if the adapter offered none
+      # @raise [Ports::Agent::Unavailable, Ports::Agent::ValidationError] when it could not answer
+      def question(state:, asked:)
+        Ports::Agent.ask(@registry, state: state, asked: asked).first
+      end
+
+      # @param prose [String] what the expert just said, as the developer typed it
+      # @param state [Hash] the interview so far
+      # @return [Array<Ports::Agent::Proposal>] the findings the sentence names; none for a question
+      # @raise [Ports::Agent::Unavailable, Ports::Agent::ValidationError] when it could not answer
+      def proposals(prose:, state:)
+        Ports::Agent.interpret(@registry, prose: prose, state: state)
+      end
+    end
+  end
+end

data/lib/hecks/cli/interview_run.rb

@@ -0,0 +1,87 @@
+require_relative "../../hecks"
+require_relative "domain_stub"
+require_relative "domain_writer"
+require_relative "interview_agent"
+require_relative "interview_session"
+
+module Hecks
+  module CLI
+    # The command behind `hecks interview <Name>` (ADR 0088): boots the SME chapter on demand, holds
+    # the interview at the terminal, then writes the first domain, or the next interview's proposed
+    # additions, and says what to type next. Nothing is written unless the interview concludes.
+    module InterviewRun
+      SME = File.expand_path("../sme", __dir__)
+
+      module_function
+
+      # @param name [String] the domain being discovered, as its bluebook will spell it
+      # @param adapter [String, nil] a persistence adapter from `DomainStub::ADAPTERS`
+      # @param dir [String, nil] where the domain goes; the snake-cased name here when nil
+      # @param expert [String, nil] who is interviewed; asked for when nil
+      # @param use_ai [Boolean] false runs the plain prompts (`--no-ai`)
+      # @param input [#gets] where the developer types
+      # @param output [#puts, #print] where the session speaks
+      # @param agent [#question, #proposals, nil] an interviewer to use instead of the real one
+      # @param runtime [Runtime, nil] a booted SME chapter to use instead of booting one
+      # @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, runtime: nil)
+        DomainStub.support_files(name: name, adapter: adapter)
+        target = File.expand_path(dir || DomainStub.directory(name), Dir.pwd)
+        expert = who(expert, input, output)
+        result = InterviewSession.new(runtime: runtime || Hecks.boot(SME), agent: interviewer(use_ai, agent, output),
+                                      input: input, output: output, reference: next_reference(target),
+                                      subject: name, expert: expert).call
+        return "" unless result.status == :concluded
+
+        report(target, DomainWriter.write!(files(result.interview, adapter, target), target))
+          .tap { |text| output.puts(text) }
+      end
+
+      # @api private
+      def who(expert, input, output)
+        return expert unless expert.to_s.strip.empty?
+
+        output.print("Who is the expert? ")
+        input.gets.to_s.strip.then { |text| text.empty? ? "the expert" : text }
+      end
+
+      # @api private
+      def interviewer(use_ai, agent, output)
+        return nil unless use_ai
+        return agent if agent
+        return InterviewAgent.claude if InterviewAgent.claude_available?
+
+        output.puts("`claude` is not installed, so this runs without the AI. Use --no-ai to skip this note.")
+        nil
+      end
+
+      # The first interview names a domain; a later one finds a bluebook there and offers additions.
+      # @api private
+      def files(interview, adapter, target)
+        return InterviewDraft.additions(interview) unless Dir.glob(File.join(target, "bluebook", "*.bluebook")).empty?
+
+        InterviewDraft.files(interview, adapter: adapter)
+      end
+
+      # @api private
+      def next_reference(target)
+        "INT-#{Dir.glob(File.join(target, 'interviews', 'INT-*.md')).length + 1}"
+      end
+
+      # @api private
+      def report(target, written)
+        where = target.delete_prefix("#{Dir.pwd}/")
+        lines = ["wrote #{written.length} #{written.length == 1 ? 'file' : 'files'} in #{where}/:"] +
+                written.sort.map { |path| "  #{path}" }
+        lines << "" << "next:"
+        if written.any? { |path| path.start_with?("bluebook/") }
+          lines << "  hecks docs #{where}/bluebook" << "  hecks console subject=#{where}"
+        else
+          lines << "  merge the proposed additions in #{where}/#{written.first} into the domain's bluebook"
+        end
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/hecks/cli/interview_session.rb

@@ -0,0 +1,299 @@
+require_relative "interview_draft"
+
+module Hecks
+  module CLI
+    # 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
+    # back from the expert, records it, asks the agent what the answer names as findings, and puts
+    # each to the developer to accept or reject. The agent never dispatches anything. Every SME
+    # command is dispatched here, so the domain's own rules are the guard on the interview.
+    #
+    # With no agent (`--no-ai`), or for a turn the agent could not answer, a plain prompt stands in:
+    # a fixed question, and findings typed by the developer.
+    class InterviewSession
+      NOTICE = "Your answers are sent to a model through your own `claude` login. " \
+               "Run with --no-ai to leave it out.".freeze
+
+      FALLBACK_QUESTIONS = [
+        "What is the main thing this business keeps track of?",
+        "What happens to it, from the beginning to the end?",
+        "What must never happen?",
+        "Is there anything else I should know?"
+      ].freeze
+
+      TASK = "You interview a subject matter expert, through the developer who sits beside them, about the " \
+             "business domain called %<subject>s, so the developer can model it. Ask one plain-language " \
+             "question at a time about what the business keeps track of, what happens to it, and what must " \
+             "never happen. Use the expert's own words. Do not assume what kind of business it is, or an " \
+             "industry, from the name of the domain: learn it from what the expert says. When you interpret " \
+             "an answer, propose findings only with the verbs listed under `verbs`, using the argument " \
+             "names given there, and nothing else.".freeze
+
+      VERBS = {
+        "SME::Interview.ProposeThing"  => {
+          "meaning"   => "a thing the business keeps track of, and the field that identifies one of it",
+          "arguments" => %w[name identifier]
+        },
+        "SME::Interview.ProposeAction" => {
+          "meaning"   => "something that happens to a thing, and the event it announces, in the past tense",
+          "arguments" => %w[name thing event creates]
+        },
+        "SME::Interview.ProposeRule"   => {
+          "meaning"   => "a rule the expert stated, in their own words",
+          "arguments" => %w[statement]
+        }
+      }.freeze
+
+      # What each finding verb needs, and the SME commands that carry it out and decide it.
+      KINDS = {
+        "SME::Interview.ProposeThing"  => { kind: "thing", fields: %w[name identifier], propose: :propose_thing!,
+                                           entity: "ThingFinding", accept: "AcceptThing", reject: "RejectThing" },
+        "SME::Interview.ProposeAction" => { kind: "action", fields: %w[name thing event creates],
+                                            propose: :propose_action!, entity: "ActionFinding",
+                                            accept: "AcceptAction", reject: "RejectAction" },
+        "SME::Interview.ProposeRule"   => { kind: "rule", fields: %w[statement], propose: :propose_rule!,
+                                          entity: "RuleFinding", accept: "AcceptRule", reject: "RejectRule" }
+      }.freeze
+
+      TRUE_WORDS = %w[true yes y 1].freeze
+
+      Result = Struct.new(:status, :interview, keyword_init: true)
+
+      # @param runtime [Runtime] the booted SME chapter
+      # @param agent [#question, #proposals, nil] the interviewer; nil runs the plain prompts
+      # @param input [#gets] where the developer types
+      # @param output [#puts, #print] where the session speaks
+      # @param reference [String] the interview's reference, such as `INT-1`
+      # @param subject [String] the domain being discovered, as its bluebook will spell it
+      # @param expert [String] who is being interviewed
+      def initialize(runtime:, agent:, input:, output:, reference:, subject:, expert:)
+        @runtime = runtime
+        @agent = agent
+        @input = input
+        @output = output
+        @reference = reference
+        @subject = subject
+        @expert = expert
+        @asked = []
+        @number = 0
+        @suggested = false
+      end
+
+      # Holds the interview until the developer finishes or quits.
+      #
+      # @return [Result] `concluded` with the plain interview (see `InterviewDraft`), or `cancelled`
+      def call
+        ::Interview.plan!(reference: @reference, subject: @subject, expert: @expert).begin!
+        say("#{NOTICE}\n") if @agent
+        say("Type done when there is enough to start, or quit to stop and write nothing.\n")
+        turn until finished?
+        outcome
+      end
+
+      private
+
+      def outcome
+        return Result.new(status: :cancelled) if @cancelled
+
+        Result.new(status: :concluded, interview: InterviewDraft.from_record(current))
+      end
+
+      def finished? = @finished
+
+      def current = ::Interview.find(@reference)
+
+      def turn
+        question = next_question
+        say("\n#{question}")
+        answer = ask("> ")
+        return end_of_input if answer.nil?
+
+        case answer.strip.downcase
+        when "" then say("Say what the expert said, or type done.")
+        when "done" then conclude
+        when "quit" then cancel
+        else answered(question, answer.strip)
+        end
+      end
+
+      def answered(question, answer)
+        current.record!(question: question, answer: answer)
+        @asked << question
+        findings_from(answer)
+        suggest_enough
+      end
+
+      def next_question
+        asked = @asked.dup
+        proposed = @agent && ask_agent { @agent.question(state: state, asked: asked) }
+        text = proposed&.text
+        return text if text && !@asked.include?(text)
+
+        FALLBACK_QUESTIONS.find { |q| !@asked.include?(q) } || FALLBACK_QUESTIONS.last
+      end
+
+      def findings_from(answer)
+        proposals = @agent && ask_agent { @agent.proposals(prose: answer, state: state) }
+        return manual_findings unless proposals
+
+        proposals.each { |proposal| review(proposal) }
+      end
+
+      # Runs one call to the agent; a turn it cannot answer is said aloud, and a plain one follows.
+      def ask_agent
+        yield
+      rescue Ports::Agent::Unavailable, Ports::Agent::ValidationError => e
+        say("The AI could not answer (#{e.message.lines.first.to_s.strip}). Using a plain prompt for this turn.")
+        nil
+      end
+
+      def review(proposal)
+        config = KINDS[proposal.verb]
+        return say("Ignored a proposal for #{proposal.verb}: not a finding I know.") unless config
+
+        fields = fields_of(proposal, config)
+        missing = config[:fields].reject { |f| f == "creates" || fields[f].to_s.strip != "" }
+        return say("Ignored a #{config[:kind]} proposal with no #{missing.join(', ')}.") unless missing.empty?
+
+        number = propose(config, fields) or return
+        say("  Proposed #{describe(config, fields)}")
+        say("  because: #{proposal.rationale}")
+        decide(config, number, accept?("  Accept? [Y/n] "))
+      end
+
+      def fields_of(proposal, config)
+        rows = proposal.arguments.to_h { |row| [row[:name].to_s, row[:value]] }
+        fields = rows.slice(*config[:fields])
+        fields["creates"] = TRUE_WORDS.include?(fields["creates"].to_s.downcase) if fields.key?("creates")
+        fields
+      end
+
+      def propose(config, fields)
+        number = (@number += 1)
+        args = fields.transform_keys(&:to_sym).merge(number: number, source: current.exchanges.size)
+        current.public_send(config[:propose], **args)
+        number
+      rescue StandardError => e
+        say("  Could not keep that finding: #{reason(e)}")
+        nil
+      end
+
+      def decide(config, number, accepted)
+        verb = accepted ? config[:accept] : config[:reject]
+        @runtime.dispatch_flat("SME::Interview.#{config[:entity]}.#{verb}",
+                               reference: { value: @reference }, number: { value: number })
+        say(accepted ? "  Accepted." : "  Rejected.")
+      rescue StandardError => e
+        say("  Could not record the decision: #{reason(e)}")
+      end
+
+      def describe(config, fields)
+        case config[:kind]
+        when "thing" then "thing: #{fields['name']}, identified by #{fields['identifier']}"
+        when "action" then "action: #{fields['name']} on #{fields['thing']}, announcing #{fields['event']}" \
+                           "#{', creating it' if fields['creates']}"
+        else "rule: #{fields['statement']}"
+        end
+      end
+
+      # The plain prompt: findings typed by the developer, accepted as they are entered.
+      def manual_findings
+        loop do
+          kind = ask("Add a finding from that answer? thing, action or rule (enter to skip): ")
+          kind = kind.to_s.strip.downcase
+          break if kind.empty?
+
+          typed = typed_finding(kind) or next say("  I only know thing, action and rule.")
+          config = KINDS["SME::Interview.Propose#{kind.capitalize}"]
+          number = propose(config, typed) or next
+          decide(config, number, true)
+        end
+      end
+
+      def typed_finding(kind)
+        case kind
+        when "thing" then named("Name" => "name", "Identified by" => "identifier")
+        when "action" then typed_action
+        when "rule" then named("The rule, in the expert's words" => "statement")
+        end
+      end
+
+      def typed_action
+        fields = named("Name" => "name", "On which thing" => "thing", "It announces (event)" => "event") or return nil
+        fields.merge("creates" => TRUE_WORDS.include?(ask("  Does it create the thing? [y/N] ").to_s.strip.downcase))
+      end
+
+      def named(prompts)
+        fields = prompts.to_h { |label, key| [key, ask("  #{label}: ").to_s.strip] }
+        fields.values.all? { |v| !v.empty? } ? fields : nil
+      end
+
+      def suggest_enough
+        return if @suggested || !enough?
+
+        @suggested = true
+        say("\nI think we have enough to start. Type done to finish, or keep answering.")
+      end
+
+      def enough?
+        plain = InterviewDraft.from_record(current)
+        InterviewDraft.accepted(plain, :things).any? && InterviewDraft.accepted(plain, :actions).any?
+      end
+
+      def conclude
+        current.conclude!
+        @finished = true
+      rescue StandardError => e
+        say("Not finished yet: #{reason(e)}.")
+      end
+
+      def cancel
+        current.cancel!
+        @cancelled = @finished = true
+        say("Stopped. Nothing was written.")
+      end
+
+      def end_of_input
+        conclude
+        cancel unless @finished
+      end
+
+      def accept?(label)
+        !%w[n no].include?(ask(label).to_s.strip.downcase)
+      end
+
+      def state
+        plain = InterviewDraft.from_record(current)
+        { task: format(TASK, subject: @subject), subject: @subject, expert: @expert, verbs: VERBS,
+          exchanges: plain[:exchanges].each_with_index.map { |e, i| e.slice(:question, :answer).merge(number: i + 1) },
+          accepted: accepted_state(plain), gaps: gaps(plain) }
+      end
+
+      def accepted_state(plain)
+        { things:  InterviewDraft.accepted(plain, :things).map { |f| f.slice(:name, :identifier) },
+          actions: InterviewDraft.accepted(plain, :actions).map { |f| f.slice(:name, :thing, :event, :creates) },
+          rules:   InterviewDraft.accepted(plain, :rules).map { |f| f.slice(:statement) } }
+      end
+
+      # What the interview has not yet pinned down, in words a model can act on.
+      def gaps(plain)
+        things = InterviewDraft.accepted(plain, :things).map { |t| t[:name].to_s }
+        actions = InterviewDraft.accepted(plain, :actions)
+        gaps = things.reject { |t| actions.any? { |a| a[:thing] == t } }.map { |t| "nothing is yet said to happen to #{t}" }
+        gaps += things.reject { |t| actions.any? { |a| a[:thing] == t && a[:creates] } }.map { |t| "nothing yet creates #{t}" }
+        unplaced = actions.reject { |a| things.include?(a[:thing].to_s) }
+        gaps + unplaced.map { |a| "#{a[:name]} names #{a[:thing]}, not yet a thing" }
+      end
+
+      def reason(error) = error.message.sub(/\A[A-Z]\w* refused\s+[—-]\s+/, "").strip
+
+      def ask(label)
+        @output.print(label)
+        @input.gets&.chomp
+      end
+
+      def say(text) = @output.puts(text)
+    end
+  end
+end

data/lib/hecks/corpus.rb

@@ -32,6 +32,7 @@ module Hecks
       language:  "lib/hecks/language/**/*.bluebook",
       deploy:    "lib/hecks/deploy/bluebook/*.bluebook",
       site:      "lib/hecks/site/bluebook/*.bluebook",
+      tickets:   "lib/hecks/tickets/bluebook/*.bluebook",
       tenancy:   "lib/hecks/tenancy/bluebook/*.bluebook",
       sme:       "lib/hecks/sme/bluebook/*.bluebook",
       fixture:   "spec/fixtures/**/*.bluebook"

data/lib/hecks/doors/cli_runner.rb

@@ -104,7 +104,7 @@ module Hecks
       # @return [Array(String, Integer), nil] the text and status, or nil when the line would
       #   run a command or question and so needs a booted domain
       def usage(runtime:, argv:, program: "hecks run")
-        resolve(runtime, argv, program)[:answer]
+        UsageCache.fetch(runtime, argv, program) { resolve(runtime, argv, program)[:answer] }
       end
 
       # Parses a command line against the projection: either the answer it gives without

data/lib/hecks/doors/usage_cache.rb

@@ -0,0 +1,123 @@
+require "digest"
+require "fileutils"
+require "json"
+
+module Hecks
+  module Doors
+    # Remembers the help a launcher prints, so a repeat `hecks` need not read the domain again.
+    #
+    # The help is a pure function of the domain's declarations and of the gem that projects them,
+    # and reading those is most of what a launcher costs. The answer is kept in a file named for a
+    # digest of everything it depends on (the domain's declaration files, the gem's own library,
+    # the hecks and Ruby versions, the environment overlay, the command line and the program name),
+    # so any edit to one of them is simply a different entry: nothing is ever stale, only unused.
+    # Only an answer that ended well is kept, and any trouble with the cache itself is ignored
+    # and the help is worked out as if it did not exist.
+    #
+    # `HECKS_NO_USAGE_CACHE=1` turns it off; `HECKS_CACHE_DIR` moves it.
+    module UsageCache
+      # The variable that turns the cache off when set to anything but empty or `0`.
+      DISABLE_VARIABLE = "HECKS_NO_USAGE_CACHE".freeze
+      # The variable that names the directory the cache lives in.
+      DIRECTORY_VARIABLE = "HECKS_CACHE_DIR".freeze
+      # The declaration files whose contents shape a help text.
+      DECLARATIONS = "*.{bluebook,world,hecksagon,rb}".freeze
+      # How long an unused entry stays before the next write sweeps it away.
+      KEEP_SECONDS = 14 * 24 * 60 * 60
+
+      module_function
+
+      # Answers the cached help for this command line, or works it out with the block and
+      # remembers it.
+      #
+      # @param runtime [#directory] what `Hecks.describe` answered; anything else bypasses the cache
+      # @param argv [Array<String>] the command line
+      # @param program [String] how the caller was invoked
+      # @yield works the answer out, loading the domain
+      # @yieldreturn [Array(String, Integer), nil] the text and status; nil if it runs a command
+      # @return [Array(String, Integer), nil] the block's answer, or the remembered one
+      def fetch(runtime, argv, program)
+        directory = runtime.respond_to?(:directory) ? runtime.directory : nil
+        return yield unless directory && enabled?
+
+        file = entry_path(directory, argv, program)
+        remembered = file && recall(file)
+        return remembered if remembered
+
+        answer = yield
+        remember(file, answer) if file && answer&.last&.zero?
+        answer
+      end
+
+      # @return [Boolean] whether the cache is on
+      def enabled?
+        off = ENV[DISABLE_VARIABLE].to_s
+        off.empty? || off == "0"
+      end
+
+      # @return [String] the directory entries live in
+      def directory
+        ENV[DIRECTORY_VARIABLE] || File.join(ENV["XDG_CACHE_HOME"] || File.join(Dir.home, ".cache"), "hecks")
+      end
+
+      # The file that holds the answer for this command line, named by what it depends on.
+      #
+      # @return [String, nil] nil when the digest cannot be taken
+      def entry_path(domain, argv, program)
+        digest = Digest::SHA256.new
+        [Hecks::VERSION, RUBY_VERSION, ENV["HECKS_ENVIRONMENT"].to_s, program, argv.join("\0")].each do |part|
+          digest << part.to_s << "\0"
+        end
+        [domain, library].each { |root| fingerprint(root, digest) }
+        File.join(directory, "usage-#{digest.hexdigest}.json")
+      rescue SystemCallError
+        nil
+      end
+
+      # Feeds the digest every declaration file under `root`: its path, size and modification time.
+      def fingerprint(root, digest)
+        Dir.glob(File.join(root, "**", DECLARATIONS)).each do |file|
+          stat = File.stat(file)
+          digest << file << ":" << stat.size.to_s << ":" << stat.mtime.to_f.to_s << "\0"
+        end
+      end
+
+      # @return [String] the gem's own library directory, which the frameworks load from
+      def library
+        File.expand_path("..", __dir__)
+      end
+
+      # Reads the remembered answer and marks the entry as used, so a sweep keeps what is read.
+      #
+      # @return [Array(String, Integer), nil] the remembered answer, or nil when none can be trusted
+      def recall(file)
+        record = JSON.parse(File.read(file))
+        File.utime(nil, nil, file)
+        [record.fetch("text"), record.fetch("status")]
+      rescue SystemCallError, JSON::ParserError, KeyError
+        nil
+      end
+
+      # Writes the answer beside its name and sweeps entries nobody has read for a while.
+      def remember(file, answer)
+        FileUtils.mkdir_p(File.dirname(file))
+        scratch = "#{file}.#{Process.pid}"
+        File.write(scratch, JSON.generate("text" => answer.first, "status" => answer.last))
+        File.rename(scratch, file)
+        sweep(File.dirname(file))
+      rescue SystemCallError
+        nil
+      end
+
+      # Removes the entries older than `KEEP_SECONDS`.
+      def sweep(dir)
+        cutoff = Time.now - KEEP_SECONDS
+        Dir.glob(File.join(dir, "usage-*.json")).each do |entry|
+          File.delete(entry) if File.mtime(entry) < cutoff
+        end
+      rescue SystemCallError
+        nil
+      end
+    end
+  end
+end