principles 0.0.1

data/lib/principles/controllers/answer.rb

@@ -0,0 +1,172 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "time"
+require_relative "command"
+require_relative "../models/finding_write_ups"
+require_relative "../models/audit"
+require_relative "../models/request_id"
+require_relative "acknowledgement"
+require_relative "correction"
+require_relative "repoint"
+require_relative "audit_completion"
+
+module Principles
+  # Each runs one command: reads models, applies their rules and prints through a view.
+  # controllers/CLAUDE.md owns the boundary.
+  module Controllers
+    # Answering an audit's requests: this tool checks the answer against the project's files and, when the
+    # audit completes, writes the committed audit record. Nothing else is stored: each request id is a
+    # digest of what the request depends on, so an answer is checked against the project as it is now (D25).
+    class Answer < Command
+      #: (String, String?, Hash[String, untyped]) -> untyped
+      def call(command, id, options)
+        naming_the_executable do
+          case command
+          when "submit-answer" then submit_answer(required_id(id), submitted(required_id(id), options))
+          when "show-answer-check"
+            check_answer(required_id(id), submitted(required_id(id), options), options.fetch("file"))
+          else unknown(command)
+          end
+        end
+      end
+
+      private
+
+      # The answer from --file, where - means it was read from stdin, checked against the schema for the phase
+      # the request id names.
+      #: (String, Hash[String, untyped]) -> untyped
+      def submitted(request_text, options)
+        @project.answer(options.fetch("file"), stdin: options["stdin"], phase: Models::RequestId.parse(request_text).phase)
+      end
+
+      # Accepts the answer and writes the record changes it makes.
+      #: (String, untyped) -> untyped
+      def submit_answer(request_text, response)
+        output, changes = judged(request_text, response)
+        wrote = changes.map { |record| @audit_records.save(record) }
+        audit_result.present(output).merge("wrote" => wrote)
+      end
+
+      # Runs every check submit-answer would, and says what it would write, writing nothing; its submit command
+      # gives answer_file, the --file value it was checked from, again.
+      #: (String, untyped, String) -> untyped
+      def check_answer(request_text, response, answer_file)
+        _, changes = judged(request_text, response)
+        written_up = Models::FindingWriteUps.of(@project, changes).written_up
+        # Only a correction's fixed dispositions claim map entries; for any other answer this is empty, read from
+        # no map, and left out.
+        audit_result.acceptable(request_text, changes.map { |record| @audit_records.file(record.principle_id) },
+                                answer_file:, open_findings_will_print: (written_up unless written_up.empty?),
+                                map_entry_changes: claimed_map_entry_changes(request_text, response))
+                    .merge("wrote" => [])
+      end
+
+      # What each map entry a correction's fix claims changed, from the map its audit started from; its audit is
+      # built only when a fix claims one.
+      #: (String, untyped) -> Array[Hash[String, untyped]]
+      def claimed_map_entry_changes(request_text, response)
+        handed(Correction).map_entry_changes(response) { audit(Models::RequestId.parse(request_text).principle_id) }
+      end
+
+      # The result of answering, and each record change the answer makes, not yet written.
+      #: (String, untyped) -> [untyped, Array[Models::AuditRecord]]
+      def judged(request_text, response)
+        request_id = Models::RequestId.parse(request_text)
+        request_id.check_answer(response)
+        case request_id.phase
+        when "acknowledgement" then handed(Acknowledgement).answered(request_id, response)
+        when "repointing" then handed(Repoint).answered(request_id, response)
+        when "assessment" then answer_assessment(request_id, response, audit(request_id.principle_id))
+        else handed(Correction).answered(request_id, response, audit(request_id.principle_id))
+        end
+      end
+
+      # The audit of principle id, against its members' hashes now.
+      #: (String) -> Models::Audit
+      def audit(id)
+        map = @member_maps.find(id)
+        Models::Audit.new(map: map, now: @project.snapshots(map).hashes)
+      end
+
+      #: (Models::RequestId, untyped, Models::Audit) -> [untyped, Array[Models::AuditRecord]]
+      def answer_assessment(request_id, response, audit)
+        basis = Models::AssessmentBasis.new(response.fetch("basis"))
+        judged_against = record_judged_against(audit)
+        prior = checked_request(request_id, basis, audit, judged_against.loads)
+        basis.printed_after.refusing_stale_first(audit.id, @audit_records.find(audit.id)) do
+          judged_assessment(response, audit, prior, judged_against, basis)
+        end
+      end
+
+      # The assessment's fields and its decisions on the prior findings checked, then the audit completed or its
+      # correction asked for.
+      #: (untyped, Models::Audit, Models::PriorFindings, Models::RecordJudgedAgainst, Models::AssessmentBasis)
+      #|  -> [untyped, Array[Models::AuditRecord]]
+      def judged_assessment(response, audit, prior, judged_against, basis)
+        assessed = audit.assessment(response, judged_against, Time.now.utc.iso8601) do |locator|
+          snapshot(locator)
+        end
+        findings = assessed.findings
+        decided = prior.decided(response["prior_finding_decisions"], findings, records: @audit_records) do |locator|
+          snapshot(locator)
+        end
+        correction(audit.assessed_start(basis.base, assessed, grounds(audit)), audit, findings, decided, basis)
+      end
+
+      # The request an assessment answers, checked against the project now, with the prior findings it listed.
+      #: (Models::RequestId, Models::AssessmentBasis, Models::Audit, Models::LoadsToCheck) -> Models::PriorFindings
+      def checked_request(request_id, basis, audit, loads)
+        audit.check_assessment_request(request_id, basis: basis, committed: committed(basis.base, audit.map),
+                                                   record: @audit_records.find(audit.id), loads: loads)
+      end
+
+      # Completes an audit with no findings. Otherwise asks the agent to correct them. Each is refused once the last
+      # completed record changed after the assessment's request was printed, the completion unless it writes
+      # nothing (D50).
+      #: (Models::AuditStart, Models::Audit, Array[untyped], Models::DecidedPriorFindings, Models::AssessmentBasis)
+      #|  -> [untyped, Array[Models::AuditRecord]]
+      def correction(start, audit, findings, decided, assessed)
+        if findings.empty?
+          return handed(AuditCompletion, replacing: assessed.printed_after).completed(start, audit, [], [], decided)
+        end
+
+        correction_request(start, audit, findings, decided, assessed)
+      end
+
+      # The correction request for findings, and outside git the open record that keeps what the audit began from.
+      # It is refused before it is printed once the last completed record changed, so no fix is made for an audit
+      # that cannot complete (D50). The check results travel in the basis, so the completed record keeps them (D30).
+      #: (Models::AuditStart, Models::Audit, Array[untyped], Models::DecidedPriorFindings, Models::AssessmentBasis)
+      #|  -> [untyped, Array[Models::AuditRecord]]
+      def correction_request(start, audit, findings, decided, assessed)
+        assessed.printed_after.confirm_unchanged(audit.id, @audit_records.find(audit.id))
+        basis = printed_basis(start, findings, decided, assessed)
+        [audit_result.correction_request(request_id: basis.request_id(audit.id, audit.now).to_s,
+                                         principle_id: audit.id, findings: findings, basis: basis.to_h,
+                                         placeholders: Models::Disposition::PLACEHOLDERS),
+         open_record_changes(start, audit, basis.to_h)]
+      end
+
+      # The basis a correction request prints, for the agent to hand back with its answer.
+      # Its revision is the one the assessment was printed after, carried forward, so the correction is refused once
+      # that record changes (#646, D50).
+      #: (Models::AuditStart, Array[untyped], Models::DecidedPriorFindings, Models::AssessmentBasis)
+      #|  -> Models::CorrectionBasis
+      def printed_basis(start, findings, decided, assessed)
+        Models::CorrectionBasis.printed(start, findings: findings, prior: decided, revision: assessed.revision)
+      end
+
+      # Outside git, the open record that keeps what the audit began from, and the last completed record, so a
+      # restarted audit still lists its prior findings (D35); in git, nothing.
+      #: (Models::AuditStart, Models::Audit, Hash[String, untyped]) -> Array[Models::AuditRecord]
+      def open_record_changes(start, audit, basis)
+        return [] if start.base
+
+        last = @audit_records.find(audit.id)&.last_completed
+        record = handed(AuditCompletion).record(start, basis.fetch("findings"), "open", audit.now, last)
+        @audit_records.changes(record)
+      end
+    end
+  end
+end

data/lib/principles/controllers/audit.rb

@@ -0,0 +1,203 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "command"
+require_relative "../models/audit"
+require_relative "../models/evidence_lines_since"
+require_relative "../models/findings_left_open"
+require_relative "../models/meta_principle"
+require_relative "../models/other_principles"
+require_relative "../models/finding_write_ups"
+require_relative "../models/uncommitted_outside_the_map"
+require_relative "../views/assessment_request"
+require_relative "../views/findings_result"
+require_relative "../views/loads_to_check_result"
+require_relative "../views/open_findings_elsewhere_result"
+require_relative "../views/open_findings_line"
+require_relative "../views/other_principles_unjudged_result"
+require_relative "../views/outside_the_map_result"
+require_relative "../views/package_since_last_audit_result"
+require_relative "../views/prior_findings_result"
+require_relative "acknowledgement"
+require_relative "members_to_assess"
+require_relative "repoint"
+
+module Principles
+  # Each runs one command: reads models, applies their rules and prints through a view.
+  # controllers/CLAUDE.md owns the boundary.
+  module Controllers
+    # Starting and showing an audit: start-audit hands the agent the assessment request, and show-audit
+    # prints the committed record. Starting writes nothing: the request id is a digest of what the request
+    # depends on, so Answer checks the answer against the project as it is then (D25).
+    class Audit < Command
+      #: (String, String?, Hash[String, untyped]) -> untyped
+      def call(command, id, options)
+        return started_audit(required_id(id), options) if command == "start-audit"
+
+        naming_the_executable do
+          case command
+          when "show-audit" then shown_audit(required_id(id))
+          when "list-open-findings" then options["short"] ? open_findings_line(id, options) : open_findings(id)
+          else unknown(command)
+          end
+        end
+      end
+
+      private
+
+      # The audit start-audit's options ask for: a one-member audit with --member, a repoint of the open
+      # findings' write-ups with --write-ups (D59), else a full audit.
+      #: (String, Hash[String, untyped]) -> Hash[String, untyped]
+      def started_audit(id, options)
+        return acknowledge(id, options["member"]) if options["member"]
+        return handed(Repoint).start(id) if options["write_ups"]
+
+        naming_the_executable { start_audit(id) }
+      end
+
+      # id's committed record. With none, an id no map has is refused as show-principle refuses it, since
+      # starting its audit would be refused too; a record kept after its map was removed still shows (#577).
+      #: (String) -> Hash[String, untyped]
+      def shown_audit(id)
+        @member_maps.find(id) unless @audit_records.exist?(id)
+        @audit_records.fetch(id).shown.merge("wrote" => [])
+      end
+
+      # A one-member audit of member_id (D33).
+      #: (String, String) -> Hash[String, untyped]
+      def acknowledge(id, member_id)
+        handed(Acknowledgement).start(id, member_id)
+      end
+
+      # The findings the last completed audit of map id, or of every map, deferred or accepted (#292, D35).
+      #: (String?) -> Hash[String, untyped]
+      def open_findings(id)
+        listed = Models::FindingWriteUps.of(@project, @audit_records.of(@member_maps.ids_of(id))).listed
+        Views::FindingsResult.new(invocation).open(listed).merge("wrote" => [])
+      end
+
+      # The one line saying how many findings are open and how long the oldest has waited until now, and which
+      # write-ups can no longer be found (#694), or nothing when none is open, for a session-start hook (D47),
+      # worded for the session's start, startup unless --session-start names another (#717).
+      #: (String?, Hash[String, untyped]) -> Views::Lines
+      def open_findings_line(id, options)
+        records = @audit_records.of(@member_maps.ids_of(id))
+        waiting = Models::FindingsLeftOpen.of(records).waiting_at(Time.now.utc)
+        Views::OpenFindingsLine.new(invocation).short(waiting, Models::FindingWriteUps.of(@project, records).not_found,
+                                                      source: options["session_start"] || "startup")
+      end
+
+      #: (String) -> untyped
+      def start_audit(id)
+        auditable = @member_maps.auditable(id)
+        base = base_commit(id, auditable)
+        current = @project.snapshots(auditable)
+        audit = Models::Audit.new(map: auditable, now: current.hashes)
+        listing = handed(MembersToAssess, principle_id: id).listed(audit, current)
+        output = assessment_request(audit, base, listing)
+        audit_result.present(with_record_notice(output, id, base)).merge("wrote" => [])
+      end
+
+      # The request, listing the findings the last completed audit left to decide, and with an id that digests them
+      # (D35) and the revision of that audit's record (#653), but not the findings other principles leave open on
+      # members sharing these lines (D62).
+      #: (Models::Audit, String?, MembersToAssess::Listing) -> Hash[String, untyped]
+      def assessment_request(audit, base, listing)
+        record = @audit_records.find(audit.id)
+        prior = audit.prior_findings(record)
+        loads = loads_to_check(audit).listed
+        basis = Models::AssessmentBasis.printed(base, record)
+        audit_result.assessment_request(request_id: audit.assessment_id(basis, prior.digested, loads).to_s,
+                                        request: request_to_assess(audit, basis, listing.members,
+                                                                   parts_to_read(audit, prior, listing, loads)))
+      end
+
+      # What the agent assesses: the members, with what else it reads beside them (D60).
+      #: (Models::Audit, Models::AssessmentBasis, Array[Hash[String, untyped]], Array[Views::RequestPart])
+      #|  -> Views::AssessmentRequest
+      def request_to_assess(audit, basis, members, parts)
+        Views::AssessmentRequest.new(principle_id: audit.id, description: audit.map.description, members: members,
+                                     basis: basis.to_h, parts: parts)
+      end
+
+      # What the agent reads beside the members, in order (D60): 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); the prior findings
+      # (D35); the findings other principles leave open on members sharing these lines (D62); and the members to
+      # check against the activation (#355); each when it lists any; and, on the meta-principle's audit, the release
+      # since its last audit (D68) and the other principles with members no audit has judged (D71).
+      #: (Models::Audit, Models::PriorFindings, MembersToAssess::Listing, Hash[String, untyped]?)
+      #|  -> Array[Views::RequestPart]
+      def parts_to_read(audit, prior, listing, loads)
+        [outside_the_map(audit), prior_findings_part(prior),
+         Views::OpenFindingsElsewhereResult.new(listing.open_findings_elsewhere).part,
+         Views::LoadsToCheckResult.new(invocation, loads, audit.id).part, package_since_last_audit(audit.map),
+         other_principles_unjudged(audit.map)].compact
+      end
+
+      # The part listing each other principle with members no audit has judged as they are now, as
+      # list-member-problems reports them, for the principle whose audit states them; nil for any other (D71).
+      #: (Models::MemberMap) -> Views::RequestPart?
+      def other_principles_unjudged(map)
+        return unless map.keeps_others_held?
+
+        listed = Models::OtherPrinciples.of(@project, but: map.id).unjudged.map do |other, members|
+          Views::PrincipleWithChangedMembers.new(principle_id: other, members: members)
+        end
+        Views::OtherPrinciplesUnjudgedResult.new(listed).part
+      end
+
+      # The part stating the release of principles the last completed audit ran under beside the one now, and
+      # whether the passage changed since, for a principle whose audit keeps one; nil for any other (D68).
+      #: (Models::MemberMap) -> Views::RequestPart?
+      def package_since_last_audit(map)
+        now = @tool.release_kept_by(map) or return
+        last = @audit_records.find(map.id)&.last_completed&.package
+        Views::PackageSinceLastAuditResult.new(invocation, at_last_audit: last&.version, now: now.version,
+                                                           passage_changed: last && now.passage_changed_since?(last))
+                                          .part
+      end
+
+      # The part listing the prior findings, in git with each evidence item saying whether its text changed since the
+      # commit the audit that left them open was based on, and whether it is found now (#858, #877); nil when there are
+      # none.
+      #: (Models::PriorFindings) -> Views::RequestPart?
+      def prior_findings_part(prior)
+        shown = prior.shown { |item, base| Models::EvidenceLinesSince.of(item, since: base, project: @project).facts }
+        Views::PriorFindingsResult.new(shown, last_audited_commit: prior.last_audited_commit).part
+      end
+
+      # The part naming the files outside the map that differ from the base commit, or nil when none do.
+      #: (Models::Audit) -> Views::RequestPart?
+      def outside_the_map(audit)
+        outside = @history.uncommitted_outside(audited_files(audit.id, audit.map))
+        Views::OutsideTheMapResult.new(outside && Models::UncommittedOutsideTheMap.new(outside).shown).part
+      end
+
+      # The commit the audit is judged against, over the map and every member's file; nil outside git.
+      #: (String, Models::MemberMap) -> String?
+      def base_commit(id, map)
+        @history.base_commit(id, audited_files(id, map))
+      end
+
+      # The map's file and every member's file.
+      #: (String, Models::MemberMap) -> Array[String]
+      def audited_files(id, map)
+        [@member_maps.file(id), *map.members.map(&:path)]
+      end
+
+      # The request, with a notice when the last audit's record was left uncommitted.
+      #: (Hash[String, untyped], String, String?) -> Hash[String, untyped]
+      def with_record_notice(output, id, base)
+        return output unless base && uncommitted_record?(id)
+
+        output.merge("notice" => audit_result.uncommitted_record_notice(@audit_records.file(id)))
+      end
+
+      # Whether the last audit's record exists but differs from the last commit, so it may be left behind.
+      #: (String) -> bool
+      def uncommitted_record?(id)
+        @audit_records.exist?(id) && @history.uncommitted([@audit_records.file(id)]).any?
+      end
+    end
+  end
+end

data/lib/principles/controllers/audit_completion.rb

@@ -0,0 +1,113 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "time"
+require_relative "command"
+require_relative "../models/audit"
+require_relative "../models/commits_since_base"
+require_relative "../models/other_principles"
+require_relative "../views/prior_finding_decisions_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 full audit's record: the open record a correction request leaves outside git, and the last step, which
+    # submit-answer reaches from an assessment with no findings or from a correction, with the record it writes,
+    # the files to commit and what landed since the base commit.
+    class AuditCompletion < Command
+      # map_changes are the changes a correction declared to the map, which name the map file to commit (D40).
+      # replacing is the revision of the last completed record when the request that completes the audit was
+      # printed, which refuses to replace a record changed since (#646).
+      #: (Models::Project, tool: RunningTool, ?map_changes: Models::DeclaredMapChanges?,
+      #|  ?replacing: Models::LastCompletedRevision?) -> void
+      def initialize(project, tool:, map_changes: nil, replacing: nil)
+        super(project, tool: tool)
+        @map_changes = map_changes #: Models::DeclaredMapChanges?
+        @replacing = replacing #: Models::LastCompletedRevision?
+      end
+
+      # The completed result, and the record change it makes, not yet written.
+      # Each prior finding's decision is applied: a kept one stays in the record, and a closed one is reported (D35).
+      #: (Models::AuditStart, Models::Audit, Array[Models::Disposition], Array[untyped], Models::DecidedPriorFindings)
+      #|  -> [untyped, Array[Models::AuditRecord]]
+      def completed(start, audit, dispositions, findings, decided)
+        written = record(start, audit.outcomes(findings, dispositions, decided), "completed", audit.now)
+        changes = @audit_records.changes(written)
+        @replacing&.confirm_writable(audit.id, @audit_records.find(audit.id), changes)
+        [completion_result(start, audit, dispositions, decided, written), changes]
+      end
+
+      # The record an audit writes, made now, saying what its assessments answered, with each assessment carried
+      # forward taken from the record it replaces (D49), and the release of principles it ran under when its
+      # principle keeps one (D68).
+      #: (Models::AuditStart, Array[untyped], String, Hash[String, String], ?Models::AuditRecord?)
+      #|  -> Models::AuditRecord
+      def record(start, findings, status, members, last_completed = nil)
+        Models::AuditRecord.written(start, status: status, audited_at: Time.now.utc.iso8601, members: members,
+                                           findings: findings)
+                           .judged(start.judged_against(Views::AssessmentRequest.question))
+                           .carrying(@audit_records.find(start.id)).packaged(@tool.release_kept_by(start.map))
+                           .keeping(last_completed)
+      end
+
+      private
+
+      # What the completed audit prints: its resolved and open findings, as the record it writes holds them, so they
+      # agree with list-open-findings (#714); what it changed; and each prior finding's decision (D35).
+      #: (Models::AuditStart, Models::Audit, Array[Models::Disposition], Models::DecidedPriorFindings,
+      #|  Models::AuditRecord) -> untyped
+      def completion_result(start, audit, dispositions, decided, written)
+        decisions = Views::PriorFindingDecisionsResult.new(kept_ids: decided.kept_ids, closed: decided.closed,
+                                                           dropped: decided.dropped,
+                                                           waits_on_dropped: decided.waits_on_dropped,
+                                                           evidence_replaced: decided.evidence_replaced)
+        audit_result.completion(principle_id: audit.id, resolved: written.resolved_ids(decided),
+                                open: written.open_ids, changes: changes(start, audit, dispositions, written),
+                                decisions: decisions)
+      end
+
+      # What the audit changed in the project: the files to commit, in git the commits since the base, the
+      # other principles whose members its fixes changed, and the members its correction added (T69).
+      #: (Models::AuditStart, Models::Audit, Array[Models::Disposition], Models::AuditRecord) -> Views::AuditChanges
+      def changes(start, audit, dispositions, written)
+        changed = audit.changed_files(dispositions)
+        added = start.added(now: audit.now)
+        map = @map_changes&.files_to_commit(@member_maps.file(audit.id), added: added) || []
+        files = @audit_records.files_to_commit(written, changed + map, start.reported)
+        Views::AuditChanges.new(files_to_commit: files, landed: landed_since_base(start, audit), added: added,
+                                other_changed: other_changed(audit, changed),
+                                cited_files_missing: @audit_records.cited_files_missing(written))
+      end
+
+      # Each other principle with a member in paths, the files this audit's fixes changed, whose own text now
+      # differs from what this tool last knew of it or whose reference broke, as list-member-problems reports it
+      # (#410). A map this tool
+      # cannot read names none here; list-member-problems reports it.
+      #: (Models::Audit, Array[String]) -> Array[Views::PrincipleWithChangedMembers]
+      def other_changed(audit, paths)
+        Models::OtherPrinciples.of(@project, but: audit.id).changed_or_broken_in(paths).map do |id, changed|
+          Views::PrincipleWithChangedMembers.new(principle_id: id, members: changed.map(&:to_h))
+        end
+      end
+
+      # In git, what landed since the base commit, as the completed result prints it; nil outside git.
+      #: (Models::AuditStart, Models::Audit) -> Views::LandedSinceBase?
+      def landed_since_base(start, audit)
+        landed = commits_since_base(start, audit) or return nil
+        Views::LandedSinceBase.new(commits_by_member: landed.by_member, head_past_base: landed.head_past_base)
+      end
+
+      # In git, for each member that changed during the audit, the commits since the base commit that touched
+      # its file, so the owner can see how each fix landed (alpha feedback A4), and HEAD now. nil outside git.
+      #: (Models::AuditStart, Models::Audit) -> Models::CommitsSinceBase?
+      def commits_since_base(start, audit)
+        base = start.base or return nil
+        by_member = start.changed(now: audit.now).to_h do |member|
+          [member, @history.commits_since(base, audit.path_of(member))]
+        end
+        Models::CommitsSinceBase.new(base: base, head: @history.head, by_member: by_member)
+      end
+    end
+  end
+end