principles 0.0.1

data/lib/principles/views/meta_principle_result.rb

@@ -0,0 +1,170 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "invocation"
+require_relative "meta_principle_passage"
+require_relative "printed_principle"
+
+module Principles
+  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
+  module Views
+    # What show-meta-principle-passage prints: the map its printed add-member writes, the facts of the project's entry
+    # files, the one passage any of them would take, and the commands that map the passage once the agent has placed
+    # it with the user (D68, D71, D74).
+    class MetaPrincipleResult
+      # How the printed add-member commands map the passage: heading is the passage's heading, which they name as
+      # its member's section, beside role, the role they give that member; step_role is the role they give a
+      # passage the project has that carries one of the passage's steps, and place_role the one they give any other
+      # place that keeps the principles held, such as a timer or a settings line (D75).
+      class PassageMapping
+        #: String
+        attr_reader :heading, :role, :step_role, :place_role
+
+        #: (heading: String, role: String, step_role: String, place_role: String) -> void
+        def initialize(heading:, role:, step_role:, place_role:)
+          @heading = heading
+          @role = role
+          @step_role = step_role
+          @place_role = place_role
+          freeze
+        end
+      end
+
+      # mapping is how the printed commands map the passage; in_git says whether a commit can be the member's
+      # baseline.
+      #: (Invocation, PassageMapping, in_git: bool) -> void
+      def initialize(invocation, mapping, in_git:)
+        @invocation = invocation
+        @mapping = mapping
+        @in_git = in_git
+        freeze
+      end
+
+      # The passage, as the agent pastes it into an entry file, its lines kept.
+      #: () -> String
+      def passage = MetaPrinciplePassage.new(heading: @mapping.heading).text
+
+      # What the passage presumes of a teammate without principles, given its estimated size.
+      #: (Integer) -> String
+      def presumes(estimated_tokens)
+        Prompts.text("set-principles-up/what-the-passage-presumes", estimated_tokens: estimated_tokens.to_s)
+      end
+
+      # Where the passage can go, as the agent places it from: how this run was started and whether the plugin's
+      # session-start hook runs in this session, each root entry file's facts, and the passage's text with its size
+      # and what it presumes of a teammate without principles.
+      class Placement
+        #: (runs_from: String, session_start_hook_in_this_session: bool, entry_files: Array[Hash[String, untyped]],
+        #|  passage: Hash[String, untyped]) -> void
+        def initialize(runs_from:, session_start_hook_in_this_session:, entry_files:, passage:)
+          @fields = { "runs_from" => runs_from,
+                      "session_start_hook_in_this_session" => session_start_hook_in_this_session,
+                      "entry_files" => entry_files, "passage" => passage }.freeze #: Hash[String, untyped]
+          freeze
+        end
+
+        #: () -> Hash[String, untyped]
+        def to_h = @fields
+
+        # The passage's estimated size, which loads in every session that loads the entry file it goes in.
+        #: () -> Integer
+        def estimated_tokens = @fields.fetch("passage").fetch("estimated_tokens")
+      end
+
+      # The map as the project holds it: already_mapped says the map was there before this run, and
+      # members_in_entry_files names its members already in an entry file, by id and path; set_up says the map has a
+      # member, so the question asks which keeping step each lacks in place of asking to place the passage (D75).
+      class MapInProject
+        #: bool
+        attr_reader :set_up
+
+        #: (already_mapped: bool, members_in_entry_files: Array[Hash[String, String]], set_up: bool) -> void
+        def initialize(already_mapped:, members_in_entry_files:, set_up:)
+          @fields = { "already_mapped" => already_mapped,
+                      "members_in_entry_files" => members_in_entry_files }.freeze #: Hash[String, untyped]
+          @set_up = set_up
+          freeze
+        end
+
+        #: () -> Hash[String, untyped]
+        def to_h = @fields
+      end
+
+      # existing_principles lists the project's other principles as list-principles lists them.
+      #: (PrintedPrinciple, Placement, MapInProject, existing_principles: Array[Hash[String, untyped]])
+      #|  -> Hash[String, untyped]
+      def proposal(principle, placement, map_in_project, existing_principles:)
+        { "status" => "question", "principle_id" => principle.id, "map_file" => principle.file,
+          "map" => principle.map, **map_in_project.to_h, **placement.to_h,
+          "existing_principles" => existing_principles,
+          "question" => map_in_project.set_up ? steps_lacking(principle, placement) : question(principle.id),
+          "answer_with" => add_member(principle.id), "next_action" => next_action(principle.id, existing_principles) }
+      end
+
+      private
+
+      # What to agree with the user and place, with the command that maps a passage the project has in a step's
+      # place, and the one that maps the passage once it is placed.
+      #: (String) -> String
+      def question(id)
+        Prompts.text("set-principles-up/place-the-passage-with-the-user",
+                     command: add_member(id), existing: add_existing(id), any_place: add_place(id))
+      end
+
+      # Each mapped member's place and role, and which keeping step each lacks, with the passage as one way to add a
+      # missing step, at its size, and the command that maps another place.
+      #: (PrintedPrinciple, Placement) -> String
+      def steps_lacking(principle, placement)
+        members = principle.members.map { |member| "- #{member.fetch("id")}: #{member.fetch("role")}" }.join("\n")
+        Prompts.text("set-principles-up/name-the-step-each-member-lacks",
+                     members: members, command: add_member(principle.id), any_place: add_place(principle.id),
+                     estimated_tokens: placement.estimated_tokens.to_s)
+      end
+
+      # The add-member that maps any other place that keeps the principles held, by its path and a role naming the
+      # step it runs and what starts it.
+      #: (String) -> String
+      def add_place(id)
+        @invocation.in_project("add-member", id, usage: "PATH --role \"#{@mapping.place_role}\"")
+      end
+
+      # The add-member that maps a passage the project already has, which carries one of the passage's steps.
+      #: (String) -> String
+      def add_existing(id)
+        @invocation.in_project("add-member", id, usage: "PATH --section \"HEADING\" --role \"#{@mapping.step_role}\"")
+      end
+
+      #: (String) -> String
+      def add_member(id)
+        @invocation.in_project("add-member", id,
+                               usage: "ENTRY_FILE --section \"#{@mapping.heading}\" --role \"#{@mapping.role}\"")
+      end
+
+      # What follows placing the passage: committing it, which outside git is not the member's baseline, and the
+      # first full audit, which waits until the project has a principle of its own to keep held.
+      #: (String, Array[Hash[String, untyped]]) -> String
+      def next_action(id, existing_principles)
+        baseline = if @in_git
+                     "Then commit .principles/ and the entry file you changed."
+                   else
+                     "This principle's first full audit gives the passage's member its baseline, since this project " \
+                       "is not in git."
+                   end
+        [baseline, first_audit(id, existing_principles)].join(" ")
+      end
+
+      #: (String, Array[Hash[String, untyped]]) -> String
+      def first_audit(id, existing_principles)
+        if existing_principles.empty?
+          return "This principle's first full audit judges whether the keeping works, so leave it until one of the " \
+                 "project's own principles is mapped.\n" \
+                 "To find the first of them: #{@invocation.in_project("list-candidate-files")}"
+        end
+
+        "This principle's first full audit judges whether the keeping works for the principles under " \
+          "existing_principles.\n" \
+          "To start it: #{@invocation.in_project("start-audit", id)}"
+      end
+    end
+  end
+end

data/lib/principles/views/open_findings_elsewhere_result.rb

@@ -0,0 +1,32 @@
+# typed: strict
+# frozen_string_literal: true
+
+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 shows the findings other principles leave open on members sharing its members' lines: each
+    # once, which mapped_elsewhere names by id, with what to do with them (#772, D62).
+    class OpenFindingsElsewhereResult
+      # findings are each such finding, with its principle, id, problem and action.
+      #: (Array[Hash[String, untyped]]) -> void
+      def initialize(findings)
+        @findings = findings
+        freeze
+      end
+
+      # The assessment request's part that lists them and says what to do with them; nil when there are none. It adds
+      # nothing to the template: a finding here is decided in its own principle's audit.
+      #: () -> RequestPart?
+      def part
+        return if @findings.empty?
+
+        instruction = Prompts.text("assess-every-member/name-another-principles-open-finding-rather-than-raise-it")
+        RequestPart.new(shown: { "open_findings_elsewhere" => @findings,
+                                 "open_findings_elsewhere_instruction" => instruction }, slots: {})
+      end
+    end
+  end
+end

data/lib/principles/views/open_findings_line.rb

@@ -0,0 +1,125 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "invocation"
+require_relative "problem_lines"
+require_relative "visible_text"
+require_relative "prompts"
+
+module Principles
+  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
+  module Views
+    # list-open-findings --short: the one line a session-start hook puts into the agent's context while any
+    # finding is open, and nothing when none is (D47). It says how many wait, how long the oldest has, what that
+    # one waits on, and the command that lists them all, worded as something to act on.
+    class OpenFindingsLine
+      # A waits_on longer than this is cut, so the line stays one short line.
+      WAITS_ON_LIMIT = 80
+
+      #: (Invocation) -> void
+      def initialize(invocation)
+        @invocation = invocation
+        freeze
+      end
+
+      # waiting is nil when no finding is open, or the count of open findings with the oldest one's principle,
+      # finding_id, days_open and, when it says, waits_on. not_found is each open finding, by principle and
+      # finding_id, whose write-up can no longer be found where its recorded_at points (#694). source is the
+      # session's start: startup, clear or compact.
+      #: (Hash[String, untyped]?, ?Array[Hash[String, untyped]], ?source: String) -> Lines
+      def short(waiting, not_found = [], source: "startup")
+        Lines.new(stdout: waiting ? "#{line(waiting, not_found, source)}\n" : "", stderr: "", status: 0)
+      end
+
+      private
+
+      #: (Hash[String, untyped], Array[Hash[String, untyped]], String) -> String
+      def line(waiting, not_found, source)
+        count = waiting.fetch("count")
+        them, each = pronouns(count)
+        Prompts.text("start-a-session/act-on-the-open-findings",
+                     when: raise_when(source), returns: returns(source),
+                     findings: "#{counted(count)}#{waited(waiting)} (#{named(waiting)})",
+                     without_waits_on: without_waits_on(count, waiting.fetch("without_waits_on", 0)),
+                     write_ups: write_ups(not_found),
+                     them: them, each: each, command: @invocation.in_project("list-open-findings"))
+      end
+
+      # When to raise the findings: before the user's first task at startup, and at the next pause once the session is
+      # under way, after /clear or a compaction (#717).
+      #: (String) -> String
+      def raise_when(source)
+        return Prompts.text("start-a-session/raise-them-before-the-first-task") if source == "startup"
+
+        Prompts.text("start-a-session/raise-them-at-the-next-pause")
+      end
+
+      # When the line comes back: at each session start, and after each clear or compaction too (#741).
+      #: (String) -> String
+      def returns(source)
+        return Prompts.text("start-a-session/it-returns-at-each-session-start") if source == "startup"
+
+        Prompts.text("start-a-session/it-returns-after-each-clear-or-compaction-too")
+      end
+
+      # How many of several open findings record no waits_on, since the line names only the oldest's (#736). One
+      # open finding's own name already shows whether it does, so its line says nothing more.
+      #: (Integer, Integer) -> String
+      def without_waits_on(count, without)
+        return "" if count == 1 || without.zero?
+        return " All #{count} have no waits_on." if without == count
+
+        " #{without} #{without == 1 ? "has" : "have"} no waits_on."
+      end
+
+      # The words the line refers to the findings by, all of them and each one, singular or plural together.
+      #: (Integer) -> [String, String]
+      def pronouns(count)
+        count == 1 ? %w[it it] : %w[them each]
+      end
+
+      # The sentence naming the write-ups that can no longer be found, the first by its principle and id, or
+      # nothing when every pointer resolves, so the usual line is unchanged.
+      #: (Array[Hash[String, untyped]]) -> String
+      def write_ups(not_found)
+        first = not_found.first or return ""
+        named = "#{first.fetch("principle")} #{VisibleText.new(first.fetch("finding_id"))}"
+        return " The write-up of #{named} cannot be found where its recorded_at points, and the list says why." \
+          if not_found.one?
+
+        " The write-ups of #{not_found.length} findings, the first #{named}, cannot be found where their " \
+          "recorded_at points, and the list says why."
+      end
+
+      #: (Integer) -> String
+      def counted(count)
+        count == 1 ? "1 audit finding is still open, " : "#{count} audit findings are still open, the oldest "
+      end
+
+      #: (Hash[String, untyped]) -> String
+      def waited(waiting)
+        days = waiting.fetch("days_open")
+        return "for less than a day" if days < 1
+
+        "for #{days} #{days == 1 ? "day" : "days"}"
+      end
+
+      # The oldest finding's principle and id, and what it waits on, cut when long. The id and waits_on are free
+      # text, so each is cut by characters first and then escaped, which may run past the limit to show them (#227).
+      #: (Hash[String, untyped]) -> String
+      def named(waiting)
+        named = "#{waiting.fetch("principle")} #{VisibleText.new(waiting.fetch("finding_id"))}"
+        waits_on = waiting["waits_on"] or return named
+        waits_on = closed("#{waits_on[0, WAITS_ON_LIMIT - 3]}...") if waits_on.length > WAITS_ON_LIMIT
+        "#{named}, waits on: #{VisibleText.new(waits_on)}"
+      end
+
+      # A cut waits_on with a ")" for each "(" the cut left open, so the line's own parenthesis still reads as
+      # closing the finding's name (#685).
+      #: (String) -> String
+      def closed(cut)
+        cut + (")" * [cut.count("(") - cut.count(")"), 0].max)
+      end
+    end
+  end
+end

data/lib/principles/views/other_principles_unjudged_result.rb

@@ -0,0 +1,32 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "principle_with_changed_members"
+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 the meta-principle's full audit states, as a fact, each other principle with members no audit has judged
+    # as they are now, which a check on its passage once reported, beside the release since its last audit (D71).
+    class OtherPrinciplesUnjudgedResult
+      # principles holds each other principle with such members, by id with their states; empty when there are none.
+      #: (Array[PrincipleWithChangedMembers]) -> void
+      def initialize(principles)
+        @principles = principles
+        freeze
+      end
+
+      # The request's part listing them under principles, with why, how to weigh them, as the release part beside it
+      # gives its own.
+      #: () -> RequestPart
+      def part
+        why = Prompts.text("assess-every-member/judge-the-keeping-against-the-other-principles")
+        RequestPart.new(shown: { "other_principles_with_unjudged_changes" => { "principles" => @principles.map(&:to_h),
+                                                                               "why" => why } },
+                        slots: {})
+      end
+    end
+  end
+end

data/lib/principles/views/outside_the_map_result.rb

@@ -0,0 +1,31 @@
+# typed: strict
+# frozen_string_literal: true
+
+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 names the files outside the map that differ from the base commit, which a check and
+    # the answer's evidence read as they are now (#409, #426).
+    class OutsideTheMapResult
+      # outside names the files outside, as paths and any count not_named; nil when there are none or no base commit.
+      #: (Hash[String, untyped]?) -> void
+      def initialize(outside)
+        @outside = outside
+        freeze
+      end
+
+      # The request's part naming the files outside, with why they matter to the answer; nil when there are none,
+      # and then nothing is printed.
+      #: () -> RequestPart?
+      def part
+        outside = @outside or return
+
+        why = Prompts.text("assess-every-member/uncommitted-files-outside-the-map")
+        RequestPart.new(shown: { "uncommitted_files_outside_the_map" => outside.merge("why" => why) }, slots: {})
+      end
+    end
+  end
+end

data/lib/principles/views/package_since_last_audit_result.rb

@@ -0,0 +1,34 @@
+# 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 the meta-principle's full audit states the release of principles its last completed audit ran under beside
+    # the one running now, as facts for the agent to judge (D68).
+    class PackageSinceLastAuditResult
+      # at_last_audit is the version the last completed audit ran under, or nil when none recorded one; now is the
+      # version running now; passage_changed says whether the passage setup proposes changed since, or is nil with
+      # nothing to compare. invocation names the setup command the instruction prints.
+      #: (Invocation, at_last_audit: String?, now: String, passage_changed: bool?) -> void
+      def initialize(invocation, at_last_audit:, now:, passage_changed:)
+        @invocation = invocation
+        @since = { "version_at_last_audit" => at_last_audit, "version_now" => now,
+                   "passage_changed" => passage_changed }.freeze #: Hash[String, untyped]
+        freeze
+      end
+
+      # The request's part stating the release since the last audit, with what to do about a change.
+      #: () -> RequestPart
+      def part
+        why = Prompts.text("assess-every-member/judge-the-keeping-under-the-release-since-the-last-audit",
+                           setup: @invocation.in_project("show-meta-principle-passage"))
+        RequestPart.new(shown: { "package_since_last_audit" => @since.merge("why" => why) }, slots: {})
+      end
+    end
+  end
+end

data/lib/principles/views/principle_read_result.rb

@@ -0,0 +1,86 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "invocation"
+require_relative "printed_principle"
+require_relative "member_repairs"
+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 reading principles, show-principle and list-principles, with commands for the invocation
+    # running now. They change with what a read reports, such as freshness and repairs; MapResult prints the writes.
+    class PrincipleReadResult
+      #: (Invocation) -> void
+      def initialize(invocation)
+        @invocation = invocation
+        freeze
+      end
+
+      # show-principle: each member with where its text is now and its freshness, and each member in broken, the ids
+      # of those an audit would refuse, with its repair_with commands (#272).
+      # hook_settings_not_read names each project settings file whose hooks this tool could not read (#491).
+      # loaded_files lists each file the members load once, with the total of those loading at session start (#483).
+      #: (PrintedPrinciple, broken: Array[String], ?hook_settings_not_read: Array[Hash[String, String]],
+      #|  ?loaded_files: Hash[String, untyped]) -> Hash[String, untyped]
+      def shown(principle, broken:, hook_settings_not_read: [], loaded_files: {})
+        unread = hook_settings_not_read.empty? ? {} : { "hook_settings_not_read" => hook_settings_not_read }
+        { "id" => principle.id, "map_file" => principle.file, **principle.declared,
+          "members" => principle.members.map { |member| repaired(principle.id, member, broken) },
+          **loaded_files, **unread, "next_action" => shown_next_action(principle, broken) }
+      end
+
+      # list-principles: each entry is { "id", "description", "members_by_freshness" }. Until principles is set_up,
+      # its next_action puts setting it up first.
+      #: (Array[Hash[String, untyped]], set_up: bool) -> Hash[String, untyped]
+      def listing(entries, set_up:)
+        next_action = if entries.empty?
+                        "To map one, start with: #{@invocation.in_project("list-candidate-files")}"
+                      else
+                        "To see a principle's members: #{@invocation.in_project("show-principle", usage: "ID")}\n" \
+                          "To audit it: #{@invocation.in_project("start-audit", usage: "ID")}"
+                      end
+        first = set_up ? [] : [set_up_first]
+        { "principles" => entries, "next_action" => [*first, next_action].join("\n") }
+      end
+
+      # list-principles' note on the meta-principle's map, kept in file, when it has no members, with the two ways on
+      # (#931).
+      #: (String) -> Hash[String, String]
+      def no_members(file)
+        setup = @invocation.in_project("show-meta-principle-passage")
+        { "no_members" => "This map has no members, as a setup that wrote it before its first member, or removing " \
+                          "its last member, leaves it. Either remove #{file} and commit the removal, or add its " \
+                          "first member with the add-member this prints: #{setup}" }
+      end
+
+      private
+
+      # The line that puts setting principles up first, ending in its command.
+      #: () -> String
+      def set_up_first
+        Prompts.text("set-principles-up/set-up-first",
+                     command: @invocation.in_project("show-meta-principle-passage"))
+      end
+
+      # member, with its repairs when broken names it.
+      #: (String, Hash[String, untyped], Array[String]) -> Hash[String, untyped]
+      def repaired(id, member, broken)
+        MemberRepairs.new(@invocation).beside(id, member, broken: broken.include?(member.fetch("id")))
+      end
+
+      # Repair each member in broken, the ids of those an audit would refuse; otherwise audit when one changed or was
+      # never assessed.
+      #: (PrintedPrinciple, Array[String]) -> String
+      def shown_next_action(principle, broken)
+        unless broken.empty?
+          return "Repair each member that cannot be found or read before auditing, with one of the commands in " \
+                 "its repair_with: #{broken.join(", ")}."
+        end
+
+        "Audit when a member is changed or unassessed: #{@invocation.in_project("start-audit", principle.id)}"
+      end
+    end
+  end
+end

data/lib/principles/views/principle_with_changed_members.rb

@@ -0,0 +1,26 @@
+# 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
+    # One other principle whose members a completed audit's fixes changed or broke, as its result names it under
+    # other_principles_with_changed_members, to re-audit by its id (#410, #823).
+    class PrincipleWithChangedMembers
+      #: (principle_id: String, members: Array[Hash[String, untyped]]) -> void
+      def initialize(principle_id:, members:)
+        @principle_id = principle_id
+        @members = members
+        freeze
+      end
+
+      # The principle to re-audit.
+      #: String
+      attr_reader :principle_id
+
+      # The fields as printed: the principle's id and each changed or broken member, by id with its state.
+      #: () -> Hash[String, untyped]
+      def to_h = { "principle_id" => @principle_id, "members" => @members }
+    end
+  end
+end

data/lib/principles/views/principles_with_no_completed_audit.rb

@@ -0,0 +1,30 @@
+# 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
+    # The principles no full audit has completed, as list-member-problems' next_action names them in one line, then
+    # each one's audit to start on a line of its own, filled and shell-quoted so the agent types no id (D58, #731,
+    # #755).
+    class PrinciplesWithNoCompletedAudit
+      # audits holds each principle's start-audit command, in the order of ids.
+      #: (ids: Array[String], audits: Array[String]) -> void
+      def initialize(ids:, audits:)
+        @ids = ids
+        @audits = audits
+        freeze
+      end
+
+      #: () -> String
+      def to_s
+        one = @ids.length == 1
+        carry = one ? "its members carry it" : "their members carry them"
+        "No full audit has completed for #{ProseList.new(@ids)}, so whether #{carry} is unknown. " \
+          "To start #{one ? "one" : "each"}:\n#{@audits.join("\n")}"
+      end
+    end
+  end
+end

data/lib/principles/views/printed_principle.rb

@@ -0,0 +1,45 @@
+# 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
+    # A principle as printed: its id, map file, description and members. Each member is a plain hash that
+    # already carries its "id", and on show-principle its snapshot and freshness too.
+    class PrintedPrinciple
+      #: String
+      attr_reader :id
+      #: String
+      attr_reader :file
+      #: String?
+      attr_reader :description
+      #: Array[Hash[String, untyped]]
+      attr_reader :members
+      #: Hash[String, untyped]?
+      attr_reader :activation
+
+      # activation is when the agent said the principle's work is in hand, or nil when it has not said (D38).
+      #: (id: String, file: String, description: String?, members: Array[Hash[String, untyped]],
+      #|  ?activation: Hash[String, untyped]?) -> void
+      def initialize(id:, file:, description:, members:, activation: nil)
+        @id = id
+        @file = file
+        @description = description
+        @members = members.freeze #: Array[Hash[String, untyped]]
+        @activation = activation #: Hash[String, untyped]?
+        freeze
+      end
+
+      # What the principle declares as a whole: its description, and its activation once the agent has said it.
+      #: () -> Hash[String, untyped]
+      def declared
+        { "description" => @description, **({ "activation" => @activation } if @activation) }
+      end
+
+      #: () -> Hash[String, untyped]
+      def map
+        { **declared, "members" => @members }
+      end
+    end
+  end
+end

data/lib/principles/views/prior_finding_decisions_result.rb

@@ -0,0 +1,35 @@
+# 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 a completed full audit's result says what it decided about each prior finding (D35).
+    class PriorFindingDecisionsResult
+      # kept_ids are the prior findings it kept and closed those it closed; dropped is any pointer a kept one's
+      # decision dropped (#374), waits_on_dropped any waits_on it dropped, with null or by accepting it (D52), and
+      # evidence_replaced each kept evidence item a decision gave a new place, as it was and is now (D70).
+      #: (kept_ids: Array[String], closed: Array[Hash[String, untyped]], dropped: Array[Hash[String, untyped]],
+      #|  waits_on_dropped: Array[Hash[String, untyped]], evidence_replaced: Array[Hash[String, untyped]]) -> void
+      def initialize(kept_ids:, closed:, dropped:, waits_on_dropped:, evidence_replaced:)
+        @kept_ids = kept_ids
+        @closed = closed
+        @dropped = dropped
+        @waits_on_dropped = waits_on_dropped
+        @evidence_replaced = evidence_replaced
+        freeze
+      end
+
+      # output, with these decisions added; unchanged when there were no prior findings to decide.
+      #: (Hash[String, untyped]) -> Hash[String, untyped]
+      def added_to(output)
+        return output if @kept_ids.empty? && @closed.empty?
+
+        decided = output.merge("prior_findings_kept" => @kept_ids, "prior_findings_closed" => @closed)
+        decided = decided.merge("prior_findings_pointers_dropped" => @dropped) unless @dropped.empty?
+        decided = decided.merge("prior_findings_waits_on_dropped" => @waits_on_dropped) unless @waits_on_dropped.empty?
+        @evidence_replaced.empty? ? decided : decided.merge("prior_findings_evidence_replaced" => @evidence_replaced)
+      end
+    end
+  end
+end