hecks 3.4.2 → 3.6.0

data/lib/hecks/cli/interview_aggregate.rb

@@ -0,0 +1,132 @@
+require_relative "../naming"
+require_relative "interview_shape"
+
+module Hecks
+  module CLI
+    # The bluebook text of one accepted thing: its aggregate, with its value objects, commands and
+    # lifecycle. `InterviewDraft` extends it, and supplies the naming and citing helpers it calls.
+    module InterviewAggregate
+      # The pattern every generated string field carries: it refuses a blank value.
+      PATTERN = %q('[^ \t\n\r]').freeze
+
+      # What stands in for a creating command nothing in the interview named.
+      STUB_NOTE = "    # TODO: no action that creates was accepted; replace Create with the real one.".freeze
+
+      # One accepted thing: what it is called and identified by, its fields, its transitions, the
+      # actions that create it and the others.
+      Shape = Struct.new(:name, :identifier, :type, :fields, :steps, :creating, :rest, keyword_init: true)
+      private_constant :PATTERN, :STUB_NOTE, :Shape
+
+      # @api private
+      def aggregate(interview, thing, actions)
+        shape = shape_of(interview, thing, actions)
+        lines = head_lines(interview, thing, shape)
+        lines.concat(command_lines(interview, shape))
+        lines.concat(InterviewShape.lifecycle(shape.steps, shape.creating, shape.rest))
+        (lines << "  end").join("\n")
+      end
+
+      # What one accepted thing is made of: its fields, its actions, and its steps.
+      # @api private
+      def shape_of(interview, thing, actions)
+        name = word(thing[:name])
+        identifier = Naming.snake(word(thing[:identifier]))
+        type = identifier_type(name, identifier)
+        steps = of_thing(accepted(interview, :transitions), name)
+        mine = InterviewShape.merged_actions(of_thing(actions, name))
+        creating = mine.select { |a| a[:creates] }
+        Shape.new(name: name, identifier: identifier, type: type, steps: steps, creating: creating,
+                  fields: shape_fields(interview, [name, identifier, type], steps), rest: mine - creating)
+      end
+
+      # @api private
+      def shape_fields(interview, identity, steps)
+        name, identifier, type = identity
+        InterviewShape.fields(of_thing(accepted(interview, :fields), name), name, identifier, type,
+                              lifecycle: !steps.empty?)
+      end
+
+      # @api private
+      def of_thing(findings, name) = findings.select { |finding| word(finding[:thing]) == name }
+
+      # The aggregate's opening: its identity, its fields, and the value object of each.
+      # @api private
+      def head_lines(interview, thing, shape)
+        required = shape.creating.flat_map { |action| InterviewShape.takes(action) }
+        ["  # #{source_note(interview, thing)}".rstrip,
+         "  aggregate #{shape.name.inspect} do",
+         "    description #{"TODO: describe what a #{shape.name} is.".inspect}", "",
+         "    identified_by :#{shape.identifier}", "",
+         "    attribute :#{shape.identifier}, #{shape.type}",
+         *InterviewShape.attributes(shape.fields, required), "",
+         *type_lines(shape)]
+      end
+
+      # The value object that types the identifier, then the value object of each field.
+      # @api private
+      def type_lines(shape)
+        ["    value_object #{shape.type.inspect} do",
+         "      attribute :value, String, pattern: #{PATTERN}", "    end",
+         *InterviewShape.value_objects(shape.fields)]
+      end
+
+      # @api private
+      def command_lines(interview, shape)
+        creating = shape.creating.empty? ? [stub_create(shape.name)] : shape.creating
+        creating.flat_map { |action| creating_command(interview, action, shape) } +
+          shape.rest.flat_map { |action| mutating_command(interview, action, shape) }
+      end
+
+      # The creating command nothing in the interview named: a stub, marked for the developer.
+      # @api private
+      def stub_create(name) = { name: "Create", event: "#{name}Created", stub: true }
+
+      # @api private
+      def creating_command(interview, action, shape)
+        note = action[:stub] ? STUB_NOTE : "    # #{source_note(interview, action)}"
+        given, unknown = InterviewShape.inputs(action, shape.fields, shape.identifier)
+        command_open(action, note) +
+          ["      attribute :#{shape.identifier}, #{shape.type}",
+           *given.map { |f| "      attribute :#{f[:name]}, #{f[:type]}" }, *InterviewShape.unknown_lines(unknown), ""] +
+          command_close(action)
+      end
+
+      # @api private
+      def mutating_command(interview, action, shape)
+        given, unknown = InterviewShape.inputs(action, shape.fields, shape.identifier)
+        command_open(action, "    # #{source_note(interview, action)}") +
+          ["      reference_to #{shape.name}", *InterviewShape.input_lines(given), *InterviewShape.unknown_lines(unknown),
+           *InterviewShape.assignment_lines(given), ""] +
+          command_close(action)
+      end
+
+      # The lines every command opens with: a blank, its source note, its name, its goal and
+      # who may run it.
+      # @api private
+      def command_open(action, note)
+        verb = word(action[:name])
+        ["", note, "    command #{verb.inspect} do", "      goal #{"TODO: say what #{verb} does".inspect}",
+         *InterviewShape.who_lines(action), ""]
+      end
+
+      # @api private
+      def command_close(action) = ["      emits #{word(action[:event]).inspect}", "    end"]
+
+      # An action whose thing nobody accepted has nowhere to go; it is kept as a comment, not lost.
+      # @api private
+      def unplaced(interview, actions)
+        lines = ["  # UNPLACED: these accepted actions name a thing that was not accepted. Place each, or drop it."]
+        actions.each do |action|
+          lines << "  #   - #{cite(interview, action)} #{word(action[:name])} on #{action[:thing]}, announcing #{action[:event]}"
+        end
+        lines.join("\n")
+      end
+
+      # @api private
+      def identifier_type(name, field)
+        type = Naming.pascal(field)
+        type == name ? "#{type}Id" : type
+      end
+    end
+  end
+end

data/lib/hecks/cli/interview_draft.rb

@@ -1,6 +1,8 @@
 require_relative "../naming"
 require_relative "domain_stub"
 require_relative "interview_shape"
+require_relative "interview_record"
+require_relative "interview_aggregate"
 
 module Hecks
   module CLI
@@ -16,16 +18,8 @@ module Hecks
     module InterviewDraft
       ACCEPTED = "accepted".freeze
 
-      # The pattern every generated string field carries: it refuses a blank value.
-      PATTERN = %q('[^ \t\n\r]').freeze
-
-      # What stands in for a creating command nothing in the interview named.
-      STUB_NOTE = "    # TODO: no action that creates was accepted; replace Create with the real one.".freeze
-
-      # One accepted thing: what it is called and identified by, its fields, its transitions, the
-      # actions that create it and the others.
-      Shape = Struct.new(:name, :identifier, :type, :fields, :steps, :creating, :rest, keyword_init: true)
-      private_constant :PATTERN, :STUB_NOTE, :Shape
+      extend InterviewRecord
+      extend InterviewAggregate
 
       module_function
 
@@ -53,60 +47,14 @@ module Hecks
                                "```ruby\n#{fragment(interview)}```\n")
       end
 
-      # The interview's record: every exchange in order, and every finding with how it was decided.
-      #
-      # @param interview [Hash] the interview
-      # @return [String] Markdown
-      def record(interview)
-        lines = ["# Interview #{interview.fetch(:reference)}: #{interview.fetch(:subject)}", "",
-                 "Expert: #{interview.fetch(:expert)}", "", "## Exchanges", ""]
-        interview.fetch(:exchanges).each_with_index { |ex, i| lines.concat(exchange_lines(ex, i + 1)) }
-        lines << "" << "## Findings" << ""
-        lines.concat(finding_lines(interview))
-        "#{lines.join("\n")}\n"
-      end
-
-      # Reads the plain interview out of an `Interview` record booted from the SME chapter.
-      #
-      # @param interview [Object] the booted record
-      # @return [Hash] the plain interview this module takes: `reference`, `subject`, `expert`,
-      #   `exchanges` (`question`, `answer`, `topic`), and `things`, `actions`, `rules`,
-      #   `fields` and `transitions`, each a finding with its `number`, `source` and `status`
-      #   and the fields of its kind
-      def from_record(interview)
-        { reference: plain(interview.reference), subject: plain(interview.subject), expert: plain(interview.expert),
-          exchanges: interview.exchanges.map { |ex| slice(ex, :question, :answer, :topic) },
-          things:    interview.thing_findings.map { |f| slice(f, :number, :name, :identifier, :source, :status) },
-          actions:   interview.action_findings.map do |f|
-            slice(f, :number, :name, :thing, :event, :creates, :takes, :by, :source, :status)
-          end,
-          rules:     interview.rule_findings.map { |f| slice(f, :number, :statement, :source, :status) },
-          fields:    interview.field_findings.map { |f| slice(f, :number, :thing, :name, :values, :source, :status) },
-          transitions: interview.transition_findings.map do |f|
-            slice(f, :number, :thing, :action, :to, :from, :source, :status)
-          end }
-      end
-
-      # @api private
-      def record_file(interview, tail = "")
-        { "interviews/#{file_stem(interview.fetch(:reference))}.md" => record(interview) + tail }
-      end
-
-      # @api private
-      def file_stem(reference) = reference.to_s.gsub(/[^A-Za-z0-9._-]/, "_")
-
       # @api private
       def bluebook(interview)
         name = interview.fetch(:subject)
-        things = accepted(interview, :things)
-        raise ArgumentError, "nothing was accepted: a draft needs at least one thing" if things.empty?
+        raise ArgumentError, "nothing was accepted: a draft needs at least one thing" if accepted(interview, :things).empty?
 
-        out = ["Hecks.bluebook #{name.inspect} do"]
-        out.concat(header(interview))
-        out << %(  vision "TODO: say in one sentence what #{name} is for.")
-        out << "  supporting" << ""
-        out.concat(rule_lines(interview))
-        out << fragment(interview).chomp << "end"
+        out = ["Hecks.bluebook #{name.inspect} do"] + header(interview) +
+              [%(  vision "TODO: say in one sentence what #{name} is for."), "  supporting", ""] +
+              rule_lines(interview) + [fragment(interview).chomp, "end"]
         "#{out.join("\n")}\n"
       end
 
@@ -115,13 +63,19 @@ module Hecks
       def fragment(interview)
         things = accepted(interview, :things).uniq { |t| word(t[:name]) }
         actions = accepted(interview, :actions)
-        placed = things.map { |t| word(t[:name]) }
         blocks = things.map { |thing| aggregate(interview, thing, actions) }
-        loose = actions.reject { |a| placed.include?(word(a[:thing])) }
+        loose = loose_actions(things, actions)
         blocks << unplaced(interview, loose) unless loose.empty?
         "#{blocks.join("\n\n")}\n"
       end
 
+      # The accepted actions whose thing nobody accepted.
+      # @api private
+      def loose_actions(things, actions)
+        placed = things.map { |t| word(t[:name]) }
+        actions.reject { |a| placed.include?(word(a[:thing])) }
+      end
+
       # @api private
       def header(interview)
         ["  # Drafted from interview #{interview[:reference]} with #{interview[:expert]}. Each name below cites the",
@@ -137,130 +91,6 @@ module Hecks
           rules.map { |r| "  #   - #{cite(interview, r)} #{one_line(r[:statement])}" } + [""]
       end
 
-      # @api private
-      def aggregate(interview, thing, actions)
-        shape = shape_of(interview, thing, actions)
-        lines = head_lines(interview, thing, shape)
-        lines.concat(command_lines(interview, shape))
-        lines.concat(InterviewShape.lifecycle(shape.steps, shape.creating, shape.rest))
-        (lines << "  end").join("\n")
-      end
-
-      # What one accepted thing is made of: its fields, its actions, and its steps.
-      # @api private
-      def shape_of(interview, thing, actions)
-        name = word(thing[:name])
-        identifier = Naming.snake(word(thing[:identifier]))
-        mine = InterviewShape.merged_actions(actions.select { |a| word(a[:thing]) == name })
-        steps = accepted(interview, :transitions).select { |s| word(s[:thing]) == name }
-        found = accepted(interview, :fields).select { |f| word(f[:thing]) == name }
-        type = identifier_type(name, identifier)
-        fields = InterviewShape.fields(found, name, identifier, type, lifecycle: !steps.empty?)
-        creating = mine.select { |a| a[:creates] }
-        Shape.new(name: name, identifier: identifier, type: type, fields: fields, steps: steps,
-                  creating: creating, rest: mine - creating)
-      end
-
-      # The aggregate's opening: its identity, its fields, and the value object of each.
-      # @api private
-      def head_lines(interview, thing, shape)
-        required = shape.creating.flat_map { |action| InterviewShape.takes(action) }
-        ["  # #{source_note(interview, thing)}".rstrip,
-         "  aggregate #{shape.name.inspect} do",
-         "    description #{"TODO: describe what a #{shape.name} is.".inspect}", "",
-         "    identified_by :#{shape.identifier}", "",
-         "    attribute :#{shape.identifier}, #{shape.type}",
-         *InterviewShape.attributes(shape.fields, required), "",
-         "    value_object #{shape.type.inspect} do",
-         "      attribute :value, String, pattern: #{PATTERN}", "    end",
-         *InterviewShape.value_objects(shape.fields)]
-      end
-
-      # @api private
-      def command_lines(interview, shape)
-        creating = shape.creating.empty? ? [stub_create(shape.name)] : shape.creating
-        creating.flat_map { |action| creating_command(interview, action, shape) } +
-          shape.rest.flat_map { |action| mutating_command(interview, action, shape) }
-      end
-
-      # The creating command nothing in the interview named: a stub, marked for the developer.
-      # @api private
-      def stub_create(name) = { name: "Create", event: "#{name}Created", stub: true }
-
-      # @api private
-      def creating_command(interview, action, shape)
-        verb = word(action[:name])
-        note = action[:stub] ? STUB_NOTE : "    # #{source_note(interview, action)}"
-        given, unknown = InterviewShape.inputs(action, shape.fields, shape.identifier)
-        ["", note, "    command #{verb.inspect} do", "      goal #{"TODO: say what #{verb} does".inspect}",
-         *InterviewShape.who_lines(action), "", "      attribute :#{shape.identifier}, #{shape.type}",
-         *given.map { |f| "      attribute :#{f[:name]}, #{f[:type]}" }, *InterviewShape.unknown_lines(unknown), "",
-         "      emits #{word(action[:event]).inspect}", "    end"]
-      end
-
-      # @api private
-      def mutating_command(interview, action, shape)
-        verb = word(action[:name])
-        given, unknown = InterviewShape.inputs(action, shape.fields, shape.identifier)
-        ["", "    # #{source_note(interview, action)}", "    command #{verb.inspect} do",
-         "      goal #{"TODO: say what #{verb} does".inspect}", *InterviewShape.who_lines(action), "",
-         "      reference_to #{shape.name}", *InterviewShape.input_lines(given), *InterviewShape.unknown_lines(unknown),
-         *InterviewShape.assignment_lines(given), "", "      emits #{word(action[:event]).inspect}", "    end"]
-      end
-
-      # An action whose thing nobody accepted has nowhere to go; it is kept as a comment, not lost.
-      # @api private
-      def unplaced(interview, actions)
-        lines = ["  # UNPLACED: these accepted actions name a thing that was not accepted. Place each, or drop it."]
-        actions.each do |action|
-          lines << "  #   - #{cite(interview, action)} #{word(action[:name])} on #{action[:thing]}, announcing #{action[:event]}"
-        end
-        lines.join("\n")
-      end
-
-      # @api private
-      def identifier_type(name, field)
-        type = Naming.pascal(field)
-        type == name ? "#{type}Id" : type
-      end
-
-      # @api private
-      def exchange_lines(exchange, number)
-        lines = ["#{number}. **Q:** #{one_line(exchange[:question])}", "   **A:** #{one_line(exchange[:answer])}"]
-        topic = exchange[:topic].to_s
-        lines << "   _Topic: #{one_line(topic)}_" unless topic.empty?
-        lines
-      end
-
-      # @api private
-      def finding_lines(interview)
-        lines = interview.fetch(:things).map do |f|
-          "- Thing #{f[:number]}, #{f[:status]}: **#{f[:name]}**, identified by `#{f[:identifier]}` (exchange #{f[:source]})"
-        end
-        lines += interview.fetch(:actions).map { |f| action_line(f) }
-        lines += interview.fetch(:fields, []).map do |f|
-          values = f[:values].to_s.strip.empty? ? "" : ", one of #{f[:values]}"
-          "- Field #{f[:number]}, #{f[:status]}: **#{f[:name]}** on #{f[:thing]}#{values} (exchange #{f[:source]})"
-        end
-        lines += interview.fetch(:transitions, []).map do |f|
-          from = f[:from].to_s.strip.empty? ? "" : " from #{f[:from]}"
-          "- Transition #{f[:number]}, #{f[:status]}: **#{f[:action]}** on #{f[:thing]} to #{f[:to]}#{from} " \
-            "(exchange #{f[:source]})"
-        end
-        lines + interview.fetch(:rules).map do |f|
-          "- Rule #{f[:number]}, #{f[:status]}: #{one_line(f[:statement])} (exchange #{f[:source]})"
-        end
-      end
-
-      # @api private
-      def action_line(finding)
-        creates = finding[:creates] ? ", creates it" : ""
-        takes = finding[:takes].to_s.strip.empty? ? "" : ", takes #{finding[:takes]}"
-        by = finding[:by].to_s.strip.empty? ? "" : ", by #{finding[:by]}"
-        "- Action #{finding[:number]}, #{finding[:status]}: **#{finding[:name]}** on #{finding[:thing]}, " \
-          "announcing `#{finding[:event]}`#{creates}#{takes}#{by} (exchange #{finding[:source]})"
-      end
-
       # @api private
       def accepted(interview, kind) = interview.fetch(kind, []).select { |finding| finding[:status] == ACCEPTED }
 
@@ -268,9 +98,6 @@ module Hecks
       # @api private
       def word(text) = text.to_s.split(/[^A-Za-z0-9]+/).reject(&:empty?).map { |part| part.sub(/\A./, &:upcase) }.join
 
-      # @api private
-      def one_line(text) = text.to_s.gsub(/\s+/, " ").strip
-
       # @api private
       def cite(interview, finding) = "#{interview[:reference]} ##{finding[:source]}:"
 
@@ -285,17 +112,6 @@ module Hecks
         text = "#{text[0, 77]}..." if text.length > 80
         "#{note} #{text.inspect}"
       end
-
-      # @api private
-      def plain(value)
-        return nil if value.nil?
-
-        found = value.respond_to?(:to_h) && !value.is_a?(String) ? value.to_h : value
-        found.is_a?(Hash) && found.key?(:value) ? found[:value] : found
-      end
-
-      # @api private
-      def slice(record, *keys) = keys.to_h { |key| [key, plain(record[key])] }
     end
   end
 end

data/lib/hecks/cli/interview_record.rb

@@ -0,0 +1,130 @@
+module Hecks
+  module CLI
+    # The Markdown record of an interview, and the plain interview read out of a booted record.
+    # `InterviewDraft` extends it.
+    module InterviewRecord
+      # The keys each kind of finding carries into the plain interview, in the order they are read.
+      FINDING_KEYS = {
+        things:      [:number, :name, :identifier, :source, :status],
+        actions:     [:number, :name, :thing, :event, :creates, :takes, :by, :source, :status],
+        rules:       [:number, :statement, :source, :status],
+        fields:      [:number, :thing, :name, :values, :source, :status],
+        transitions: [:number, :thing, :action, :to, :from, :source, :status]
+      }.freeze
+
+      # The interview's record: every exchange in order, and every finding with how it was decided.
+      #
+      # @param interview [Hash] the interview
+      # @return [String] Markdown
+      def record(interview)
+        lines = ["# Interview #{interview.fetch(:reference)}: #{interview.fetch(:subject)}", "",
+                 "Expert: #{interview.fetch(:expert)}", "", "## Exchanges", ""]
+        interview.fetch(:exchanges).each_with_index { |ex, i| lines.concat(exchange_lines(ex, i + 1)) }
+        lines << "" << "## Findings" << ""
+        lines.concat(finding_lines(interview))
+        "#{lines.join("\n")}\n"
+      end
+
+      # Reads the plain interview out of an `Interview` record booted from the SME chapter.
+      #
+      # @param interview [Object] the booted record
+      # @return [Hash] the plain interview this module takes: `reference`, `subject`, `expert`,
+      #   `exchanges` (`question`, `answer`, `topic`), and `things`, `actions`, `rules`,
+      #   `fields` and `transitions`, each a finding with its `number`, `source` and `status`
+      #   and the fields of its kind
+      def from_record(interview)
+        plain_interview = { reference: plain(interview.reference), subject: plain(interview.subject),
+                            expert: plain(interview.expert),
+                            exchanges: interview.exchanges.map { |ex| slice(ex, :question, :answer, :topic) } }
+        FINDING_KEYS.each { |kind, keys| plain_interview[kind] = plain_findings(interview, kind, keys) }
+        plain_interview
+      end
+
+      # @api private
+      def plain_findings(interview, kind, keys)
+        interview.public_send(:"#{kind.to_s.chomp("s")}_findings").map { |finding| slice(finding, *keys) }
+      end
+
+      # @api private
+      def record_file(interview, tail = "")
+        { "interviews/#{file_stem(interview.fetch(:reference))}.md" => record(interview) + tail }
+      end
+
+      # @api private
+      def file_stem(reference) = reference.to_s.gsub(/[^A-Za-z0-9._-]/, "_")
+
+      # @api private
+      def exchange_lines(exchange, number)
+        lines = ["#{number}. **Q:** #{one_line(exchange[:question])}", "   **A:** #{one_line(exchange[:answer])}"]
+        topic = exchange[:topic].to_s
+        lines << "   _Topic: #{one_line(topic)}_" unless topic.empty?
+        lines
+      end
+
+      # @api private
+      def finding_lines(interview)
+        interview.fetch(:things).map { |f| thing_line(f) } +
+          interview.fetch(:actions).map { |f| action_line(f) } +
+          shape_finding_lines(interview) +
+          interview.fetch(:rules).map { |f| rule_line(f) }
+      end
+
+      # The field and transition findings, which an interview may not carry at all.
+      # @api private
+      def shape_finding_lines(interview)
+        interview.fetch(:fields, []).map { |f| field_line(f) } +
+          interview.fetch(:transitions, []).map { |f| transition_line(f) }
+      end
+
+      # @api private
+      def thing_line(finding)
+        "- Thing #{finding[:number]}, #{finding[:status]}: **#{finding[:name]}**, " \
+          "identified by `#{finding[:identifier]}` (exchange #{finding[:source]})"
+      end
+
+      # @api private
+      def action_line(finding)
+        creates = finding[:creates] ? ", creates it" : ""
+        "- Action #{finding[:number]}, #{finding[:status]}: **#{finding[:name]}** on #{finding[:thing]}, " \
+          "announcing `#{finding[:event]}`#{creates}#{clause("takes", finding[:takes])}" \
+          "#{clause("by", finding[:by])} (exchange #{finding[:source]})"
+      end
+
+      # @api private
+      def field_line(finding)
+        "- Field #{finding[:number]}, #{finding[:status]}: **#{finding[:name]}** on #{finding[:thing]}" \
+          "#{clause("one of", finding[:values])} (exchange #{finding[:source]})"
+      end
+
+      # @api private
+      def transition_line(finding)
+        from = finding[:from].to_s.strip.empty? ? "" : " from #{finding[:from]}"
+        "- Transition #{finding[:number]}, #{finding[:status]}: **#{finding[:action]}** on #{finding[:thing]} " \
+          "to #{finding[:to]}#{from} (exchange #{finding[:source]})"
+      end
+
+      # @api private
+      def rule_line(finding)
+        "- Rule #{finding[:number]}, #{finding[:status]}: #{one_line(finding[:statement])} (exchange #{finding[:source]})"
+      end
+
+      # A `, label value` clause, or nothing when the value is blank.
+      # @api private
+      def clause(label, value) = value.to_s.strip.empty? ? "" : ", #{label} #{value}"
+
+      # @api private
+      def one_line(text) = text.to_s.gsub(/\s+/, " ").strip
+
+      # @api private
+      def plain(value)
+        return nil if value.nil?
+
+        found = value.respond_to?(:to_h) && !value.is_a?(String) ? value.to_h : value
+        found.is_a?(Hash) && found.key?(:value) ? found[:value] : found
+      end
+
+      # @api private
+      def slice(record, *keys) = keys.to_h { |key| [key, plain(record[key])] }
+    end
+  end
+end

data/lib/hecks/cli/interview_run.rb

@@ -25,7 +25,8 @@ module Hecks
       # @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)
+      def call(name:, adapter: nil, dir: nil, expert: nil, use_ai: true, input: $stdin, output: $stdout, agent: nil, # rubocop:disable Metrics/ParameterLists -- one keyword per setting the command takes
+               runtime: nil)
         DomainStub.support_files(name: name, adapter: adapter)
         target = File.expand_path(dir || DomainStub.directory(name), Dir.pwd)
         expert = who(expert, input, output)
@@ -34,7 +35,14 @@ module Hecks
                                       subject: name, expert: expert).call
         return "" unless result.status == :concluded
 
-        report(target, DomainWriter.write!(files(result.interview, adapter, target), target))
+        write_domain(result.interview, adapter, target, output)
+      end
+
+      # Writes the files the interview decided and prints the report.
+      #
+      # @api private
+      def write_domain(interview, adapter, target, output)
+        report(target, DomainWriter.write!(files(interview, adapter, target), target))
           .tap { |text| output.puts(text) }
       end
 
@@ -66,21 +74,24 @@ module Hecks
 
       # @api private
       def next_reference(target)
-        "INT-#{Dir.glob(File.join(target, 'interviews', 'INT-*.md')).length + 1}"
+        "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}/:"] +
+        lines = ["wrote #{written.length} #{written.length == 1 ? "file" : "files"} in #{where}/:"] +
                 written.sort.map { |path| "  #{path}" }
-        lines << "" << "next:"
+        (lines + next_steps(written, where)).join("\n")
+      end
+
+      # @api private
+      def next_steps(written, where)
         if written.any? { |path| path.start_with?("bluebook/") }
-          lines << "  hecks docs #{where}/bluebook" << "  hecks console subject=#{where}"
+          ["", "next:", "  hecks docs #{where}/bluebook", "  hecks console subject=#{where}"]
         else
-          lines << "  merge the proposed additions in #{where}/#{written.first} into the domain's bluebook"
+          ["", "next:", "  merge the proposed additions in #{where}/#{written.first} into the domain's bluebook"]
         end
-        lines.join("\n")
       end
     end
   end

data/lib/hecks/cli/interview_session/agent_state.rb

@@ -0,0 +1,70 @@
+module Hecks
+  module CLI
+    class InterviewSession
+      # What the session tells the agent: the interview so far, what was accepted, and the gaps.
+      module AgentState
+        private
+
+        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:     accepted_actions(plain),
+            fields:      InterviewDraft.accepted(plain, :fields).map { |f| f.slice(:thing, :name, :values) },
+            transitions: InterviewDraft.accepted(plain, :transitions).map { |f| f.slice(:thing, :action, :to, :from) },
+            rules:       InterviewDraft.accepted(plain, :rules).map { |f| f.slice(:statement) } }
+        end
+
+        def accepted_actions(plain)
+          InterviewDraft.accepted(plain, :actions).map { |f| f.slice(:name, :thing, :event, :creates, :takes, :by) }
+        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)
+          action_gaps(things, actions) + shape_gaps(plain, things, actions)
+        end
+
+        def action_gaps(things, actions)
+          idle_gaps(things, actions) + uncreated_gaps(things, actions) + unplaced_gaps(things, actions)
+        end
+
+        def idle_gaps(things, actions)
+          things.reject { |t| actions.any? { |a| a[:thing] == t } }.map { |t| "nothing is yet said to happen to #{t}" }
+        end
+
+        def uncreated_gaps(things, actions)
+          things.reject { |t| actions.any? { |a| a[:thing] == t && a[:creates] } }.map { |t| "nothing yet creates #{t}" }
+        end
+
+        # Actions on a thing nobody accepted.
+        def unplaced_gaps(things, actions)
+          actions.reject { |a| things.include?(a[:thing].to_s) }.map { |a| "#{a[:name]} names #{a[:thing]}, not yet a thing" }
+        end
+
+        # What a thing is not yet said to have, and how it moves from one state to the next.
+        def shape_gaps(plain, things, actions)
+          bare_gaps(things, InterviewDraft.accepted(plain, :fields)) +
+            unmoved_gaps(things, actions, InterviewDraft.accepted(plain, :transitions))
+        end
+
+        def bare_gaps(things, fields)
+          things.reject { |t| fields.any? { |f| f[:thing] == t } }
+                .map { |t| "nothing is yet said #{t} has, beyond its identifier" }
+        end
+
+        def unmoved_gaps(things, actions, steps)
+          changing = things.select { |t| actions.count { |a| a[:thing] == t && !a[:creates] } > 1 }
+          changing.reject { |t| steps.any? { |s| s[:thing] == t } }
+                  .map { |t| "nothing yet says how #{t} moves from one state to the next" }
+        end
+      end
+    end
+  end
+end