principles 0.0.1

data/lib/principles/models/write_up_opening.rb

@@ -0,0 +1,93 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # The opening of a write-up's region in a file's text: what list-open-findings prints as a finding's
+    # write_up_opening, and show-answer-check previews (#300, #411). This tool does not judge what it says.
+    class WriteUpOpening
+      # The longest opening printed whole; a longer one is cut and marked truncated.
+      LIMIT = 200
+      # A line that starts a new block, a list item or a heading, rather than continuing the paragraph before it.
+      NEW_BLOCK = /\A(([-*+]|\d+[.)])\s|#)/
+      # What a heading line starts with, a block of its own line.
+      HEADING = "#"
+      # The end of a sentence: its mark and any closing quotes or brackets, before a space or the end.
+      SENTENCE_END = /[.!?]["')\]]*(?=\s|\z)/
+
+      # One line of the file, as the opening reads it.
+      class Line
+        #: (String) -> void
+        def initialize(text)
+          @text = text
+          freeze
+        end
+
+        # The line without its indentation or line break.
+        #: () -> String
+        def text = @text.strip
+
+        #: () -> bool
+        def blank? = text.empty?
+
+        #: () -> bool
+        def heading? = text.start_with?(HEADING)
+
+        # Whether the line continues the paragraph before it: it is not blank and starts no new block. It keeps its
+        # line break, which NEW_BLOCK's \s may match, so a bare "-" line still starts a list item.
+        #: () -> bool
+        def continues? = !blank? && !@text.lstrip.match?(NEW_BLOCK)
+      end
+
+      # lines are the file's lines; the region runs from index first up to, not including, index last.
+      #: (lines: Array[String], first: Integer, last: Integer) -> void
+      def initialize(lines:, first:, last:)
+        @lines = lines.map { |each| Line.new(each) } #: Array[Line]
+        @first = first
+        @last = last
+        freeze
+      end
+
+      # The opening from the region's first non-blank line, with that line's number. nil when every line in the
+      # region is blank.
+      #: () -> Hash[String, untyped]?
+      def to_h
+        index = (@first...@last).find { |each| !line(each).blank? } or return nil
+        text = opening_text(index)
+        { "text" => text[0, LIMIT], "line" => index + 1 }.merge(text.length > LIMIT ? { "truncated" => true } : {})
+      end
+
+      private
+
+      # A heading line whole, since a heading is not a sentence and "F4." may number it (#739). Otherwise the
+      # first sentence: hard-wrapped lines joined with single spaces up to the sentence's end, or else to its
+      # paragraph's end, a blank line, the next list item or heading, or the file's end. It runs past the region's
+      # end, since a starting_at alone locates one line (#697).
+      #: (Integer) -> String
+      def opening_text(index)
+        return line(index).text if line(index).heading?
+
+        sentence(paragraph_from(index).join(" "))
+      end
+
+      # The trimmed lines of the paragraph that starts at index, to its end in the file.
+      #: (Integer) -> Array[String]
+      def paragraph_from(index)
+        rest = @lines.drop(index + 1).take_while(&:continues?)
+        [line(index), *rest].map(&:text)
+      end
+
+      # text up to the end of its first sentence, or all of it when none ends.
+      #: (String) -> String
+      def sentence(text)
+        found = SENTENCE_END.match(text) or return text
+        text[0, found.end(0)].to_s
+      end
+
+      # The line at index, or a blank one past the file's end.
+      #: (Integer) -> Line
+      def line(index) = @lines[index] || Line.new("")
+    end
+  end
+end

data/lib/principles/models/write_up_pointer.rb

@@ -0,0 +1,50 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "locator"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # Where a finding is written up, as its record's recorded_at keeps it: a path, with a heading or a starting_at
+    # inside it (#768). It holds that place as the Locator the hash it was read from gives, which keeps its keys, nulls
+    # and order, since the record's bytes and each digest over them depend on it; two pointers are the same when
+    # those hashes hold the same keys and values, in any order.
+    class WriteUpPointer
+      #: (Hash[String, untyped]) -> void
+      def initialize(fields)
+        @locator = Locator.new(fields) #: Locator
+        freeze
+      end
+
+      # The file the write-up is in.
+      #: () -> String
+      def path = @locator.path
+
+      # Whether it names a starting_at inside its file.
+      #: () -> bool
+      def starting_at? = !@locator.starting_at.nil?
+
+      # The same heading or starting_at in the file at path, as a repoint checks git's match for a missing file (#722).
+      #: (String) -> WriteUpPointer
+      def in_file(path) = WriteUpPointer.new(to_h.merge("path" => path))
+
+      # The opening of its write-up in project's file as it stands now, as WriteUpOpening finds it, or nil when there
+      # is none; refused when the pointer no longer resolves (#300).
+      #: (Project) -> Hash[String, untyped]?
+      def opening_in(project) = project.member_file(path).write_up_opening(@locator)
+
+      # The pointer as its record's file holds it.
+      #: () -> Hash[String, untyped]
+      def to_h = @locator.to_h
+
+      #: (untyped) -> bool
+      def ==(other) = other.is_a?(WriteUpPointer) && other.to_h.eql?(to_h)
+
+      alias eql? ==
+
+      #: () -> Integer
+      def hash = to_h.hash
+    end
+  end
+end

data/lib/principles/models/write_up_repoint.rb

@@ -0,0 +1,39 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "answer_fields"
+require_relative "recorded_finding"
+require_relative "write_up_pointer"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # One finding's write-up pointer moved by a repoint (D59): the finding it names, the recorded_at the agent
+    # found the write-up at, and why. It moves a finding there, keeping where it pointed before, when and why.
+    class WriteUpRepoint
+      # The repoint one entry of an answer's repoints gives, to recorded_at, its pointer already located, refused by
+      # fields without a reason, since the record keeps why each pointer moved (#760), naming its place in the answer
+      # (#787).
+      #: (Hash[String, untyped], WriteUpPointer, AnswerFields, AnswerPlace) -> WriteUpRepoint
+      def self.answered(repoint, recorded_at, fields, place)
+        new(finding_id: repoint.fetch("finding_id"), recorded_at: recorded_at,
+            reason: fields.text_at(repoint["reason"], "repoint.reason", place.child("reason")))
+      end
+
+      #: String
+      attr_reader :finding_id
+
+      #: (finding_id: String, recorded_at: WriteUpPointer, reason: String) -> void
+      def initialize(finding_id:, recorded_at:, reason:)
+        @finding_id = finding_id
+        @recorded_at = recorded_at
+        @reason = reason
+        freeze
+      end
+
+      # finding moved to this repoint's recorded_at, for its reason, at at.
+      #: (RecordedFinding, at: String) -> RecordedFinding
+      def applied_to(finding, at:) = finding.moved_to(@recorded_at, at: at, reason: @reason)
+    end
+  end
+end

data/lib/principles/prose_list.rb

@@ -0,0 +1,23 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Principles
+  # Items as one would say them in a sentence: "a", "a and b", or "a, b and c", or with "or" for alternatives. It
+  # is the one owner of that list, which several results and refusals print (#445, #731, #737), so every layer may
+  # load it, as it may error.rb.
+  class ProseList
+    #: (Array[String], ?conjunction: String) -> void
+    def initialize(items, conjunction: "and")
+      @items = items
+      @conjunction = conjunction
+      freeze
+    end
+
+    #: () -> String
+    def to_s
+      return @items.join if @items.length < 2
+
+      "#{@items.take(@items.length - 1).join(", ")} #{@conjunction} #{@items.last}"
+    end
+  end
+end

data/lib/principles/supported_ruby.rb

@@ -0,0 +1,93 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Principles
+  # The Ruby this tool runs on. exe/principles loads this before anything else, so an agent on a Ruby too old to
+  # parse lib/ still gets this tool's JSON refusal, not a SyntaxError. So this file stays in syntax any Ruby 2
+  # parses, and requires only rbconfig: a GEM_HOME left by another Ruby can hand an old Ruby a json it cannot
+  # parse. When the Ruby running is unsupported, it looks for a supported one that rbenv installed, since
+  # rbenv otherwise picks Ruby by the directory this tool runs in, and runs this tool on that instead (D31).
+  # Its bounds equal the gemspec's required_ruby_version; a spec checks it.
+  class SupportedRuby
+    MINIMUM = [3, 4, 2].freeze #: Array[Integer]
+    BELOW = [3, 5].freeze #: Array[Integer]
+    # Set on the process this tool hands itself to, so a Ruby that is not what its folder name says cannot
+    # hand it on again.
+    HANDED_OFF = "PRINCIPLES_HANDED_TO_RUBY"
+
+    #: (String, Hash[String, String]) -> void
+    def initialize(running, environment)
+      @running = running
+      @environment = environment
+    end
+
+    # Returns when this Ruby is supported; otherwise runs executable on a supported rbenv Ruby, or prints the
+    # refusal and exits 1.
+    #: (String, Array[String]) -> void
+    def run_here_or_on_another(executable, arguments)
+      step = next_step(executable, arguments)
+      return if step.key?("run_here")
+
+      if step.key?("hand_to")
+        process = Kernel #: as untyped
+        process.exec(*step.fetch("hand_to"))
+      end
+      warn step.fetch("refuse")
+      exit 1
+    end
+
+    # What this tool does on this Ruby, decided without acting: run_here; hand_to, the arguments for Kernel.exec
+    # that run executable on a supported rbenv Ruby; or refuse, the refusal to print before exiting 1.
+    #: (String, Array[String]) -> Hash[String, untyped]
+    def next_step(executable, arguments)
+      return { "run_here" => true } if supported?(@running)
+
+      other = rbenv_ruby
+      if other && !@environment[HANDED_OFF]
+        return { "hand_to" => [{ HANDED_OFF => other }, other, executable, *arguments] }
+      end
+
+      { "refuse" => refusal }
+    end
+
+    private
+
+    #: (String) -> bool
+    def supported?(version)
+      numbers = version.split(".").map(&:to_i)
+      (numbers <=> MINIMUM) >= 0 && (numbers <=> BELOW).negative?
+    end
+
+    # The newest supported Ruby among rbenv's installed versions, if any.
+    #: () -> String?
+    def rbenv_ruby
+      root = @environment["RBENV_ROOT"] || File.join(@environment["HOME"].to_s, ".rbenv")
+      found = Dir.glob(File.join(root, "versions", "*", "bin", "ruby")).select do |ruby|
+        supported?(version_of(ruby)) && File.executable?(ruby)
+      end
+      found.max_by { |ruby| version_of(ruby).split(".").map(&:to_i) }
+    end
+
+    # The version rbenv installed ruby as: the name of its folder under versions/.
+    #: (String) -> String
+    def version_of(ruby)
+      # File.dirname's level argument needs Ruby 3.1, and this runs on older Rubies.
+      File.basename(File.dirname(File.dirname(ruby))) # rubocop:disable Style/NestedFileDirname
+    end
+
+    # This tool's refusal as JSON, written by hand because json may not load here.
+    #: () -> String
+    def refusal
+      require "rbconfig"
+      needed = ">= #{MINIMUM.join(".")} and < #{BELOW.join(".")}"
+      fields = [%w[status refused], %w[code unsupported_ruby],
+                ["message", "This tool needs Ruby #{needed}; this is Ruby #{@running} at #{RbConfig.ruby}, and rbenv " \
+                            "has no Ruby it supports"],
+                ["repair", "In Claude Code with the principles plugin, ask the user to run /principles:setup-ruby, " \
+                           "which installs one with rbenv and ruby-build. Otherwise install a Ruby #{needed} with " \
+                           "rbenv; it finds any rbenv Ruby it supports, whatever directory it runs in."]]
+      quoted = fields.map { |pair| pair.map { |text| "\"#{text.gsub(/[\\"]/) { |c| "\\#{c}" }}\"" }.join(":") }
+      "{#{quoted.join(",")}}"
+    end
+  end
+end

data/lib/principles/version.rb

@@ -0,0 +1,11 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Principles
+  # The next production release, as major.minor.patch. A production build is versioned with this alone.
+  RELEASE = "0.0.1"
+  # The version a built gem prints. `rake build[production]` stamps RELEASE here, in the copy of lib/ it
+  # packages, and `rake build[development]` stamps RELEASE.g<short sha>. A checkout leaves it nil, and
+  # Data::RunningVersion reads the commit this tool runs from instead.
+  BUILT_VERSION = "0.0.1" #: String?
+end

data/lib/principles/views/acknowledged_since_last_audit.rb

@@ -0,0 +1,34 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "prompts"
+
+module Principles
+  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
+  module Views
+    # The edits to one member acknowledged since the last full audit, as the next full audit's request shows them
+    # beside the member, so edits judged one at a time are judged together against the last audited text (D33).
+    class AcknowledgedSinceLastAudit
+      # last_audited_commit is the last full audit's base commit; acknowledgements are the record's own, oldest
+      # first; member_lines its own lines then and now, as a one-member audit shows them. The command that reads every
+      # edit since is the member's read_the_change, which every member judged again carries (#771).
+      #: (last_audited_commit: String, member_lines: Hash[String, untyped],
+      #|  acknowledgements: Array[Hash[String, untyped]]) -> void
+      def initialize(last_audited_commit:, member_lines:, acknowledgements:)
+        @last_audited_commit = last_audited_commit
+        @member_lines = member_lines
+        @acknowledgements = acknowledgements
+        freeze
+      end
+
+      # The fields as the request prints them.
+      #: () -> Hash[String, untyped]
+      def to_h
+        { "last_audited_commit" => @last_audited_commit,
+          "acknowledgements" => @acknowledgements.map { |each| each.slice("commit", "reason", "acknowledged_at") },
+          "member_lines" => @member_lines,
+          "why" => Prompts.text("assess-every-member/judge-acknowledged-edits-together") }
+      end
+    end
+  end
+end

data/lib/principles/views/acknowledgement_result.rb

@@ -0,0 +1,44 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "invocation"
+require_relative "member_change_since_baseline"
+require_relative "prompts"
+
+module Principles
+  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
+  module Views
+    # A one-member audit's request and its result (D33).
+    class AcknowledgementResult
+      #: (Invocation) -> void
+      def initialize(invocation)
+        @invocation = invocation
+        freeze
+      end
+
+      # change is the member's change since its baseline; open_findings, the record's findings on the member. What
+      # the agent judges is under context, the question last, as in a full audit's request (D60).
+      #: (request_id: String, principle_id: String, change: MemberChangeSinceBaseline,
+      #|  open_findings: Hash[String, Array[String]]) -> Hash[String, untyped]
+      def request(request_id:, principle_id:, change:, open_findings:)
+        { "status" => "agent_judgement_required", "request_id" => request_id, "phase" => "acknowledgement",
+          "context" => { "principle_id" => principle_id, **change.to_h, **open_findings,
+                         "question" => Prompts.text("acknowledge-a-change/say-whether-the-change-keeps-the-meaning") },
+          "response_template" => { "request_id" => request_id,
+                                   "basis" => { "base_commit" => change.base_commit, "member_id" => change.member_id },
+                                   "meaning_kept" => true, "reason" => "", "old_line" => "", "new_line" => "" },
+          "answer_with" => @invocation.submit_answer(request_id) }
+      end
+
+      # The acknowledgement was accepted and file holds it.
+      #: (principle_id: String, member_id: String, file: String) -> Hash[String, untyped]
+      def acknowledged(principle_id:, member_id:, file:)
+        { "status" => "acknowledged", "principle_id" => principle_id, "member_id" => member_id,
+          "files_to_commit" => [file],
+          "next_action" => "Commit #{file}. #{member_id} reads as judged until it is edited again.\n" \
+                           "After committing, this no longer lists it: " \
+                           "#{@invocation.in_project("list-member-problems", principle_id, usage: "--short")}" }
+      end
+    end
+  end
+end

data/lib/principles/views/activation_in_hand.rb

@@ -0,0 +1,47 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Principles
+  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
+  module Views
+    # How this tool says when a principle's work is in hand, from the activation its map stores (D38): the phrase
+    # change-activation's question carries, and that later results will share.
+    class ActivationInHand
+      # How the question words each value of Models::Activation#full_audit_lists.
+      LISTED = {
+        "session_start_members" => "The next full audit lists each member that loads at every session start " \
+                                   "anyway, for you to weigh against it.",
+        "none" => "Its work is in hand in every session, so a full audit lists no member to weigh against it.",
+        "not_built" => "A full audit's listing of members that load outside it is not built yet."
+      }.freeze #: Hash[String, String]
+
+      #: (Hash[String, untyped]) -> void
+      def initialize(activation)
+        @activation = activation
+        freeze
+      end
+
+      # What change-activation's question says it recorded for principle_id, and, from lists, what the next full audit
+      # lists against it.
+      #: (String, String) -> String
+      def recorded(principle_id, lists)
+        "Recorded that #{principle_id}'s work is in hand #{phrase}. #{LISTED.fetch(lists)}"
+      end
+
+      # What change-activation's question says when the map already held this activation, so nothing changed.
+      #: (String) -> String
+      def unchanged(principle_id)
+        "#{principle_id}'s work was already in hand #{phrase}; nothing was written."
+      end
+
+      #: () -> String
+      def phrase
+        case @activation.fetch("when")
+        when "files" then "when files matching #{@activation.fetch("files").join(", ")} are read or changed"
+        when "invoked" then "when its work is invoked, as a skill or a runbook is"
+        else "for all work, in every session"
+        end
+      end
+    end
+  end
+end

data/lib/principles/views/assessment_request.rb

@@ -0,0 +1,131 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "check_result_template"
+require_relative "prompts"
+require_relative "request_parts"
+
+module Principles
+  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
+  module Views
+    # One assessment request start-audit prints: the principle and its members as the agent assesses them, and
+    # the answer's template. Each member is an entry of id, role, first_line, last_line, the evidence that locates
+    # it and, for a member with a check, the check whose result the template asks for (D30). Its hash travels in
+    # the request id, not here.
+    class AssessmentRequest
+      # The question every member's assessment answers, which a completed record digests with the description (D49).
+      #: () -> String
+      def self.question = Prompts.text("assess-every-member/assess-each-member-and-the-set")
+
+      # basis is what the answer hands back unchanged: the base commit and the last completed record's revision.
+      # parts are what the agent reads beside the members before the question, such as the files outside the map
+      # that differ from the base commit (#409), each with any slots it adds to the template (D60).
+      #: (principle_id: String, description: untyped, members: Array[Hash[String, untyped]],
+      #|  basis: Hash[String, untyped], ?parts: Array[RequestPart]) -> void
+      def initialize(principle_id:, description:, members:, basis:, parts: [])
+        @principle_id = principle_id
+        @description = description
+        @members = members
+        @basis = basis
+        @parts = RequestParts.new(parts) #: RequestParts
+        freeze
+      end
+
+      # What the agent assesses, its other parts, the question and a guide to the answer's shapes.
+      #: () -> Hash[String, untyped]
+      def context
+        listed = { "principle_id" => @principle_id, "description" => @description,
+                   "members" => @members.map do |member|
+                     member.slice("id", "role", "first_line", "last_line", "check", "check_since_last_audit",
+                                  "check_hidden_characters", "acknowledged_since_last_audit", "carried_forward",
+                                  "judge_because", "moved_from", "read_the_change", "mapped_elsewhere")
+                   end }
+        @parts.shown_after(listed).merge(asked)
+      end
+
+      # The answer to fill in: one assessment per member, and the set's.
+      #: () -> Hash[String, untyped]
+      def template
+        assessed = {
+          "basis" => @basis,
+          "member_assessments" => @members.map { |member| member_assessment_template(member) },
+          "collective_assessment" => "How the members reinforce the principle, and any contradiction or " \
+                                     "missing connection.",
+          "recent_decision" => { "unavailable_reason" => "Or use the assessed shape in answer_guide.recent_decision." },
+          "findings" => []
+        }
+        @parts.slotted_after(assessed)
+      end
+
+      private
+
+      # What the request asks of what the agent read: the question, why members are judged afresh, how to treat the
+      # members it carries forward and the roles other principles give their lines, and the guide to the answer's
+      # shapes.
+      #: () -> Hash[String, untyped]
+      def asked
+        { "question" => AssessmentRequest.question }.merge(judge_because_instruction, carried_forward_instruction,
+                                                           mapped_elsewhere_instruction)
+                                                    .merge("answer_guide" => answer_guide)
+      end
+
+      # Why each member with judge_because is judged afresh, explaining only the values the members carry, so the
+      # agent meets each value's meaning where it meets the value (D61); nothing when no member gives one.
+      #: () -> Hash[String, untyped]
+      def judge_because_instruction
+        reasons = @members.filter_map { |member| member["judge_because"] }.uniq
+        return {} if reasons.empty?
+
+        intro, *meanings = Prompts.text("assess-every-member/why-each-member-is-judged-again").split("\n\n")
+        shown = meanings.select { |meaning| reasons.any? { |reason| meaning.start_with?("`#{reason}`:") } }
+        { "judge_because_instruction" => [intro, *shown].join("\n\n") }
+      end
+
+      # How to judge the roles other principles give a member's lines, printed only when a member shares lines with
+      # another principle's (#719, D61), and, when an entry names findings open on its member, where to read how to
+      # treat them, which prints apart, before the question (#808).
+      #: () -> Hash[String, untyped]
+      def mapped_elsewhere_instruction
+        entries = @members.flat_map { |member| member["mapped_elsewhere"] || [] }
+        return {} if entries.empty?
+
+        roles, open_findings = Prompts.text("assess-every-member/check-roles-other-principles-give-these-lines")
+                                      .split("\n\n")
+        shown = entries.any? { |entry| entry["open_finding_ids"] } ? [roles, open_findings] : [roles]
+        { "mapped_elsewhere_instruction" => shown.join("\n\n") }
+      end
+
+      # The answer guide, showing the check result's shapes only when a member has a check, so an audit
+      # with no checks costs no more context than before (D30).
+      #: () -> Hash[String, untyped]
+      def answer_guide
+        guide = Prompts.data("assess-every-member/answer-guide")
+        @members.any? { |member| member["check"] } ? guide : guide.except("check_result")
+      end
+
+      # How to answer when the request carries some members' last assessments forward; nothing when it carries none.
+      #: () -> Hash[String, untyped]
+      def carried_forward_instruction
+        return {} unless @members.any? { |member| member["carried_forward"] }
+
+        { "carried_forward_instruction" => Prompts.text("assess-every-member/judge-the-set-with-carried-assessments") }
+      end
+
+      # A member's template entry: a fresh assessment to fill in, or, for a member whose last assessment is carried
+      # forward, the marker that keeps it (D49); either with its check's result when it has a check.
+      #: (Hash[String, untyped]) -> Hash[String, untyped]
+      def member_assessment_template(member)
+        assessed = if member["carried_forward"]
+                     { "member_id" => member.fetch("id"), "carried_forward" => true }
+                   else
+                     { "member_id" => member.fetch("id"), "assessment" => "Your assessment, including its context cost",
+                       "delivery" => "not_observed", "evidence" => member.fetch("evidence") }
+                   end
+        check = member["check"] or return assessed
+        template = CheckResultTemplate.new(check, member["check_since_last_audit"],
+                                           member.fetch("check_hidden_characters", []))
+        assessed.merge("check_result" => template.to_h)
+      end
+    end
+  end
+end

data/lib/principles/views/audit_changes.rb

@@ -0,0 +1,79 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "audit_commit"
+require_relative "landed_since_base"
+require_relative "principle_with_changed_members"
+require_relative "shell_word"
+
+module Principles
+  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
+  module Views
+    # What a completed audit changed in the project, as its result prints it: the files to commit, in git what
+    # landed since the base commit, as LandedSinceBase prints it, each other principle whose members its fixes changed
+    # (#410), each file the record cites that no longer exists (#861), and each member added to the map during the
+    # audit, which no assessment read, so the next full audit assesses it (T69).
+    class AuditChanges
+      #: (files_to_commit: Array[String], ?landed: LandedSinceBase?,
+      #|  ?other_changed: Array[PrincipleWithChangedMembers], ?cited_files_missing: Array[String],
+      #|  ?added: Array[String]) -> void
+      def initialize(files_to_commit:, landed: nil, other_changed: [], cited_files_missing: [], added: [])
+        @files_to_commit = files_to_commit
+        @added = added
+        @landed = landed
+        @other_changed = other_changed
+        @cited_files_missing = cited_files_missing
+        freeze
+      end
+
+      # The files to commit, and each other principle whose members the audit's fixes changed, as the next step
+      # names them.
+      #: Array[String]
+      attr_reader :files_to_commit
+      #: Array[PrincipleWithChangedMembers]
+      attr_reader :other_changed
+
+      # The fields as printed; the members added and the cited files missing, what landed since the base only in
+      # git, where it is given, and the other principles, each only when there are some.
+      #: () -> Hash[String, untyped]
+      def to_h
+        printed = { "files_to_commit" => @files_to_commit } #: Hash[String, untyped]
+        printed = printed.merge("members_added_awaiting_assessment" => @added) unless @added.empty?
+        printed = printed.merge("cited_files_missing" => @cited_files_missing) unless @cited_files_missing.empty?
+        printed = printed.merge(@landed.to_h) if @landed
+        others = @other_changed.map(&:to_h)
+        others.empty? ? printed : printed.merge("other_principles_with_changed_members" => others)
+      end
+
+      # Refuses, staging nothing, while a merge is unfinished, whose commit would otherwise take in these files
+      # (758f12b, #811), saying why on stderr, the one place the stop is explained (#828). It fails with false, not
+      # exit, so a shell running it outside the printed subshell survives; the braces keep a failed cd from reading
+      # as a merge. The message is in single quotes, so it holds no apostrophe.
+      NO_MERGE_UNFINISHED = '{ test ! -e "$(git rev-parse --git-path MERGE_HEAD)" || ' \
+                            "{ echo 'principles: a merge is unfinished; finish or abort it, then run this again' " \
+                            ">&2; false; }; }" #: String
+
+      # In git, the command that commits the files to commit and nothing else staged, with subject, run from
+      # project, where those paths are relative. Each path is quoted for the shell and read by git as written, since
+      # project files anyone may have written name them (#227, #811). nil outside git, where it could not run.
+      #: (String, String) -> String?
+      def commit_with(subject, project)
+        return unless @landed
+
+        files = @files_to_commit.map { |file| ShellWord.new(file) }.join(" ")
+        "(cd #{ShellWord.new(project)} && #{NO_MERGE_UNFINISHED} && git --literal-pathspecs add -- #{files} && " \
+          "git --literal-pathspecs commit -m #{ShellWord.new(subject)} -- #{files})"
+      end
+
+      # How the result says to commit these files with subject, run from project: in git with commit_with's
+      # command, outside git by hand.
+      #: (String, String) -> (AuditCommit | AuditCommit::ByHand)
+      def commit(subject, project)
+        command = commit_with(subject, project)
+        return AuditCommit::ByHand.new(@files_to_commit) unless command
+
+        AuditCommit.new(files_to_commit: @files_to_commit, subject:, command:)
+      end
+    end
+  end
+end