principles 0.0.1

data/lib/principles/controllers/member_entries.rb

@@ -0,0 +1,149 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "command"
+
+module Principles
+  # Each runs one command: reads models, applies their rules and prints through a view.
+  # controllers/CLAUDE.md owns the boundary.
+  module Controllers
+    # The writes to one member's entry in the committed member map: where the member is, the part it plays
+    # and the check that enforces it. This tool asks, the agent answers, and this tool writes the map and
+    # nothing else.
+    class MemberEntries < Command
+      # Each command and the method that runs it.
+      COMMANDS = {
+        "add-member" => :add_member, "move-member" => :move_member,
+        "change-member-role" => :change_member_role, "change-member-check" => :change_member_check,
+        "remove-member-check" => :remove_member_check, "remove-member" => :remove_member
+      }.freeze #: Hash[String, Symbol]
+
+      # Each location option and the name the agent typed it as.
+      LOCATION_OPTIONS = { "section" => "--section", "starting_at" => "--starting-at",
+                           "ending_at" => "--ending-at", "query" => "--query" }.freeze #: Hash[String, String]
+
+      #: (String, String?, Hash[String, untyped]) -> untyped
+      def call(command, id, options)
+        naming_the_executable(rerun: ->(member) { rerun(command, id.to_s, member, options) }) do
+          method = COMMANDS[command] or unknown(command)
+          send(method, required_id(id), options)
+        end
+      end
+
+      private
+
+      # command as the agent ran it on principle id, with member in place of the member id it gave, and its options
+      # as given, each quoted for a shell and named as the agent typed it: a location by LOCATION_OPTIONS, any other,
+      # such as --path or --role, by its own one-word name (D56).
+      #: (String, String, String, Hash[String, untyped]) -> String
+      def rerun(command, id, member, options)
+        flags = options.except("project", "member").flat_map do |name, value|
+          [LOCATION_OPTIONS.fetch(name) { "--#{name}" }, value.to_s]
+        end
+        invocation.in_project(command, id, member, options: flags)
+      end
+
+      #: (String, Hash[String, untyped]) -> untyped
+      def add_member(id, options)
+        started = !@member_maps.mapped?(id)
+        map = @member_maps.addable(id)
+        member = located(options, { "path" => text(options["path"], "PATH") }).merge(played(options))
+        write_map(map.adding(member)) do |printed|
+          added = member_added(printed, map, member)
+          started ? added.merge(map_result.map_created(printed)) : added
+        end
+      end
+
+      # What add-member reports of the member it added to map: its id, lines and check, and the members, in
+      # this map or another, that share a line with it, so the agent sees an edit there shows on each (#383).
+      #: (Views::PrintedPrinciple, Models::MemberMap, Hash[String, untyped]) -> Hash[String, untyped]
+      def member_added(printed, map, member)
+        added = Models::Member.new(member)
+        map_result.member_added(printed, added: span(member).merge(member.slice("check")),
+                                         shared: lines_shared(added, map))
+      end
+
+      # The part a new member plays, and the check that enforces it when one is named (D30).
+      #: (Hash[String, untyped]) -> Hash[String, untyped]
+      def played(options)
+        role = { "role" => text(options["role"], "--role") }
+        options["check"] ? role.merge("check" => text(options["check"], "--check")) : role
+      end
+
+      # The member's id and the lines it spans in its file now, so the agent sees what it located.
+      #: (Hash[String, untyped]) -> Hash[String, untyped]
+      def span(member)
+        { "id" => Models::Member.new(member).id }
+          .merge(snapshot(Models::Member.new(member).locator).slice("first_line", "last_line"))
+      end
+
+      # Points an existing member at a new place (a narrower passage, a renamed heading, an anchor that was
+      # lost, or with --path a file that was renamed) without taking it out of the map, so it keeps its key and
+      # its audit (#268).
+      #: (String, Hash[String, untyped]) -> untyped
+      def move_member(id, options)
+        map = @member_maps.find(id)
+        old = map.member(text(options["member"], "MEMBER"))
+        member = located(options, { "path" => new_path(options, old) })
+        moved = span(member)
+        write_map(map.moving(Models::Member.new(old).id, member)) do |printed|
+          map_result.member_moved(printed, from: Models::Member.new(old).id, moved: moved)
+        end
+      end
+
+      # The path --path names, or else the member's own.
+      #: (Hash[String, untyped], Hash[String, untyped]) -> String
+      def new_path(options, old)
+        options["path"] ? text(options["path"], "--path") : old.fetch("path")
+      end
+
+      #: (String, Hash[String, untyped]) -> untyped
+      def change_member_role(id, options)
+        map = @member_maps.find(id)
+        target = Models::Member.new(map.member(text(options["member"], "MEMBER"))).id
+        write_map(map.changing_role(target, text(options["role"], "--role"))) do |printed|
+          map_result.member_replaced(printed, member: target, done: "Changed the role of #{target}.")
+        end
+      end
+
+      # Names the command that enforces a member, which the audit asks the agent to run (D30).
+      #: (String, Hash[String, untyped]) -> untyped
+      def change_member_check(id, options)
+        map = @member_maps.find(id)
+        target = Models::Member.new(map.member(text(options["member"], "MEMBER"))).id
+        check = text(options["check"], "--check")
+        changed = map.changing_check(target, check)
+        hidden = Models::Member.new(changed.member(target)).check_hidden_characters
+        write_map(changed) { |printed| map_result.check_changed(printed, member: target, hidden: hidden) }
+      end
+
+      #: (String, Hash[String, untyped]) -> untyped
+      def remove_member_check(id, options)
+        map = @member_maps.find(id)
+        target = Models::Member.new(map.member(text(options["member"], "MEMBER"))).id
+        write_map(map.removing_check(target)) do |printed|
+          map_result.member_replaced(printed, member: target,
+                                              done: "Removed the check of #{target}; the audit no longer asks for " \
+                                                    "its result.")
+        end
+      end
+
+      #: (String, Hash[String, untyped]) -> untyped
+      def remove_member(id, options)
+        map = @member_maps.find(id)
+        target = text(options["member"], "MEMBER")
+        write_map(map.removing(target)) { |printed| map_result.member_removed(printed, removed: target) }
+      end
+
+      # The member's place in its file from --section, --starting-at and --ending-at, checked to resolve.
+      #: (Hash[String, untyped], Hash[String, untyped]) -> Hash[String, untyped]
+      def located(options, member)
+        LOCATION_OPTIONS.each { |key, flag| member[key] = text(options[key], flag) if options[key] }
+        place = Models::Member.new(member)
+        place.check_location
+        snapshot(place.locator)
+        member
+      end
+    end
+  end
+end

data/lib/principles/controllers/members_a_commit_changed.rb

@@ -0,0 +1,43 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "command"
+require_relative "../views/members_a_commit_changed"
+
+module Principles
+  # Each runs one command: reads models, applies their rules and prints through a view.
+  # controllers/CLAUDE.md owns the boundary.
+  module Controllers
+    # list-member-problems --commits-after COMMIT --hook-event EVENT, which the plugin's after-commit hook runs once a
+    # Bash call moved HEAD (D73): the members the commits after COMMIT changed, as the hook's JSON, or nothing. It
+    # exits 0 whatever it finds, since the host shows the user an error for any other status, and reports a refusal
+    # only when those commits could have caused it, so a broken setup does not repeat at every commit (review R8).
+    class MembersACommitChanged < Command
+      # report gives list-member-problems' result for every map, as Inventory checks it, or raises its refusal.
+      #: (Models::Project, tool: RunningTool, report: ^() -> Hash[String, untyped]) -> void
+      def initialize(project, tool:, report:)
+        super(project, tool: tool)
+        @report = report
+      end
+
+      # The hook's output for the commits after `after`, run for event.
+      #: (after: String, event: String) -> Views::Lines
+      def printed(after:, event:)
+        members = @report.call.fetch("members")
+        changed = @history.commits_brought_in(after).changed_by(members)
+        return Views::MembersACommitChanged::NOTHING if changed.empty?
+
+        view.changed(event, changed, others: members.size - changed.size)
+      rescue Error => e
+        return Views::MembersACommitChanged::NOTHING unless @history.touched_since?(after, @member_maps.readable_paths)
+
+        view.refused(event, e.payload.fetch("code"))
+      end
+
+      private
+
+      #: () -> Views::MembersACommitChanged
+      def view = Views::MembersACommitChanged.new(invocation)
+    end
+  end
+end

data/lib/principles/controllers/members_to_assess.rb

@@ -0,0 +1,160 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "command"
+require_relative "../models/check_since_last_audit"
+require_relative "../models/open_findings_elsewhere"
+require_relative "../views/acknowledged_since_last_audit"
+require_relative "../views/diff_since_last_audit"
+
+module Principles
+  # Each runs one command: reads models, applies their rules and prints through a view.
+  # controllers/CLAUDE.md owns the boundary.
+  module Controllers
+    # The members a full audit's request lists, which Audit hands over for start-audit: each as the agent assesses
+    # it, beside what the principle's audit record says of it since the last full audit.
+    class MembersToAssess < Command
+      # The members a full audit's request lists, each as the agent assesses it, and the findings other principles
+      # leave open on members sharing their lines, each once, which each member's mapped_elsewhere names by id (D62).
+      class Listing
+        #: Array[Hash[String, untyped]]
+        attr_reader :members
+
+        #: Array[Hash[String, untyped]]
+        attr_reader :open_findings_elsewhere
+
+        #: (members: Array[Hash[String, untyped]], open_findings_elsewhere: Array[Hash[String, untyped]]) -> void
+        def initialize(members:, open_findings_elsewhere:)
+          @members = members
+          @open_findings_elsewhere = open_findings_elsewhere
+          freeze
+        end
+      end
+
+      # principle_id names the principle whose members are listed, against its audit record now.
+      #: (Models::Project, tool: RunningTool, principle_id: String) -> void
+      def initialize(project, tool:, principle_id:)
+        super(project, tool: tool)
+        @principle_id = principle_id
+        @record = @audit_records.find(principle_id) #: Models::AuditRecord?
+        @completed = @record&.last_completed #: Models::AuditRecord?
+        @checks = Models::CheckSinceLastAudit.new(id: principle_id, history: @history, member_maps: @member_maps,
+                                                  record: @record) #: Models::CheckSinceLastAudit
+      end
+
+      # Each member of audit's map as the assessment request shows it, located as current has it: id, role, lines,
+      # the evidence that locates it and the check that enforces it, if any, with whether the last audit already had
+      # it run, the edits to it acknowledged since that audit, its last assessment carried forward by audit, or why
+      # it is judged again (D49) with the command that shows its file's edits since that audit (#771), and the other
+      # principles' members sharing its lines (#719), beside the findings their principles leave open on them (D62).
+      #: (Models::Audit, Models::MemberSnapshots) -> Listing
+      def listed(audit, current)
+        map = audit.map
+        carried = carried_assessments(audit)
+        elsewhere = elsewhere(map, current)
+        members = map.members_shown.map do |fields|
+          member = Models::Member.new(fields)
+          judged = carried(member, carried)
+          located(member, current).merge(checked(member), acknowledged(fields), judged,
+                                         changed_since(fields, judged), shared_lines(member, elsewhere))
+        end
+        Listing.new(members: members, open_findings_elsewhere: elsewhere_listed(elsewhere, current))
+      end
+
+      private
+
+      # Each finding elsewhere names, once, with each evidence item's lines beside this audit's members, where current
+      # locates them; the project locates each item now (D64).
+      #: (Models::OpenFindingsElsewhere, Models::MemberSnapshots) -> Array[Hash[String, untyped]]
+      def elsewhere_listed(elsewhere, current)
+        elsewhere.listed(current.audited_lines) { |locator| @project.located_text(locator) }
+      end
+
+      # The other principles' members sharing a line with each member of map where current locates it, with the
+      # findings their records leave open on them, each record read once (#772, D62). The request id hashes this
+      # principle's members, not other maps or their records: another principle changing after the request is its
+      # own audit to judge, and does not make this one stale.
+      #: (Models::MemberMap, Models::MemberSnapshots) -> Models::OpenFindingsElsewhere
+      def elsewhere(map, current)
+        sharing = map.members.ids.to_h do |id|
+          [id, Models::MembersSharingLines.new(@project, current.of(id), id: id).elsewhere(except: @principle_id)]
+        end
+        Models::OpenFindingsElsewhere.of(sharing, @audit_records)
+      end
+
+      # The other principles' members sharing a line with member, each with its role there, so a contradiction
+      # between the two maps shows in this audit (#719), naming the findings that principle leaves open on it, so one
+      # problem is not raised under both (#772, D62); nothing when there are none.
+      #: (Models::Member, Models::OpenFindingsElsewhere) -> Hash[String, untyped]
+      def shared_lines(member, elsewhere)
+        Views::LinesSharedWithMember.new(mapped_elsewhere: elsewhere.beside(member.id)).to_h
+      end
+
+      # The member's last assessment carried forward, with whether any evidence it cited changed since and, in git,
+      # whether its file changed since the last full audit's base commit, outside the member, whose own text did not;
+      # or why it is judged again. These are facts: the agent may re-judge any carried member (D49).
+      #: (Models::Member, Models::CarriedAssessments) -> Hash[String, untyped]
+      def carried(member, carried)
+        shown = carried.shown(member.id) { |locator, sha| evidence_changed?(locator, sha) }
+        kept = shown["carried_forward"]
+        base = @completed&.base_commit
+        return shown unless kept && base
+
+        { "carried_forward" => kept.merge("file_changed_outside_member" =>
+                                            @history.commits_since(base, member.path).any?) }
+      end
+
+      # Whether the evidence at locator no longer hashes to sha, or can no longer be found.
+      #: (Models::Locator, String) -> bool
+      def evidence_changed?(locator, sha)
+        snapshot(locator).fetch("sha256") != sha
+      rescue Error
+        true
+      end
+
+      # The member as the request names and locates it: id, role, evidence and its lines now.
+      #: (Models::Member, Models::MemberSnapshots) -> Hash[String, untyped]
+      def located(member, current)
+        { "id" => member.id, "role" => member.role, "evidence" => [member.reference] }
+          .merge(current.of(member.id).lines)
+      end
+
+      # The command that shows the edits to a member judged again to its file since the last full audit's base
+      # commit, over its path then and now (#557, #771); nothing for a member carried forward, or with no such
+      # commit, as outside git or before any full audit.
+      #: (Hash[String, untyped], Hash[String, untyped]) -> Hash[String, untyped]
+      def changed_since(fields, judged)
+        base = @completed&.base_commit
+        return {} unless judged["judge_because"] && base
+
+        paths = map_history(@principle_id).paths_from(base, Models::Member.new(fields).key, fields)
+        { "read_the_change" => Views::DiffSinceLastAudit.new(last_audited_commit: base, paths: paths).to_s }
+      end
+
+      # The edits to member acknowledged since the last full audit, which this audit judges together (D33, #312), with
+      # its lines then and now; its read_the_change shows the whole change (#771).
+      #: (Hash[String, untyped]) -> Hash[String, untyped]
+      def acknowledged(fields)
+        last = @completed or return {}
+
+        member = Models::Member.new(fields)
+        made = last.members.acknowledgements_for(member.key)
+        return {} if made.empty?
+
+        base = last.base_commit.to_s
+        lines = @project.member_lines_since_last_audit(member.locator, since: base).shown
+        since = Views::AcknowledgedSinceLastAudit.new(last_audited_commit: base, member_lines: lines,
+                                                      acknowledgements: made)
+        { "acknowledged_since_last_audit" => since.to_h }
+      end
+
+      #: (Models::Member) -> Hash[String, untyped]
+      def checked(member)
+        check = member.check or return {}
+        hidden = member.check_hidden_characters
+        { "check" => check, "check_since_last_audit" => @checks.of(member, check) }
+          .merge(hidden.empty? ? {} : { "check_hidden_characters" => hidden })
+      end
+    end
+  end
+end

data/lib/principles/controllers/meta_principle_setup.rb

@@ -0,0 +1,92 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "command"
+require_relative "inventory"
+require_relative "../models/entry_files"
+require_relative "../models/runs_from"
+require_relative "../models/meta_principle"
+require_relative "../models/text_size"
+require_relative "../views/meta_principle_result"
+
+module Principles
+  # Each runs one command: reads models, applies their rules and prints through a view.
+  # controllers/CLAUDE.md owns the boundary.
+  module Controllers
+    # Setting principles up: shows the map of the principle that keeps every other one held, and proposes its passage
+    # for the agent to place with the user, since this tool writes none of the project's guidance (D67, D68); the
+    # add-member it prints writes the map (T74). It takes no id, since the principle is the product's own.
+    class MetaPrincipleSetup < Command
+      #: (String, String?, Hash[String, untyped]) -> untyped
+      def call(command, _id, _options)
+        naming_the_executable do
+          command == "show-meta-principle-passage" ? show_meta_principle_passage : unknown(command)
+        end
+      end
+
+      private
+
+      # Writes nothing: with no map, it shows the one the printed add-member creates with the passage as its first
+      # member, so no memberless map waits while placement waits on an owner (T74). A map already there is shown as
+      # the project holds it, since the id is its identity, and its members in an entry file are named for the agent
+      # to judge whether one is the passage.
+      #: () -> untyped
+      def show_meta_principle_passage
+        map = @member_maps.addable(Models::MetaPrinciple::ID)
+        view = meta_principle_result
+        view.proposal(printed_principle(map), placement(view), map_in_project(map),
+                      existing_principles: existing_principles).merge("wrote" => [])
+      end
+
+      # map as the project holds it: whether it was there before this run, its members already in an entry file, and
+      # whether principles is set up, its map having a member (D75).
+      #: (Models::MemberMap) -> Views::MetaPrincipleResult::MapInProject
+      def map_in_project(map)
+        Views::MetaPrincipleResult::MapInProject.new(
+          already_mapped: @member_maps.mapped?(map.id), members_in_entry_files: map.members_in(Models::EntryFiles::PATHS),
+          set_up: @member_maps.set_up?
+        )
+      end
+
+      # The project's other principles, as list-principles lists them, which this principle's first audit keeps held.
+      #: () -> Array[Hash[String, untyped]]
+      def existing_principles = handed(Inventory).rows(@member_maps.ids - [Models::MetaPrinciple::ID])
+
+      # Where the passage can go: how this run was started and whether the hook runs in this session, the project's
+      # entry files, and the passage.
+      #: (Views::MetaPrincipleResult) -> Views::MetaPrincipleResult::Placement
+      def placement(view)
+        runs_from = Models::RunsFrom.new(@tool.executable)
+        Views::MetaPrincipleResult::Placement.new(
+          runs_from: runs_from.to_s, session_start_hook_in_this_session: runs_from.session_start_hook_in_this_session?,
+          entry_files: @project.entry_files.to_a, passage: passage(view)
+        )
+      end
+
+      # The view of show-meta-principle-passage's result, with how its printed commands map the passage.
+      #: () -> Views::MetaPrincipleResult
+      def meta_principle_result
+        Views::MetaPrincipleResult.new(invocation, passage_mapping, in_git: @history.inside_git?)
+      end
+
+      # The passage member's heading and role, the role of a passage the project has that carries one of its steps,
+      # and the role of any other place that keeps the principles held (D75).
+      #: () -> Views::MetaPrincipleResult::PassageMapping
+      def passage_mapping
+        Views::MetaPrincipleResult::PassageMapping.new(heading: Models::MetaPrinciple::PASSAGE_HEADING,
+                                                       role: Models::MetaPrinciple::PASSAGE_ROLE,
+                                                       step_role: Models::MetaPrinciple::STEP_ROLE,
+                                                       place_role: Models::MetaPrinciple::KEEPING_PLACE_ROLE)
+      end
+
+      # The passage's text, as the agent pastes it, with its size, which loads in every session (F9), and what it
+      # presumes of a teammate without principles (D71).
+      #: (Views::MetaPrincipleResult) -> Hash[String, untyped]
+      def passage(view)
+        text = view.passage
+        size = Models::TextSize.new(text).under(%w[bytes estimated_tokens])
+        { "text" => text, **size, "presumes" => view.presumes(size.fetch("estimated_tokens")) }
+      end
+    end
+  end
+end

data/lib/principles/controllers/repoint.rb

@@ -0,0 +1,68 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "time"
+require_relative "command"
+require_relative "../models/finding_write_ups"
+require_relative "../models/last_completed_revision"
+require_relative "../models/repoint"
+require_relative "../views/repoint_result"
+
+module Principles
+  # Each runs one command: reads models, applies their rules and prints through a view.
+  # controllers/CLAUDE.md owns the boundary.
+  module Controllers
+    # A repoint of a principle's open findings' write-ups (D59): start-audit ID --write-ups lists each open finding
+    # with where its write-up is now, and submit-answer points the recorded_at the agent gives in the audit record.
+    class Repoint < Command
+      # The request for principle id's open findings.
+      #: (String) -> Hash[String, untyped]
+      def start(id)
+        naming_the_executable do
+          record = @audit_records.find(id)
+          repoint = Models::Repoint.new(principle_id: id, record: record, history: @history)
+          findings = Models::FindingWriteUps.of(@project, [record].compact).listed
+          view.request(request_id: repoint.request_id.to_s, principle_id: id, revision: repoint.revision,
+                       findings: findings).merge("wrote" => [])
+        end
+      end
+
+      # The result of answering request_id with response, and the record it changes, not yet written. It is
+      # refused once the last completed record changed after the request was printed, unless it writes nothing.
+      #: (Models::RequestId, untyped) -> [Hash[String, untyped], Array[Models::AuditRecord]]
+      def answered(request_id, response)
+        id = request_id.principle_id
+        record = @audit_records.find(id)
+        repoint = Models::Repoint.new(principle_id: id, record: record, history: @history)
+        repointed = repoint.accepted(response, at: Time.now.utc.iso8601) { |locator| snapshot(locator) }
+        changes = writable_changes(record, repointed, response.dig("basis", "revision"))
+        [view.repointed(principle_id: id, file: @audit_records.file(id), outcome: outcome(repoint, repointed)), changes]
+      end
+
+      private
+
+      # What the repoint did, and each other principle's open finding whose write-up cannot be found (T16).
+      #: (Models::Repoint, Models::AuditRecord) -> Views::RepointResult::Outcome
+      def outcome(repoint, repointed)
+        others = @audit_records.of(@member_maps.ids - [repointed.principle_id])
+        Views::RepointResult::Outcome.new(repointed: repoint.moved_ids(repointed),
+                                          unchanged: repoint.unchanged_ids(repointed),
+                                          not_found_elsewhere: Models::FindingWriteUps.of(@project, others).not_found)
+      end
+
+      # The records repointed changes from record. Refused once record changed after the request, whose revision the
+      # answer quotes back, was printed, unless there are none.
+      #: (Models::AuditRecord?, Models::AuditRecord, String?) -> Array[Models::AuditRecord]
+      def writable_changes(record, repointed, revision)
+        changes = @audit_records.changes(repointed)
+        Models::LastCompletedRevision.new(revision).confirm_writable(repointed.principle_id, record, changes)
+        changes
+      end
+
+      #: () -> Views::RepointResult
+      def view
+        Views::RepointResult.new(invocation)
+      end
+    end
+  end
+end

data/lib/principles/controllers/running_tool.rb

@@ -0,0 +1,41 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../models/meta_principle"
+require_relative "../models/principles_package"
+require_relative "../views/meta_principle_passage"
+
+module Principles
+  # Each runs one command: reads models, applies their rules and prints through a view.
+  # controllers/CLAUDE.md owns the boundary.
+  module Controllers
+    # This run of the tool, as its entry point was invoked: the executable every printed command names, and the
+    # version running, which only the command line can read; and so the release of principles it comes from.
+    class RunningTool
+      #: String
+      attr_reader :executable
+
+      # version gives the version running, read only when a command needs it, since in a checkout reading it
+      # asks git.
+      #: (executable: String, version: ^() -> String) -> void
+      def initialize(executable:, version:)
+        @executable = executable
+        @version = version
+        freeze
+      end
+
+      #: () -> String
+      def version = @version.call
+
+      # The release of principles this run comes from, as the audit of map's principle keeps it: the version running
+      # and the passage as setup prints it, which only a view holds; nil for a principle whose audit keeps none (D68).
+      #: (Models::MemberMap) -> Models::PrinciplesPackage?
+      def release_kept_by(map)
+        return unless map.keeps_package?
+
+        passage = Views::MetaPrinciplePassage.new(heading: Models::MetaPrinciple::PASSAGE_HEADING).text
+        Models::PrinciplesPackage.of(version: version, passage: passage)
+      end
+    end
+  end
+end

data/lib/principles/data/audit_files.rb

@@ -0,0 +1,96 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "json"
+require_relative "../error"
+require_relative "schema_check"
+require_relative "principles_subfolder"
+require_relative "json_text"
+
+module Principles
+  # Every file and process this tool reads or writes. data/CLAUDE.md owns the boundary.
+  module Data
+    # The audit records: one JSON file per principle under .principles/audits/, committed in the audited
+    # repository beside its map. A record holds the last audit's base commit, each member's hash and each
+    # finding's id, members and action, never the agent's prose (D24, D25).
+    class AuditFiles
+      # The key a record named its principle under before the rename to principles (#536).
+      EARLIER_ID_KEY = "memeplex_id"
+
+      #: (PrinciplesSubfolder) -> void
+      def initialize(directory)
+        @directory = directory
+      end
+
+      # Which of the folder and its earlier name hold this subfolder (#536).
+      #: () -> Array[String]
+      def held_in
+        @directory.held_in
+      end
+
+      #: (String) -> bool
+      def exist?(id)
+        @directory.exist?(id)
+      end
+
+      # The record of id's last audit, or nil when it has none, checked against its schema (D29).
+      #: (String) -> Hash[String, untyped]?
+      def read(id)
+        return unless exist?(id)
+
+        parse(id, @directory.read(id, shown_as: relative(id)))
+      end
+
+      # The record of id from its text, with an older version's key upgraded, checked against its schema (D29).
+      #: (String, String) -> Hash[String, untyped]
+      def parse(id, text)
+        record = upgraded(JsonText.new(text).parsed)
+        problems = SchemaCheck.new("audit-record").problems(record)
+        return record if problems.empty?
+
+        raise Error.new("invalid_audit_record", "#{relative(id)} is not in the shape this tool writes",
+                        "Repair each field listed, or restore the record from version control.", relative(id),
+                        fields: problems)
+      rescue JSON::ParserError => e
+        raise Error.new("unparseable_audit", e.message,
+                        "Repair this audit record or restore it from version control.", relative(id))
+      end
+
+      #: (String, Hash[String, untyped]) -> void
+      def write(id, record)
+        @directory.write(id, "#{JSON.pretty_generate(record)}\n")
+      end
+
+      #: (String) -> String
+      def relative(id)
+        File.join(PrinciplesSubfolder::FOLDER, "audits", "#{id}.json")
+      end
+
+      # Where record id was kept before the folder took its name now, so it can be read at earlier commits (#536).
+      #: (String) -> String
+      def earlier_relative(id)
+        File.join(PrinciplesSubfolder::EARLIER_FOLDER, "audits", "#{id}.json")
+      end
+
+      private
+
+      # A record an older version wrote names its principle under EARLIER_ID_KEY, in the record and in the last
+      # completed record an open one keeps. It is read under principle_id, in the same place, so the next save
+      # writes the new key only; when both are present, principle_id is kept.
+      #: (untyped) -> untyped
+      def upgraded(record)
+        return record unless record.is_a?(Hash)
+
+        renamed = renamed_id(record)
+        kept = renamed["last_completed"]
+        kept.is_a?(Hash) ? renamed.merge("last_completed" => renamed_id(kept)) : renamed
+      end
+
+      #: (Hash[String, untyped]) -> Hash[String, untyped]
+      def renamed_id(record)
+        current = record.key?("principle_id") ? record.except(EARLIER_ID_KEY) : record
+        current.to_h { |key, value| [key == EARLIER_ID_KEY ? "principle_id" : key, value] }
+      end
+    end
+  end
+end