principles 0.0.1

data/lib/principles/views/lines_shared_with_member.rb

@@ -0,0 +1,111 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../prose_list"
+
+module Principles
+  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
+  module Views
+    # What add-member's result says of the members sharing a line with the member it added, show-principle
+    # beside each member it shows (#541), and a full audit's request beside each member, of other maps only (#719):
+    # those in its map (overlaps), those of them spanning exactly its lines
+    # (same_lines_as, #442), and those in other maps, with their roles there and same_lines when they span exactly
+    # its lines, spans_these_lines when their lines include all of its and within_these_lines when its lines
+    # include theirs (mapped_elsewhere, #383, #718). Each field is printed only when there are some; add-member
+    # also prints the sentences that say what it means for the agent.
+    class LinesSharedWithMember
+      # Why the agent checks the text where the lines meet, unless each member holding another's lines is a whole
+      # file, which holds every line's text (#756).
+      TEXT_CHECK = "Lines are not text: where two share a first or last line, a passage can start or end partway " \
+                   "through it, so check the text there before deciding which edit reaches which member. " #: String
+
+      # text_check says whether a member holding another's lines is not a whole file, so the text needs checking.
+      #: (?overlaps: Array[String], ?same_lines_as: Array[String], ?mapped_elsewhere: Array[Hash[String, untyped]],
+      #|  ?text_check: bool) -> void
+      def initialize(overlaps: [], same_lines_as: [], mapped_elsewhere: [], text_check: false)
+        @overlaps = overlaps
+        @same_lines_as = same_lines_as
+        @mapped_elsewhere = mapped_elsewhere
+        @text_check = text_check
+        freeze
+      end
+
+      # The fields to merge into added, each only when there are some.
+      #: () -> Hash[String, untyped]
+      def to_h
+        { "overlaps" => @overlaps, "same_lines_as" => @same_lines_as, "mapped_elsewhere" => @mapped_elsewhere }
+          .reject { |_field, shared| shared.empty? }
+      end
+
+      # The sentences the question carries for them, or none.
+      #: () -> String
+      def note
+        "#{overlap_note}#{elsewhere_note}#{same_lines_note}"
+      end
+
+      private
+
+      #: () -> String
+      def overlap_note
+        return "" if @overlaps.empty?
+
+        "It shares lines with #{@overlaps.join(", ")}, so one edit there will show as a change to each. "
+      end
+
+      #: () -> String
+      def elsewhere_note
+        return "" if @mapped_elsewhere.empty?
+
+        "Members of other principles share lines with this one (mapped_elsewhere), so an edit to the lines they " \
+          "share changes each. #{spans_note}Check that this member's role fits beside the roles they give it there. "
+      end
+
+      # Which of them span all of this member's lines and which lie within them, so the agent can work out which
+      # member an edit reaches (#718). Lines are not text, so the agent checks where they share a first or last line.
+      #: () -> String
+      def spans_note
+        spans = @mapped_elsewhere.filter_map do |each|
+          if each["spans_these_lines"] then spanning(each)
+          elsif each["within_these_lines"] then within(each)
+          end
+        end
+        "#{spans.join}#{TEXT_CHECK if @text_check && spans.any?}"
+      end
+
+      # One that spans all of this member's lines: an edit to this member reaches it, and one outside them only it.
+      #: (Hash[String, untyped]) -> String
+      def spanning(each)
+        id = "`#{each.fetch("member_id")}`"
+        "#{id} in #{each.fetch("principle_id")} spans all of this member's lines, so every edit to this member's " \
+          "text is an edit to it too, and an edit outside the shared lines reaches only #{id}. "
+      end
+
+      # One within this member's lines: an edit to it reaches this member, and one outside them only this member.
+      #: (Hash[String, untyped]) -> String
+      def within(each)
+        "`#{each.fetch("member_id")}` in #{each.fetch("principle_id")} lies within this member's lines, so every " \
+          "edit to its text is an edit to this member's too, and an edit outside the shared lines reaches only " \
+          "this member. "
+      end
+
+      # Equal lines are not equal text, as a passage can end within its last line, so the agent decides.
+      #: () -> String
+      def same_lines_note
+        return "" if @same_lines_as.empty? && @mapped_elsewhere.none? { |each| each["same_lines"] }
+
+        named = same_lines_named
+        "#{ProseList.new(named)} #{named.length > 1 ? "span" : "spans"} exactly these lines " \
+          "(same_lines), under another id. If they are meant to be one member, decide which to keep; if both are " \
+          "meant, say why in this member's role. "
+      end
+
+      # Each member spanning exactly these lines, by id, with its principle when it is in another (#445).
+      #: () -> Array[String]
+      def same_lines_named
+        elsewhere = @mapped_elsewhere.select { |each| each["same_lines"] }
+        @same_lines_as.map { |id| "`#{id}`" } +
+          elsewhere.map { |each| "`#{each.fetch("member_id")}` in #{each.fetch("principle_id")}" }
+      end
+    end
+  end
+end

data/lib/principles/views/loads_to_check_result.rb

@@ -0,0 +1,45 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "invocation"
+require_relative "prompts"
+require_relative "request_part"
+
+module Principles
+  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
+  module Views
+    # How a full audit's request shows the members to check against the principle's activation (#355 slice 3).
+    class LoadsToCheckResult
+      # listed is the members to check, nil when there are none, and id the principle they belong to.
+      #: (Invocation, Hash[String, untyped]?, String) -> void
+      def initialize(invocation, listed, id)
+        @invocation = invocation
+        @listed = listed
+        @id = id
+        freeze
+      end
+
+      # The request's part that lists the members to check against the activation, how to decide them, and a
+      # decision to fill in for each; nil when there are none to list.
+      #: () -> RequestPart?
+      def part
+        listed = @listed or return
+
+        decisions = listed.fetch("rows").map { |row| { "member_id" => row.fetch("member_id"), "decision" => nil } }
+        RequestPart.new(shown: { "loads_to_check_against_activation" => listed,
+                                 "loads_to_check_instruction" => instruction },
+                        slots: { "loading_decisions" => decisions })
+      end
+
+      private
+
+      # How to decide each listed member, naming the activation change for a principle whose work is in hand in
+      # every session (#509).
+      #: () -> String
+      def instruction
+        always = @invocation.in_project("change-activation", @id, options: ["--always"])
+        Prompts.text("assess-every-member/decide-each-member-loading", always: always)
+      end
+    end
+  end
+end

data/lib/principles/views/map_result.rb

@@ -0,0 +1,169 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "invocation"
+require_relative "printed_principle"
+require_relative "lines_shared_with_member"
+require_relative "activation_in_hand"
+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 JSON results of the commands that write a principle's map, with commands for the invocation running now.
+    # PrincipleReadResult prints the reads.
+    class MapResult
+      # The placeholders each printed command leaves for the agent to fill.
+      ADD_MEMBER_USAGE = "PATH [--section \"Exact heading text\"] [--starting-at \"text that occurs once\" " \
+                         "[--ending-at \"text that closes the passage\"]] [--query '$.description'] " \
+                         "--role \"The part it plays\""
+
+      CREATED = "Which files or Markdown sections reinforce this principle? Add each one with the part it plays, " \
+                "for example: states the principle, lists the checks, records settled terms, reminds on a timer, " \
+                "fails the build. When a member is one item inside a larger file or section, narrow it with " \
+                "--starting-at, and --ending-at for more than one line. Add one member per command. Leave out the " \
+                "material the members govern."
+
+      # in_git says whether the project is in git, where a committed map is each member's baseline until its first
+      # full audit (#623).
+      #: (Invocation, in_git: bool) -> void
+      def initialize(invocation, in_git:)
+        @invocation = invocation
+        @in_git = in_git
+        freeze
+      end
+
+      #: (PrintedPrinciple) -> Hash[String, untyped]
+      def created(principle)
+        question(principle, CREATED, add_member_command(principle.id))
+      end
+
+      #: (PrintedPrinciple) -> Hash[String, untyped]
+      def description_changed(principle)
+        question(principle, "Changed the description of #{principle.id}.", start_audit(principle.id))
+      end
+
+      # What this tool recorded of when the work is in hand, and what a full audit lists against it, as
+      # Models::Activation#full_audit_lists names it (#355, #523).
+      #: (PrintedPrinciple, lists: String) -> Hash[String, untyped]
+      def activation_changed(principle, lists:)
+        question(principle, ActivationInHand.new(principle.activation || {}).recorded(principle.id, lists),
+                 start_audit(principle.id), shown: { "activation" => principle.activation })
+      end
+
+      # change-activation when the map already held that activation, so it wrote nothing (#474).
+      #: (PrintedPrinciple) -> Hash[String, untyped]
+      def activation_unchanged(principle)
+        question(principle, ActivationInHand.new(principle.activation || {}).unchanged(principle.id),
+                 @invocation.in_project("show-principle", principle.id),
+                 shown: { "activation" => principle.activation })
+      end
+
+      # shared says which members share a line with the new one; added lists them only when there are some, as it
+      # carries a check only when one is named.
+      #: (PrintedPrinciple, added: Hash[String, untyped], ?shared: LinesSharedWithMember) -> Hash[String, untyped]
+      def member_added(principle, added:, shared: LinesSharedWithMember.new)
+        added = added.merge(shared.to_h)
+        shown = @invocation.in_project("show-principle", principle.id)
+        question(principle, "#{span(added)}#{shared.note}Add the next member the same way. Commit " \
+                            "#{principle.file} as it changes, so the project's history shows each change; in git, " \
+                            "start-audit refuses a map that is not committed.\n" \
+                            "To see the map so far: #{shown}\n#{start_when_mapped(principle.id)}",
+                 add_member_command(principle.id), shown: { "member_count" => principle.members.length })
+          .merge("added" => added)
+      end
+
+      # add-member's report of the map it started, with the description and activation it wrote, which the agent
+      # never typed (#929).
+      #: (PrintedPrinciple) -> Hash[String, untyped]
+      def map_created(principle)
+        { "map_created" => { "description" => principle.description, "activation" => principle.activation } }
+      end
+
+      # move-member: the member's old id, and its new id with the lines it now spans.
+      #: (PrintedPrinciple, from: String, moved: Hash[String, untyped]) -> Hash[String, untyped]
+      def member_moved(principle, from:, moved:)
+        id = moved.fetch("id")
+        question(principle, "#{id} now spans lines #{moved.fetch("first_line")} to #{moved.fetch("last_line")}" \
+                            "#{" (moved from #{from})" unless from == id}; if that is not the passage you meant, " \
+                            "move it again. Check the other members, then start the audit.", start_audit(principle.id))
+          .merge("moved" => moved)
+      end
+
+      # change-member-check: the stored command is the member's check in the map printed beside this, so the
+      # agent can see it byte for byte; the question names that field rather than quoting project text (#227).
+      # hidden names each character in the check that prints escaped or not at all (#260).
+      #: (PrintedPrinciple, member: String, hidden: Array[String]) -> Hash[String, untyped]
+      def check_changed(principle, member:, hidden:)
+        done = "#{member} is now enforced by the check named in its map entry. The next audit marks it new or " \
+               "changed and asks for a review before it runs; nothing runs it automatically: " \
+               "you run it when an audit asks for its result."
+        return member_replaced(principle, member: member, done: done) if hidden.empty?
+
+        member_replaced(principle, member: member,
+                                   done: "#{done} The check holds characters that print escaped or not at all, " \
+                                         "which check_hidden_characters names; make sure each is meant.")
+          .merge("check_hidden_characters" => hidden)
+      end
+
+      # change-member-role, change-member-check and remove-member-check: done says what changed. This tool cannot
+      # tell in git whether a full audit's correction is open, so the next step names both cases (D40, #461), and
+      # the other case by what the agent holds: a correction request (second alpha user on 8e5b3f9).
+      #: (PrintedPrinciple, member: String, done: String) -> Hash[String, untyped]
+      def member_replaced(principle, member:, done:)
+        question(principle, "#{done} Check the other members, then start the audit.\nIf you hold a correction " \
+                            "request from submit-answer (phase correction), list #{member} in the " \
+                            "changed_map_entries of the fixed disposition this change fixes, and submit it instead: " \
+                            "#{@invocation.submit_answer("REQUEST")}",
+                 start_audit(principle.id))
+      end
+
+      #: (PrintedPrinciple, removed: String) -> Hash[String, untyped]
+      def member_removed(principle, removed:)
+        question(principle, "Removed #{removed}. Add or remove members until the map is right.\n" \
+                            "#{start_when_mapped(principle.id)}",
+                 add_member_command(principle.id))
+      end
+
+      private
+
+      # The lines a member spans, said so that a passage cut short shows; it ends with a space.
+      #: (Hash[String, untyped]) -> String
+      def span(member)
+        "#{member.fetch("id")} spans lines #{member.fetch("first_line")} to #{member.fetch("last_line")}; " \
+          "if that is not the passage you meant, move it with move-member. "
+      end
+
+      # shown is what the result prints of the map: the whole map unless the caller names less, as add-member
+      # does (#400).
+      #: (PrintedPrinciple, String, String, ?shown: Hash[String, untyped]) -> Hash[String, untyped]
+      def question(principle, text, answer_with, shown: { "map" => principle.map })
+        { "status" => "question", "principle_id" => principle.id, "map_file" => principle.file, **shown,
+          "question" => text, "answer_with" => answer_with }
+      end
+
+      #: (String) -> String
+      def start_audit(id)
+        @invocation.in_project("start-audit", id)
+      end
+
+      # The step after adding members, as the question's last line, since answer_with is the next add-member.
+      #: (String) -> String
+      def start_when_mapped(id)
+        if @in_git
+          return "When the map lists every member, commit it: list-member-problems then reports any change to a " \
+                 "member since that commit. Only a full audit judges whether they reinforce the principle.\n" \
+                 "To start it when you choose: #{start_audit(id)}"
+        end
+
+        "When the map lists every member, start the audit. It judges whether they reinforce the principle, and " \
+          "gives each member the baseline list-member-problems compares it with.\nTo start it: #{start_audit(id)}"
+      end
+
+      #: (String) -> String
+      def add_member_command(id)
+        @invocation.in_project("add-member", id, usage: ADD_MEMBER_USAGE)
+      end
+    end
+  end
+end

data/lib/principles/views/member_change_since_baseline.rb

@@ -0,0 +1,58 @@
+# typed: strict
+# frozen_string_literal: true
+
+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
+    # One member's change since its baseline, as a one-member audit's request shows it: the member's id, role and
+    # evidence, the commit its baseline text is at, the commit the audit is based on, the member's own lines at
+    # each (#379), and the command that shows its file's change between them, following a move (D33, #551).
+    class MemberChangeSinceBaseline
+      # member holds the member's id, role and evidence; commits holds "base", HEAD, and "baseline", the commit
+      # the member's baseline text is at, and "audit_base" when the baseline is later than the audit's base;
+      # member_lines holds its own lines at each, or their counts when too long; paths holds the paths the change
+      # spans, its path at the baseline first.
+      #: (member: Hash[String, untyped], commits: Hash[String, String], member_lines: Hash[String, untyped],
+      #|  paths: Array[String]) -> void
+      def initialize(member:, commits:, member_lines:, paths:)
+        @member = member
+        @commits = commits
+        @member_lines = member_lines
+        @paths = paths
+        freeze
+      end
+
+      #: () -> String
+      def member_id
+        @member.fetch("id")
+      end
+
+      #: () -> String
+      def base_commit
+        @commits.fetch("base")
+      end
+
+      # The fields as the request prints them. Lines left out for their length point at read_the_change instead,
+      # so the request is never silently partial (D38).
+      #: () -> Hash[String, untyped]
+      def to_h
+        read = read_the_change
+        lines = @member_lines.key?("omitted") ? @member_lines.merge("read_instead" => read) : @member_lines
+        { "member" => @member, "baseline_commit" => @commits.fetch("baseline"), "base_commit" => base_commit,
+          **@commits.slice("audit_base").transform_keys { "audit_base_commit" },
+          "member_lines" => lines, "read_the_change" => read }
+      end
+
+      private
+
+      # Each word quoted for the shell, and every path read by git as written, not as a pattern (#558).
+      #: () -> String
+      def read_the_change
+        words = [@commits.fetch("baseline"), base_commit, "--", *@paths].map { |word| ShellWord.new(word).to_s }
+        "git --literal-pathspecs diff -M #{words.join(" ")}"
+      end
+    end
+  end
+end

data/lib/principles/views/member_repairs.rb

@@ -0,0 +1,82 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "invocation"
+
+module Principles
+  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
+  module Views
+    # The commands that repair a member this tool cannot find: move it, or remove it. A member whose file is
+    # gone is moved to the path the agent finds, keeping its own section, passage or query, so a rename keeps
+    # its audit (#268). A member whose place in its file is gone is moved within it, or to another file its text
+    # moved into (#378); a passage keeps its anchors, so a move cannot silently widen it to its whole new
+    # section (#251). Which fits is the agent's to judge.
+    class MemberRepairs
+      # The flag that names each locator field in a printed command.
+      FLAGS = { "section" => "--section", "starting_at" => "--starting-at", "ending_at" => "--ending-at",
+                "query" => "--query" }.freeze #: Hash[String, String]
+
+      #: (Invocation) -> void
+      def initialize(invocation)
+        @invocation = invocation
+        freeze
+      end
+
+      # The repairs for member, a printed member with its "id", its locator fields and the code of the refusal
+      # that says why it cannot be found, as "code" or show-principle's "error", of principle id. Each is
+      # copyable as it is: move-member, with NEW_PATH, HEADING or QUERY to fill in, then, for a section or
+      # passage lost from a file that is still there, the same move into another file, then remove-member.
+      #: (String, Hash[String, untyped]) -> Array[String]
+      def commands(id, member)
+        member_id = member.fetch("id")
+        [move(id, member_id, member), *move_elsewhere(id, member_id, member),
+         @invocation.in_project("remove-member", id, member_id)]
+      end
+
+      # member, as show-principle prints it, with its repairs as repair_with when broken, which the controller says
+      # of a member an audit would refuse (#272).
+      #: (String, Hash[String, untyped], broken: bool) -> Hash[String, untyped]
+      def beside(id, member, broken:)
+        return member unless broken
+
+        member.merge("repair_with" => commands(id, member))
+      end
+
+      private
+
+      #: (String, String, Hash[String, untyped]) -> String
+      def move(id, member_id, member)
+        if file_unreadable?(member)
+          kept = flags(member, FLAGS.keys)
+          return @invocation.in_project("move-member", id, member_id, options: kept, usage: "--path NEW_PATH")
+        end
+        return @invocation.in_project("move-member", id, member_id, usage: "--query QUERY") if member["query"]
+
+        @invocation.in_project("move-member", id, member_id, options: flags(member, %w[starting_at ending_at]),
+                                                             usage: "--section HEADING")
+      end
+
+      # A section or passage lost from a file that is still there may have moved into another file (#378).
+      #: (String, String, Hash[String, untyped]) -> Array[String]
+      def move_elsewhere(id, member_id, member)
+        return [] if member["query"] || file_unreadable?(member)
+
+        anchors = flags(member, %w[starting_at ending_at])
+        [@invocation.in_project("move-member", id, member_id, options: anchors,
+                                                              usage: "--path NEW_PATH --section HEADING")]
+      end
+
+      # Whether member's file cannot be read, by the refusal it carries.
+      #: (Hash[String, untyped]) -> bool
+      def file_unreadable?(member)
+        (member["code"] || member.dig("error", "code")) == "unreadable_file"
+      end
+
+      # The flags, with their values, of the locator fields named in keys that member has.
+      #: (Hash[String, untyped], Array[String]) -> Array[String]
+      def flags(member, keys)
+        keys.select { |key| member[key] }.flat_map { |key| [FLAGS.fetch(key), member.fetch(key)] }
+      end
+    end
+  end
+end

data/lib/principles/views/members_a_commit_changed.rb

@@ -0,0 +1,66 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "json"
+require_relative "invocation"
+require_relative "problem_lines"
+require_relative "prompts"
+require_relative "visible_text"
+
+module Principles
+  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
+  module Views
+    # list-member-problems --commits-after COMMIT --hook-event EVENT: the whole JSON the plugin's after-commit hook
+    # prints for Claude Code, which puts its additionalContext beside the Bash call's result (D73), or nothing at all.
+    # Claude Code asks for that text to state facts, not to give orders, so it says what the commits changed and
+    # which command shows more.
+    class MembersACommitChanged
+      NOTHING = Lines.new(stdout: "", stderr: "", status: 0).freeze #: Lines
+
+      #: (Invocation) -> void
+      def initialize(invocation)
+        @invocation = invocation
+        freeze
+      end
+
+      # changed is each member the commits changed, as list-member-problems lists it; others is how many other
+      # changed members it still lists.
+      #: (String, Array[Hash[String, untyped]], others: Integer) -> Lines
+      def changed(event, changed, others:)
+        rows = changed.map { |member| ProblemLines.new(@invocation).row(member) }
+        reported(event, [Prompts.text("report-after-a-commit/the-commits-changed-these-members"), *rows,
+                         *still_listed(others), Prompts.text("report-after-a-commit/this-command-shows-each-one"),
+                         command])
+      end
+
+      # A refusal with code, which the commits could have caused.
+      #: (String, String) -> Lines
+      def refused(event, code)
+        reported(event, [Prompts.text("report-after-a-commit/it-refused-after-the-commits-touched-the-maps",
+                                      code: VisibleText.new(code).to_s), command])
+      end
+
+      private
+
+      # The line saying how many other changed members list-member-problems still lists, or none when it lists none.
+      #: (Integer) -> Array[String]
+      def still_listed(others)
+        return [] if others.zero?
+
+        [Prompts.text("report-after-a-commit/others-are-still-listed",
+                      count: others.to_s, members: others == 1 ? "member is" : "members are")]
+      end
+
+      #: () -> String
+      def command = @invocation.in_project("list-member-problems")
+
+      # The hook's JSON. Each field from a project file or commit is written through VisibleText already, so an
+      # invisible character reaches the model as \uXXXX, not hidden in the text it reads (#227).
+      #: (String, Array[String]) -> Lines
+      def reported(event, lines)
+        output = { "hookSpecificOutput" => { "hookEventName" => event, "additionalContext" => lines.join("\n") } }
+        Lines.new(stdout: "#{JSON.generate(output)}\n", stderr: "", status: 0)
+      end
+    end
+  end
+end

data/lib/principles/views/members_with_no_baseline.rb

@@ -0,0 +1,56 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../prose_list"
+
+module Principles
+  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
+  module Views
+    # One principle's members with no baseline, as list-member-problems' next_action says what gives them one:
+    # outside git a completed audit, and in git committing the files that hold them (#564).
+    class MembersWithNoBaseline
+      # because is "outside_git" or "not_committed"; audit is the start-audit command to run outside git, and
+      # files the map and member files to commit in git.
+      #: (id: String, count: Integer, because: String, audit: String, files: Array[String]) -> void
+      def initialize(id:, count:, because:, audit:, files:)
+        @id = id
+        @count = count
+        @because = because
+        @audit = audit
+        @files = files
+        freeze
+      end
+
+      #: () -> String
+      def to_s
+        "#{@count} member#{"s" unless one?} of #{@id} #{one? ? "has" : "have"} no baseline, so whether " \
+          "#{one? ? "it" : "they"} changed is not yet known.#{remedy}"
+      end
+
+      private
+
+      #: () -> bool
+      def one? = @count == 1
+
+      # What gives the members a baseline: a completed audit outside git, or in git committing the files that
+      # differ from HEAD, or an audit again when none does, since every file is committed already (#710 X3). The
+      # audit command starts a line of its own, after its purpose.
+      #: () -> String
+      def remedy
+        return " Committing #{ProseList.new(@files)} #{gives}." if @because == "not_committed" && !@files.empty?
+
+        "#{all_committed if @because == "not_committed"}\nA completed audit #{gives}: #{@audit}"
+      end
+
+      #: () -> String
+      def gives = "gives #{one? ? "it" : "each"} one"
+
+      #: () -> String
+      def all_committed
+        them, their, were = one? ? %w[it its was] : %w[them their were]
+        " Every file holding #{them} is already committed, but no commit held #{them} where #{their} map places " \
+          "#{them} when #{one? ? "it" : "they"} #{were} mapped."
+      end
+    end
+  end
+end

data/lib/principles/views/meta_principle_passage.rb

@@ -0,0 +1,23 @@
+# 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 passage setup proposes for every entry file, as the agent pastes it, its lines kept: one or two lines,
+    # worded for a reader who may not have principles installed (D68, D71).
+    class MetaPrinciplePassage
+      #: (heading: String) -> void
+      def initialize(heading:)
+        @heading = heading
+        freeze
+      end
+
+      # The passage, ending in a line break.
+      #: () -> String
+      def text = "#{Prompts.markdown("set-principles-up/entry-file-passage", heading: @heading)}\n"
+    end
+  end
+end