principles 0.0.1

data/lib/principles/models/audit_record.rb

@@ -0,0 +1,249 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "audit_start"
+require_relative "cited_files"
+require_relative "decided_prior_findings"
+require_relative "open_finding"
+require_relative "principles_package"
+require_relative "recorded_findings"
+require_relative "recorded_members"
+require_relative "json_digest"
+require_relative "write_up_repoint"
+require_relative "../data/schema_check"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # The committed record of a principle's last audit: what it began from, each member's hash when it was
+    # made and each finding's outcome with its problem (D34). Outside git it also keeps the hashes the audit
+    # began from, which git keeps otherwise, and an open record keeps the last completed one, whose deferred
+    # and accepted findings the next audit must still decide (D35).
+    class AuditRecord
+      # The record an audit that began at start writes, with each member's hash, the result reported for its
+      # check, if any (D30), and each finding's outcome. The hashes the audit began from are kept only outside
+      # git, where start has no base commit.
+      #: (AuditStart, status: String, audited_at: String, members: Hash[String, String], findings: Array[untyped])
+      #|  -> AuditRecord
+      def self.written(start, status:, audited_at:, members:, findings:)
+        fields = { "principle_id" => start.id, "status" => status, "map_version" => start.map_version,
+                   "base_commit" => start.base, "audited_at" => audited_at,
+                   "members" => start.recorded(members, assessed_at: audited_at), "findings" => findings }
+        new(start.base ? fields : fields.merge("base_members" => start.before))
+      end
+
+      #: (Hash[String, untyped]) -> void
+      def initialize(fields)
+        @fields = fields.freeze #: Hash[String, untyped]
+        @members = RecordedMembers.new(fields.fetch("members")) #: RecordedMembers
+        freeze
+      end
+
+      # The record with only the fields this tool knows, for printing.
+      #: () -> Hash[String, untyped]
+      def shown
+        Data::SchemaCheck.new("audit-record").known(@fields)
+      end
+
+      # The record as its file holds it.
+      #: () -> Hash[String, untyped]
+      def to_h
+        @fields
+      end
+
+      # A digest of the whole record. A correction carries the last completed record's from when its request was
+      # printed, so it is refused once that record changed (#646). A formatter that only reorders its keys changes
+      # neither what the record says nor its revision, as same_as? already compares it (#656).
+      #: () -> String
+      def revision = JsonDigest.new(@fields).to_s
+
+      #: () -> String
+      def principle_id
+        @fields.fetch("principle_id")
+      end
+
+      # The hashes the audit began from, kept outside git only.
+      #: () -> Hash[String, String]?
+      def base_members
+        @fields["base_members"]
+      end
+
+      # Whether other says what this record says, apart from when it and its assessments were made.
+      #: (AuditRecord?) -> bool
+      def same_as?(other)
+        !other.nil? && other.undated == undated
+      end
+
+      # What this record says, without when it and each of its assessments were made.
+      #: () -> Hash[String, untyped]
+      def undated = @fields.except("audited_at").merge("members" => members.undated)
+
+      # The commit the audit began from, or nil outside git.
+      #: () -> String?
+      def base_commit
+        @fields["base_commit"]
+      end
+
+      # The record's status, when and from which commit it was made, and whether the map changed since.
+      #: (map_version: String) -> Hash[String, untyped]
+      def last_audit(map_version:)
+        { "status" => @fields["status"], "audited_at" => @fields["audited_at"], "base_commit" => @fields["base_commit"],
+          "map_changed" => @fields["map_version"] != map_version }
+      end
+
+      # Why a one-member audit cannot judge member's change against this record, or nil when it can (D33): the
+      # record must be completed and have assessed the member, the member's text must differ from the one it
+      # assessed, and the member must have no check. The one owner of these preconditions, which list-member-problems
+      # asks before offering the audit that Acknowledgement refuses by them (#626, #632); git is the callers' to know.
+      #: (Member, now_sha256: String?) -> Symbol?
+      def acknowledgement_refusal(member, now_sha256:)
+        recorded = members.hash_for(member.key)
+        return :not_completed unless completed?
+        return :not_assessed unless recorded
+        return :unchanged if recorded == now_sha256
+
+        :checked if member.check
+      end
+
+      # Whether the audit this record describes completed, rather than being left open outside git.
+      #: () -> bool
+      def completed?
+        @fields["status"] == "completed"
+      end
+
+      # This open record, keeping the last completed record it replaces outside git, so the next audit still
+      # decides that record's findings (D35); itself when there is none.
+      #: (AuditRecord?) -> AuditRecord
+      def keeping(last_completed)
+        last_completed ? AuditRecord.new(@fields.merge("last_completed" => last_completed.to_h)) : self
+      end
+
+      # This record, saying what its assessments were judged against, as AuditStart#judged_against digests it (D49).
+      #: (String) -> AuditRecord
+      def judged(against) = AuditRecord.new(@fields.merge("judged_against" => against))
+
+      # This record, keeping the release of principles its audit ran under, when the principle keeps one (D68).
+      #: (PrinciplesPackage?) -> AuditRecord
+      def packaged(package) = package ? AuditRecord.new(@fields.merge("principles_package" => package.to_h)) : self
+
+      # The release of principles its audit ran under, or nil when it kept none.
+      #: () -> PrinciplesPackage?
+      def package = PrinciplesPackage.kept(@fields["principles_package"])
+
+      # Whether this record kept its members' assessments, which a record written before D49 did not.
+      #: () -> bool
+      def kept_assessments? = !@fields["judged_against"].nil?
+
+      # Whether this record's assessments answered what against digests, as AuditStart#judged_against does (D49).
+      #: (String) -> bool
+      def judged_against?(against) = @fields["judged_against"] == against
+
+      # This record with each assessment its answer carried forward taken from last, the record it replaces (D49).
+      #: (AuditRecord?) -> AuditRecord
+      def carrying(last)
+        AuditRecord.new(@fields.merge("members" => members.carrying(last&.last_completed&.members).to_h))
+      end
+
+      # The last completed audit's record: this one, or the one an open record keeps, or nil (D35).
+      #: () -> AuditRecord?
+      def last_completed
+        return self if completed?
+
+        kept = @fields["last_completed"]
+        kept ? AuditRecord.new(kept) : nil
+      end
+
+      # This record with the member known by key moved to change's to_sha256, and change kept beside it (D33).
+      # Nothing else changes: the map version, base commit and findings stay the audit's own.
+      #: (String, Hash[String, untyped]) -> AuditRecord
+      def acknowledged(key, change)
+        AuditRecord.new(@fields.merge("members" => members.acknowledged(key, change).to_h))
+      end
+
+      # This record with each finding a repoint names moved by it at at (D59); the last repoint naming a finding
+      # wins.
+      #: (Array[WriteUpRepoint], at: String) -> AuditRecord
+      def repointed(repoints, at:)
+        AuditRecord.new(@fields.merge("findings" => findings.repointed(repoints, at: at).to_a))
+      end
+
+      # The ids of the findings it leaves open whose recorded_at points elsewhere than earlier's did, as a repoint
+      # moved them (D59, T16).
+      #: (AuditRecord) -> Array[String]
+      def write_ups_moved_since(earlier)
+        before = earlier.left_open.to_h { |finding| [finding.id, finding.recorded_at] }
+        left_open.select { |finding| before.key?(finding.id) && before[finding.id] != finding.recorded_at }.map(&:id)
+      end
+
+      # Each finding the last completed audit deferred or accepted, which the next full audit must decide (D35):
+      # this record's own, or, while it is open outside git, those of the completed record it keeps, since its own
+      # wait on its correction (#655). The one owner of which record's findings are open.
+      #: () -> Array[OpenFinding]
+      def left_open
+        return findings.left_open if completed?
+
+        last_completed&.left_open || []
+      end
+
+      # The ids of the findings it leaves open, as list-open-findings lists them: deferred or accepted, its own and any
+      # prior finding kept (#714).
+      #: () -> Array[String]
+      def open_ids = left_open.map(&:id)
+
+      # The ids of the findings its audit resolved: those it fixed, and each prior finding decided resolved, never
+      # one withdrawn (#714).
+      #: (DecidedPriorFindings) -> Array[String]
+      def resolved_ids(decided)
+        findings.fixed_ids + decided.resolved_ids
+      end
+
+      # Each finding left open, as list-open-findings prints it (D35, brief finding 13).
+      #: () -> Array[Hash[String, untyped]]
+      def open_findings = left_open.map(&:listed)
+
+      # Each finding left open, as the next full audit's request lists it (D35).
+      #: () -> Array[Hash[String, untyped]]
+      def prior_findings = left_open.map(&:for_next_audit)
+
+      # The path of each file this record points at, through its assessments' evidence and its findings' evidence
+      # and write-ups, which a clone must hold for the record to be checked there (#724).
+      #: () -> Array[String]
+      def cited_paths = (members.cited_paths + findings.cited_paths).uniq
+
+      # The files this record cites, as history holds them now: which go with it when its completed audit is
+      # committed, compared with HEAD only in git, and which no longer exist (#724, #861).
+      #: (ProjectHistory) -> CitedFiles
+      def cited_files(history) = CitedFiles.new(cited_paths, history, in_git: !base_commit.nil?)
+
+      # The members this record assessed, each with its hash, check, loading decision and acknowledgements.
+      #: RecordedMembers
+      attr_reader :members
+
+      # The command this record ran for the member known by key's check, as its RecordedMembers answers it, or nil
+      # when it gave that check no exit status.
+      #: (String) -> String?
+      def check_run_for(key) = members.check_run_for(key)
+
+      # The line saying what the review of the check this record ran for the member known by key rested on, with the
+      # date it was first kept: its own review_basis_since, or else this record's audited_at, which dates a line kept
+      # here first (D63, D52). Nothing when the record ran no check for it or kept no line.
+      #: (String) -> Hash[String, untyped]
+      def check_review_for(key)
+        kept = members.check_review_as_kept(key)
+        return {} unless kept.key?("review_basis")
+
+        { "review_basis_since" => @fields["audited_at"] }.merge(kept)
+      end
+
+      private
+
+      # The findings its own audit recorded, whatever it did about each, with the principle, audit time and members
+      # it recorded them under.
+      #: () -> RecordedFindings
+      def findings
+        RecordedFindings.new(@fields.fetch("findings"), principle_id: principle_id, audited_at: @fields["audited_at"],
+                                                        members: members)
+      end
+    end
+  end
+end

data/lib/principles/models/audit_records.rb

@@ -0,0 +1,103 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "../data/audit_files"
+require_relative "audit_record"
+require_relative "project_history"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # Every principle's audit record, loaded and saved through Data::AuditFiles, and read as a commit held it
+    # through ProjectHistory.
+    class AuditRecords
+      #: (Data::AuditFiles, ProjectHistory) -> void
+      def initialize(files, history)
+        @files = files
+        @history = history
+      end
+
+      # The file id's record was in at commit, and that record, or nil when commit holds it in neither the folder
+      # nor its earlier name, as outside git (D53). It is read only at a commit an agent names; nothing walks history.
+      #: (String, String) -> [String, AuditRecord]?
+      def at(id, commit)
+        [file(id), earlier_file(id)].each do |path|
+          text = @history.text_at(commit, path) or next
+          return [path, AuditRecord.new(@files.parse(id, text))]
+        end
+        nil
+      end
+
+      # id's record, or nil when it has none; Data::AuditFiles refuses one that is unparseable.
+      #: (String) -> AuditRecord?
+      def find(id)
+        fields = @files.read(id)
+        fields && AuditRecord.new(fields)
+      end
+
+      # The findings id's record leaves open: none when it has no record, and none when its record cannot be read,
+      # which list-member-problems reports, so a command reading other principles' findings beside its own is not
+      # refused for theirs (#772).
+      #: (String) -> Array[OpenFinding]
+      def left_open_or_none(id)
+        find(id)&.left_open || []
+      rescue Error
+        []
+      end
+
+      # The record of each of ids that has one.
+      #: (Array[String]) -> Array[AuditRecord]
+      def of(ids) = ids.filter_map { |id| find(id) }
+
+      # id's record, refused when it has none.
+      #: (String) -> AuditRecord
+      def fetch(id)
+        find(id) || raise(Error.new("unknown_audit", "#{id} has no audit record",
+                                    "To audit it: #{Error::EXECUTABLE} start-audit #{id}", file(id)))
+      end
+
+      #: (String) -> bool
+      def exist?(id)
+        @files.exist?(id)
+      end
+
+      # The record as a change to write, unless it says what the record on disk says, apart from when.
+      #: (AuditRecord) -> Array[AuditRecord]
+      def changes(record)
+        record.same_as?(find(record.principle_id)) ? [] : [record]
+      end
+
+      # What record's completed audit asks to commit: its own file, then the files the record says go with it, of
+      # changed and those it cites, with what reported cites that the record does not keep (#855, #860).
+      #: (AuditRecord, Array[String], ?AssessmentReport) -> Array[String]
+      def files_to_commit(record, changed, reported = AssessmentReport::NONE)
+        [file(record.principle_id), *record.cited_files(@history).committed_with(changed, reported)]
+      end
+
+      # Each file record cites that no longer exists, which files_to_commit leaves out (#861).
+      #: (AuditRecord) -> Array[String]
+      def cited_files_missing(record) = record.cited_files(@history).missing
+
+      # Writes record's file and names it, relative to the project.
+      #: (AuditRecord) -> String
+      def save(record)
+        id = record.principle_id
+        @files.write(id, record.to_h)
+        file(id)
+      end
+
+      # The file id's record is kept in, relative to the project.
+      #: (String) -> String
+      def file(id)
+        @files.relative(id)
+      end
+
+      # The file id's record was kept in under the folder's earlier name, relative to the project (#536).
+      #: (String) -> String
+      def earlier_file(id)
+        @files.earlier_relative(id)
+      end
+    end
+  end
+end

data/lib/principles/models/audit_start.rb

@@ -0,0 +1,96 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "assessment_report"
+require_relative "json_digest"
+require_relative "member_map"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # What an audit began from: the principle and its map, the commit it was based on (nil outside git) and
+    # each member's hash then, and what the assessment reported beyond its findings, as its AssessmentReport holds it.
+    class AuditStart
+      #: String?
+      attr_reader :base
+      #: Hash[String, String]
+      attr_reader :before
+
+      # What the assessment reported beyond its findings, such as each member's record entry fields.
+      #: AssessmentReport
+      attr_reader :reported
+
+      # The map of the principle the audit is of.
+      #: MemberMap
+      attr_reader :map
+
+      #: (map: MemberMap, base: String?, before: Hash[String, String], ?reported: AssessmentReport) -> void
+      def initialize(map:, base:, before:, reported: AssessmentReport::NONE)
+        @map = map
+        @base = base
+        @before = before
+        @reported = reported
+        freeze
+      end
+
+      # The principle the audit is of, as its map names it.
+      #: () -> String
+      def id = @map.id
+
+      # Each member's entry in the record, by id, from its hash in members: the hash, its key when it has moved,
+      # and what the assessment reported for it, if anything, its assessment kept as made at assessed_at. A member
+      # added during the audit has no entry, since no assessment read it: the record gives it no baseline, so the
+      # next audit judges it (T69).
+      #: (Hash[String, String], assessed_at: String) -> Hash[String, Hash[String, untyped]]
+      def recorded(members, assessed_at:)
+        keys = @map.members.moved_keys
+        members.select { |id, _| began_with?(id) }.to_h do |id, sha|
+          entry = { "sha256" => sha }.merge(keys.key?(id) ? { "key" => keys[id] } : {})
+          [id, with_assessment(entry.merge(@reported.entry_fields_of(id)), assessed_at, changed: @before[id] != sha)]
+        end
+      end
+
+      private
+
+      # Whether the audit began with member id, rather than a correction adding it (T69).
+      #: (String) -> bool
+      def began_with?(id) = @before.key?(id)
+
+      # The entry with its assessment dated assessed_at, and an observed sighting the answer gave no observed_at for
+      # dated then too (#680), or a carried one left for completion to fill; when the member changed during the
+      # audit, as a fix in its correction changes it, no assessment read the text it is recorded at, so it keeps none
+      # and says why (D49).
+      #: (Hash[String, untyped], String, changed: bool) -> Hash[String, untyped]
+      def with_assessment(entry, assessed_at, changed:)
+        kept = entry["assessment"] or return entry
+        return entry.except("assessment").merge("changed_during_last_audit" => true) if changed
+        return entry if kept["carried_forward"]
+
+        seen = kept["delivery"] == "observed" ? assessed_at : nil
+        entry.merge("assessment" => { "assessed_at" => assessed_at, "observed_at" => seen }.compact.merge(kept))
+      end
+
+      public
+
+      # A digest of what this audit's assessments answered: the principle's description and question, the question
+      # this tool asked. When either changes, the next full audit carries no assessment forward (D49).
+      #: (String) -> String
+      def judged_against(question) = JsonDigest.new("description" => @map.description, "question" => question).to_s
+
+      # The map's version: the digest of its JSON, so any change to it gives a new version.
+      #: () -> String
+      def map_version = @map.version
+
+      # The members in now that the audit did not begin with, as a correction adds a member a finding said was
+      # missing (T69).
+      #: (now: Hash[String, String]) -> Array[String]
+      def added(now:) = now.keys.reject { |id| began_with?(id) }
+
+      # The members whose hash in now differs from their hash when the audit began.
+      #: (now: Hash[String, String]) -> Array[String]
+      def changed(now:)
+        now.reject { |member, sha| @before[member] == sha }.keys
+      end
+    end
+  end
+end

data/lib/principles/models/audited_member_lines.rb

@@ -0,0 +1,45 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "evidence_item"
+require_relative "located_text"
+require_relative "line_span"
+
+module Principles
+  # The domain logic, which loads and saves itself through data/. models/CLAUDE.md owns the boundary.
+  module Models
+    # The lines a full audit's members span now, each with its file, against which each evidence item of another
+    # principle's open finding is said to share lines or not (#792, D64). These are lines, not a verdict on whether
+    # the finding is about the same problem, which the agent judges.
+    class AuditedMemberLines
+      # located gives, under each audited member's id, the text found for it now: its path and its lines.
+      #: (Hash[String, LocatedText]) -> void
+      def initialize(located)
+        @spans = located.transform_values { |found| [found.path, found.span] } #: Hash[String, [String, LineSpan]]
+        freeze
+      end
+
+      # The item as the record keeps it, with what its lines are now beside these members': the members whose lines it
+      # shares, or that it shares none, with its lines; that it names only a whole file; or that locate, which finds
+      # it in its file now, can no longer find it, so one moved write-up never refuses the request.
+      #: (EvidenceItem) { (Locator) -> LocatedText } -> Hash[String, untyped]
+      def facts_of(item, &locate)
+        return item.with_facts("whole_file" => true) if item.whole_file?
+
+        span = locate.call(item.locator).span
+        item.with_facts("first_line" => span.first_line, "last_line" => span.last_line, **sharing(item.path, span))
+      rescue Error
+        item.with_facts("not_located" => true)
+      end
+
+      private
+
+      #: (String, LineSpan) -> Hash[String, untyped]
+      def sharing(path, span)
+        ids = @spans.select { |_, (on, member)| on == path && member.shares_a_line_with?(span) }.keys
+        ids.empty? ? { "shares_no_lines" => true } : { "shares_lines_with" => ids }
+      end
+    end
+  end
+end

data/lib/principles/models/candidate_files.rb

@@ -0,0 +1,66 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Principles
+  # The domain logic, which loads and saves itself through data/. models/CLAUDE.md owns the boundary.
+  module Models
+    # The instruction files list-candidate-files offers, shortened without judging what is guidance. A
+    # skill's templates, references and examples once filled most of a 10KB inventory (alpha 011
+    # friction 2). So Markdown files and harness settings are listed one by one, except inside a skill,
+    # where only SKILL.md, the file the harness loads, is listed. Every other file is counted under its
+    # directory. The agent still sees where every file is, and decides what to read.
+    class CandidateFiles
+      # A file a harness reads as settings, listed by name like guidance.
+      SETTINGS = %r{(?:\A|/)\.claude/settings[^/]*\.json\z}
+      MARKDOWN = /\.md\z/i
+      # A file inside a skill's folder, and whether it is the skill's entry point.
+      IN_SKILL = %r{(?:\A|/)\.claude/skills/[^/]+/}
+      SKILL_ENTRY = %r{(?:\A|/)\.claude/skills/[^/]+/SKILL\.md\z}
+
+      #: (Array[Hash[String, untyped]]) -> void
+      def initialize(files)
+        @files = files #: Array[Hash[String, untyped]]
+        freeze
+      end
+
+      # The inventory's files, the other files counted by directory, and those test-data hints that name a
+      # listed file.
+      #: (Array[Hash[String, untyped]]) -> Hash[String, untyped]
+      def listing(test_data_hints)
+        paths = listed.map { |file| file.fetch("path") }
+        { "files" => listed, "other_files_by_directory" => other_files_by_directory,
+          "possibly_test_data" => test_data_hints.select { |hint| paths.include?(hint.fetch("path")) } }
+      end
+
+      # Each Markdown or settings file, with its size.
+      #: () -> Array[Hash[String, untyped]]
+      def listed
+        @files.select { |file| named?(file.fetch("path")) }
+      end
+
+      # Each directory holding other files, and how many.
+      #: () -> Array[Hash[String, untyped]]
+      def other_files_by_directory
+        others = @files.map { |file| file.fetch("path") }.reject { |path| named?(path) }
+        others.group_by { |path| directory(path) }.sort.map do |directory, paths|
+          { "directory" => directory, "files" => paths.length }
+        end
+      end
+
+      private
+
+      #: (String) -> String
+      def directory(path)
+        parent = path.rpartition("/").first
+        parent.empty? ? "." : parent
+      end
+
+      #: (String) -> bool
+      def named?(path)
+        return path.match?(SKILL_ENTRY) if path.match?(IN_SKILL)
+
+        path.match?(MARKDOWN) || path.match?(SETTINGS)
+      end
+    end
+  end
+end

data/lib/principles/models/candidate_inventory.rb

@@ -0,0 +1,67 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "candidate_listing"
+require_relative "project_history"
+
+module Principles
+  # The domain logic, which loads and saves itself through data/. models/CLAUDE.md owns the boundary.
+  module Models
+    # What list-candidate-files found: the inventory of candidate files as CandidateListing lists them, and in git
+    # which of them, or of the files their links lead to, git does not track. Each list that names a file is
+    # something the agent asks the project's owner about before mapping, and only those are asked, since asks for
+    # empty lists hid the one that applied (#405).
+    class CandidateInventory
+      # The lists the agent asks the owner about, in the order the asks are put.
+      OWNER_ASK_KEYS = %w[possibly_test_data untracked ignored ignored_folders].freeze
+
+      # The most paths an ask names inline: a short list can be pasted to the owner as it stands, while a
+      # longer one would bury the ask, so the agent reads it from its list instead (#412).
+      NAMED_INLINE_AT_MOST = 3
+
+      # What the project's inventory lists, and which listed files, or files their links lead to, history says
+      # git does not track.
+      #: (Hash[String, untyped], ProjectHistory) -> CandidateInventory
+      def self.found(inventory, history)
+        listed = CandidateListing.new(inventory).to_h
+        new(listed, untracked: history.untracked(listed.fetch("files").map { it.fetch("path") }))
+      end
+
+      # The listing, as list-candidate-files prints it.
+      #: Hash[String, untyped]
+      attr_reader :listing
+
+      # The listed files, and the files their links lead to, git does not track; nil outside git, where nothing
+      # checked them.
+      #: Array[String]?
+      attr_reader :untracked
+
+      #: (Hash[String, untyped], untracked: Array[String]?) -> void
+      def initialize(listing, untracked:)
+        @listing = listing
+        @untracked = untracked
+        @lists = listing.merge("untracked" => untracked) #: Hash[String, untyped]
+        freeze
+      end
+
+      #: () -> Hash[String, untyped]
+      def to_h = @listing
+
+      # Each list that names a file, in OWNER_ASK_KEYS' order, with the paths its ask names inline: all of
+      # them when there are at most NAMED_INLINE_AT_MOST, and none beyond.
+      #: () -> Hash[String, Array[String]]
+      def owner_asks
+        OWNER_ASK_KEYS.select { |key| @lists[key]&.any? }.to_h do |key|
+          paths = @lists.fetch(key).map { |entry| named(entry) }
+          [key, paths.length > NAMED_INLINE_AT_MOST ? [] : paths]
+        end
+      end
+
+      private
+
+      # The path one list entry names: a file's path, a folder, or the path itself.
+      #: (untyped) -> String
+      def named(entry) = entry.is_a?(Hash) ? entry.fetch("path") { entry.fetch("folder") } : entry
+    end
+  end
+end

data/lib/principles/models/candidate_listing.rb

@@ -0,0 +1,32 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "candidate_files"
+require_relative "ignored_candidates"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # The inventory of candidate files as list-candidate-files lists it: the instruction files agent hosts load
+    # by convention, the other files counted by directory, the listed files that look like test data, and in git
+    # the ignored ones, unread, each folder git ignores counted once.
+    class CandidateListing
+      #: (Hash[String, untyped]) -> void
+      def initialize(inventory)
+        @inventory = inventory
+        freeze
+      end
+
+      #: () -> Hash[String, untyped]
+      def to_h
+        files = CandidateFiles.new(@inventory.fetch("files"))
+        listed = @inventory.except("ignored", "ignored_ancestor_folders")
+                           .merge(files.listing(@inventory.fetch("possibly_test_data")))
+        return listed unless @inventory.key?("ignored")
+
+        listed.merge(IgnoredCandidates.new(paths: @inventory.fetch("ignored"),
+                                           folders: @inventory.fetch("ignored_ancestor_folders")).listing)
+      end
+    end
+  end
+end