principles 0.0.1

data/lib/principles/views/audit_commit.rb

@@ -0,0 +1,55 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "prompts"
+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
+    # How a completed audit in git says to commit what it changed: the command committing those files alone, with
+    # its default subject, which AuditChanges#commit builds. ByHand is the form outside git, with no command.
+    class AuditCommit
+      #: (files_to_commit: Array[String], subject: String, command: String) -> void
+      def initialize(files_to_commit:, subject:, command:)
+        @files_to_commit = files_to_commit
+        @subject = subject
+        @command = command
+        freeze
+      end
+
+      # The command, and beside it what replacing its default subject asks, since an agent reading commit_with
+      # alone would otherwise run the default (#853).
+      #: () -> Hash[String, String]
+      def fields
+        { "commit_with" => @command,
+          "commit_message_to_replace" => Prompts.text("report-the-completed-audit/replace-the-default-commit-message",
+                                                      subject: @subject) }
+      end
+
+      # The step that commits the files, the command ending its line (#811), up to the report that follows; its
+      # wording is its prompt's. Why the command stops during a merge is its own to say, on stderr (#828).
+      #: () -> String
+      def next_step
+        commit = Prompts.text("report-the-completed-audit/commit-only-what-the-audit-changed",
+                              files: ProseList.new(@files_to_commit).to_s, command: @command)
+        "#{commit}\nThen"
+      end
+
+      # Outside git, where no command could run as printed: only the files to commit.
+      class ByHand
+        #: (Array[String]) -> void
+        def initialize(files_to_commit)
+          @files_to_commit = files_to_commit
+          freeze
+        end
+
+        #: () -> Hash[String, String]
+        def fields = {}
+
+        #: () -> String
+        def next_step = "Commit #{ProseList.new(@files_to_commit)}. Then"
+      end
+    end
+  end
+end

data/lib/principles/views/audit_result.rb

@@ -0,0 +1,147 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "assessment_request"
+require_relative "audit_changes"
+require_relative "invocation"
+require_relative "prior_finding_decisions_result"
+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 result of an audit command. Printed commands name the executable and project that are
+    # running now, so they are added here each time: a request stays answerable after a move or reinstall
+    # (alpha 008 friction 16). A completed result names the files to commit and how to show the record,
+    # not what the agent has just written (alpha 008 friction 14, alpha 009 friction 3, alpha 010
+    # friction 2).
+    class AuditResult
+      #: (Invocation) -> void
+      def initialize(invocation)
+        @invocation = invocation
+        freeze
+      end
+
+      #: (Hash[String, untyped]) -> Hash[String, untyped]
+      def present(output)
+        output["status"] == "agent_judgement_required" ? request(output) : output
+      end
+
+      # show-answer-check: the answer passed every check, and what submitting it would write. open_findings_will_print
+      # previews each written-up finding's write_up_opening, and is nil when the record would keep none (#411).
+      # map_entry_changes gives each claimed map entry's changed role and check, left out when there is none (#462).
+      # answer_file is the --file value the answer was checked from, which the submit command gives again (#859).
+      #: (String, Array[String], answer_file: String, ?open_findings_will_print: Array[Hash[String, untyped]]?,
+      #|  ?map_entry_changes: Array[Hash[String, untyped]]) -> Hash[String, untyped]
+      def acceptable(request_id, would_write, answer_file:, open_findings_will_print: nil, map_entry_changes: [])
+        submit = @invocation.submit_answer(request_id, file: answer_file)
+        waits = "Submitting it writes nothing yet: the audit record is written when the audit completes.\n"
+        waits = "" unless would_write.empty?
+        result = { "status" => "answer_acceptable", "request_id" => request_id, "would_write" => would_write }
+        result = result.merge("open_findings_will_print" => open_findings_will_print) if open_findings_will_print
+        result = result.merge("map_entry_changes" => map_entry_changes) unless map_entry_changes.empty?
+        result.merge("next_action" => "#{waits}Submit the same answer unchanged, as you gave it: #{submit}")
+      end
+
+      # start-audit: the assessment request, as a judgement to answer under request_id.
+      #: (request_id: String, request: AssessmentRequest) -> Hash[String, untyped]
+      def assessment_request(request_id:, request:)
+        judgement("assessment", request_id, request.context, request.template)
+      end
+
+      # The correction request that follows an assessment with findings: one disposition for each, with a guide
+      # to every disposition's shape (#414). It says what was stored, so an assessment submitted twice plainly
+      # replaced nothing: in git nothing is, and outside git, where basis has no base commit, the open record
+      # keeps what the audit began from.
+      # placeholders is the text the template leaves in each field the agent writes (#725).
+      #: (request_id: String, principle_id: String, findings: Array[untyped], basis: Hash[String, untyped],
+      #|  placeholders: Hash[String, String]) -> Hash[String, untyped]
+      def correction_request(request_id:, principle_id:, findings:, basis:, placeholders:)
+        context = { "principle_id" => principle_id, "findings" => findings,
+                    "question" => Prompts.text("dispose-of-each-finding/fix-or-record-each-finding"),
+                    "answer_guide" => Prompts.data("dispose-of-each-finding/answer-guide") }
+        template = { "basis" => basis, "dispositions" => findings.map do |finding|
+          { "finding_id" => finding["id"], "action" => nil, "reason" => placeholders.fetch("reason"),
+            "changed_members" => [], "evidence" => [],
+            "reassessment" => placeholders.fetch("reassessment"), "recorded_at" => nil,
+            "waits_on" => nil }
+        end }
+        judgement("correction", request_id, context, template).merge("stored" => stored(basis["base_commit"]))
+      end
+
+      # A completed audit: its resolved and open findings, the files to commit and, in git, each changed
+      # member's commits since the base commit and the command that commits those files alone (#811), each prior
+      # finding's decision, and the next step. The command's subject states only what the audit did, which the
+      # agent rewords to its project's convention.
+      #: (principle_id: String, resolved: Array[untyped], open: Array[untyped], changes: AuditChanges,
+      #|  decisions: PriorFindingDecisionsResult) -> Hash[String, untyped]
+      def completion(principle_id:, resolved:, open:, changes:, decisions:)
+        changed = changes.to_h
+        commit = changes.commit("Audit #{principle_id}: #{resolved.length} resolved, #{open.length} open",
+                                @invocation.project)
+        output = { "status" => "audit_completed", "principle_id" => principle_id, "resolved_findings" => resolved,
+                   "open_findings" => open, "files_to_commit" => changes.files_to_commit,
+                   "limits" => Prompts.text("report-the-completed-audit/what-completion-means"),
+                   **changed.except("files_to_commit"), **commit.fields }
+        next_action = completed_next_action(principle_id, changes, commit)
+        decisions.added_to(output).merge("next_action" => next_action,
+                                         "full_record" => @invocation.in_project("show-audit", principle_id))
+      end
+
+      # The notice start-audit adds when the last audit's record is not committed.
+      #: (String) -> String
+      def uncommitted_record_notice(file)
+        "The last audit's record, #{file}, is not committed. Commit it, so the project keeps it."
+      end
+
+      private
+
+      # What submitting the assessment stored, and what submitting it again would do: in git, where the
+      # audit has a base commit, nothing; outside git, the open record.
+      #: (String?) -> String
+      def stored(base_commit)
+        again = "Submitting the same assessment again prints this same request"
+        unless base_commit
+          return "This audit's open record, listed under wrote when it was first written, keeps what the audit " \
+                 "began from. #{again} and leaves that record as it is."
+        end
+
+        "Nothing is stored yet: this request was computed from your assessment and the project. #{again} and " \
+          "replaces nothing; the audit record is written when the audit completes."
+      end
+
+      #: (String, String, Hash[String, untyped], Hash[String, untyped]) -> Hash[String, untyped]
+      def judgement(phase, request_id, context, template)
+        { "status" => "agent_judgement_required", "request_id" => request_id, "phase" => phase,
+          "context" => context, "response_template" => { "request_id" => request_id }.merge(template),
+          "limits" => Prompts.text("answer-any-judgement-request/what-a-self-audit-cannot-show") }
+      end
+
+      #: (Hash[String, untyped]) -> Hash[String, untyped]
+      def request(output)
+        submit = @invocation.submit_answer(output.fetch("request_id"))
+        output.merge("project" => @invocation.project, "answer_with" => submit)
+      end
+
+      # A completed audit's next step, from what it changed and how to commit it.
+      #: (String, AuditChanges, AuditCommit | AuditCommit::ByHand) -> String
+      def completed_next_action(id, changes, commit)
+        "#{commit.next_step} report the outcome to the project's owner.\n" \
+          "#{others_changed(changes.other_changed)}" \
+          "After members change, audit this principle again: #{@invocation.in_project("start-audit", id)}"
+      end
+
+      # The other principles whose members this audit's fixes changed, each to re-audit, or one member's edit
+      # to acknowledge; the agent judges which (#410). Nothing when there are none.
+      #: (Array[PrincipleWithChangedMembers]) -> String
+      def others_changed(others)
+        return "" if others.empty?
+
+        commands = others.map { |each| "#{@invocation.in_project("start-audit", each.principle_id)}\n" }
+        "This audit's fixes also changed or broke members of other principles, listed under " \
+          "other_principles_with_changed_members. Repair a broken one from show-principle's repair_with. To " \
+          "acknowledge one member's edit instead, add --member MEMBER to its audit. Re-audit each:\n#{commands.join}"
+      end
+    end
+  end
+end

data/lib/principles/views/candidate_files_result.rb

@@ -0,0 +1,95 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "invocation"
+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-candidate-files' result: the files that look like agent guidance, and the question of which
+    # principle several of them reinforce, asked before anything is mapped.
+    class CandidateFilesResult
+      # What the search for candidates found, as plain values: the inventory, the files git does not track, nil
+      # outside git, where nothing checked them (#386), and the lists to ask the owner about, each with the paths to
+      # name in it (#405, #412).
+      class Found
+        #: Hash[String, Array[String]]
+        attr_reader :owner_asks
+
+        #: (inventory: Hash[String, untyped], untracked: Array[String]?,
+        #|  owner_asks: Hash[String, Array[String]]) -> void
+        def initialize(inventory:, untracked:, owner_asks:)
+          @inventory = inventory
+          @untracked = untracked
+          @owner_asks = owner_asks
+          freeze
+        end
+
+        # The inventory as printed: each file by path, size and link, where the inventory looks, and untracked only
+        # in git.
+        #: () -> Hash[String, untyped]
+        def listed
+          files = @inventory.fetch("files").map { |file| file.slice("path", "characters", "symlink_to") }
+          listed = @inventory.merge("files" => files,
+                                    "scope" => Prompts.text("find-a-principle-to-map/where-the-inventory-looks"))
+          @untracked ? listed.merge("untracked" => @untracked) : listed
+        end
+      end
+
+      # The placeholders the printed create-principle command leaves for the agent to fill.
+      CREATE_PRINCIPLE_USAGE = "ID --description \"What the principle is and why it matters\""
+
+      #: (Invocation) -> void
+      def initialize(invocation)
+        @invocation = invocation
+        freeze
+      end
+
+      # The inventory, and the question of which principle to map, with one item for each list under found's owner_asks
+      # to ask the owner about. Until principles is set_up, next_action puts setting it up first.
+      #: (Found, existing_maps: Array[String], map_file: String, set_up: bool) -> Hash[String, untyped]
+      def question(found, existing_maps:, map_file:, set_up:)
+        { "status" => "question", "inventory" => found.listed, "existing_maps" => existing_maps,
+          "writes" => Prompts.text("find-a-principle-to-map/what-each-command-writes", map_file: map_file),
+          "question" => principle_question(found.owner_asks),
+          "answer_with" => @invocation.in_project("create-principle", usage: CREATE_PRINCIPLE_USAGE),
+          **(set_up ? {} : { "next_action" => set_up_first }) }
+      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
+
+      # Which principle to map, then one item per list to ask the owner about.
+      #: (Hash[String, Array[String]]) -> String
+      def principle_question(owner_asks)
+        asks = owner_asks.map { |key, paths| "- #{owner_ask(key, named: inline(paths))}" }
+        [Prompts.text("find-a-principle-to-map/choose-one-principle"),
+         *([Prompts.text("find-a-principle-to-map/ask-the-owner-before-mapping"), *asks].join("\n") if asks.any?)]
+          .join("\n\n")
+      end
+
+      # The paths an ask names after its list's name, each quoted, since a path may hold a comma; none, nothing.
+      #: (Array[String]) -> String
+      def inline(paths) = paths.empty? ? "" : " (#{paths.map { |path| "`#{path}`" }.join(", ")})"
+
+      # The ask about one inventory list, naming the paths after the list's name.
+      #: (String, named: String) -> String
+      def owner_ask(key, named:)
+        case key
+        when "possibly_test_data" then Prompts.text("find-a-principle-to-map/owner-ask-possibly-test-data", named:)
+        when "untracked" then Prompts.text("find-a-principle-to-map/owner-ask-untracked", named:)
+        when "ignored" then Prompts.text("find-a-principle-to-map/owner-ask-ignored", named:)
+        when "ignored_folders" then Prompts.text("find-a-principle-to-map/owner-ask-ignored-folders", named:)
+        else raise ArgumentError, "no owner ask for #{key}"
+        end
+      end
+    end
+  end
+end

data/lib/principles/views/check_result_template.rb

@@ -0,0 +1,75 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "prompts"
+
+module Principles
+  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
+  module Views
+    # The check_result a checked member's assessment template starts with: its command, and a not_run_reason
+    # that says what to do before replacing it. A check no audit has run, or one changed since, is reviewed
+    # before it runs (#227), and any hidden character it holds is named where that decision is made (#260).
+    class CheckResultTemplate
+      #: (String, Hash[String, untyped]?, ?Array[String]) -> void
+      def initialize(check, since_last_audit, hidden_characters = [])
+        @check = check
+        @since_last_audit = since_last_audit
+        @hidden_characters = hidden_characters
+        freeze
+      end
+
+      #: () -> Hash[String, untyped]
+      def to_h
+        { "command" => @check, "not_run_reason" => [hidden_characters, not_run_reason].compact.join(" ") }
+      end
+
+      private
+
+      #: () -> String?
+      def hidden_characters
+        return if @hidden_characters.empty?
+
+        Prompts.text("assess-every-member/have-hidden-characters-in-a-check-explained",
+                     characters: @hidden_characters.join("; "))
+      end
+
+      # What to do before replacing the field, then that a named check runs at every full audit, which holds for
+      # each status.
+      #: () -> String
+      def not_run_reason
+        [*steps, Prompts.text("assess-every-member/run-a-named-check-at-every-full-audit")].join(" ")
+      end
+
+      # An unchanged check is run and reported, keeping any line its last review rested on; a new or changed one is
+      # reviewed first, its review introduced by what it is, then run and reported with what that review rested on,
+      # as both ask the same way.
+      #: () -> Array[String]
+      def steps
+        case @since_last_audit&.fetch("status")
+        when "unchanged" then [Prompts.text("assess-every-member/run-the-check-then-report-it"), *kept_review]
+        when "changed"
+          [Prompts.text("assess-every-member/have-a-changed-check-reviewed-before-running-it"), run_reviewed]
+        else [Prompts.text("assess-every-member/have-a-new-check-reviewed-before-running-it"), run_reviewed]
+        end
+      end
+
+      # That a run keeps the line the last audit's review rested on, quoted with since when, unless a new one is
+      # given, so whether it still holds can be judged from the template (#849); a record from before D63 kept none,
+      # so there is nothing to say (#826).
+      #: () -> Array[String]
+      def kept_review
+        return [] unless @since_last_audit&.key?("review_basis")
+
+        [Prompts.text("assess-every-member/keep-the-last-review-basis-unless-you-give-a-new-one",
+                      since: @since_last_audit.fetch("review_basis_since"),
+                      basis: @since_last_audit.fetch("review_basis"))]
+      end
+
+      # Run a reviewed check, then report it with what its review rested on.
+      #: () -> String
+      def run_reviewed
+        Prompts.text("assess-every-member/run-the-reviewed-check-and-say-what-its-review-rested-on")
+      end
+    end
+  end
+end

data/lib/principles/views/diff_since_last_audit.rb

@@ -0,0 +1,29 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "shell_word"
+
+module Principles
+  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
+  module Views
+    # The command that shows the edits to a member's file since the last full audit's base commit, to the files as
+    # they are now, which the audit judges. Each word is quoted for the shell, and each path read by git as written,
+    # not as a pattern (#558). Renames are followed, so over a moved file's path then and now the diff shows the
+    # edit, not a new file (#557).
+    class DiffSinceLastAudit
+      # last_audited_commit is the last full audit's base commit; paths are the member's file then and now, once each.
+      #: (last_audited_commit: String, paths: Array[String]) -> void
+      def initialize(last_audited_commit:, paths:)
+        @last_audited_commit = last_audited_commit
+        @paths = paths
+        freeze
+      end
+
+      #: () -> String
+      def to_s
+        words = [@last_audited_commit, "--", *@paths].map { |word| ShellWord.new(word).to_s }
+        "git --literal-pathspecs diff -M #{words.join(" ")}"
+      end
+    end
+  end
+end

data/lib/principles/views/findings_result.rb

@@ -0,0 +1,45 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "invocation"
+
+module Principles
+  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
+  module Views
+    # list-open-findings' result: each finding the last completed audit of a principle deferred or accepted, what that
+    # covers, and what to do next (#292, D35).
+    class FindingsResult
+      SCOPE = "Each principle's last completed audit only, as .principles/audits/ID.json holds it. The next full " \
+              "audit decides each: one that still holds stays in the record, and one it closes is then only in git: " \
+              "git log -p -- .principles/audits/ID.json shows it."
+
+      NONE_OPEN = "No finding is deferred or accepted in the last completed audit of any principle listed."
+
+      #: (Invocation) -> void
+      def initialize(invocation)
+        @invocation = invocation
+        freeze
+      end
+
+      # findings holds each deferred or accepted finding, with its principle and action.
+      #: (Array[Hash[String, untyped]]) -> Hash[String, untyped]
+      def open(findings)
+        { "findings" => findings, "scope" => SCOPE, "next_action" => next_action(findings) }
+      end
+
+      private
+
+      #: (Array[Hash[String, untyped]]) -> String
+      def next_action(findings)
+        return NONE_OPEN if findings.empty?
+
+        audits = findings.map { |finding| finding.fetch("principle") }.uniq.map do |id|
+          @invocation.in_project("start-audit", id)
+        end
+        "Read each finding where its recorded_at points; null means it was never written up. A deferral's waits_on " \
+          "is whom it was asked to wait on, to decide what, as of waits_on_since: check that it still holds before " \
+          "chasing it. Its principle's next full audit asks you to decide each one:\n#{audits.join("\n")}"
+      end
+    end
+  end
+end

data/lib/principles/views/help.rb

@@ -0,0 +1,119 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "prompts"
+
+module Principles
+  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
+  module Views
+    # What --help prints: Markdown, because it is a prompt the agent reads before running a command (ticket 001
+    # D15). It is kept short, since every line lands in the agent's context. Refusal codes stay out: a refusal
+    # arrives with its own code and repair when it happens.
+    module Help
+      # What the page says after an agent's step: what the tool then checks, what it cannot check, and the
+      # usage of the command the agent runs next.
+      class Handover
+        #: String?
+        attr_reader :checks
+        #: String?
+        attr_reader :cannot_check
+        #: String?
+        attr_reader :then_run
+        # When the agent runs then_run, where it is the agent's to time; "Then" otherwise (#627).
+        #: String?
+        attr_reader :then_run_when
+
+        #: (?checks: String?, ?cannot_check: String?, ?then_run: String?, ?then_run_when: String?) -> void
+        def initialize(checks: nil, cannot_check: nil, then_run: nil, then_run_when: nil)
+          @checks = checks
+          @cannot_check = cannot_check
+          @then_run = then_run
+          @then_run_when = then_run_when
+          freeze
+        end
+
+        # The command to run next ends its line, with no backticks, so it pastes as it stands.
+        #: (String) -> Array[String]
+        def lines(executable)
+          [("The tool then checks that #{checks}" if checks), ("It cannot check #{cannot_check}" if cannot_check),
+           ("#{then_run_when ? "#{then_run_when}, run" : "Then run"}: #{executable} #{then_run}" if then_run)].compact
+        end
+      end
+
+      # One numbered step as the page prints it: whose step it is, what it does, what follows an agent's
+      # step, and each branch's condition with the number of the step it leads to.
+      class Step
+        #: bool
+        attr_reader :agent
+        #: String
+        attr_reader :does
+        #: Handover
+        attr_reader :handover
+        #: Array[[String, Integer]]
+        attr_reader :branches
+
+        #: (agent: bool, does: String, ?handover: Handover, ?branches: Array[[String, Integer]]) -> void
+        def initialize(agent:, does:, handover: Handover.new, branches: [])
+          @agent = agent
+          @does = does
+          @handover = handover
+          @branches = branches.freeze #: Array[[String, Integer]]
+          freeze
+        end
+      end
+
+      # The overview: what the tool is, each group's heading with its commands' usage and summary, and how
+      # the commands chain, with each command it prints started by the running executable.
+      class Overview
+        #: (version: String, groups: Array[[String, Array[[String, String]]]], executable: String) -> void
+        def initialize(version:, groups:, executable:)
+          @version = version
+          @groups = groups
+          @executable = executable
+          freeze
+        end
+
+        #: () -> String
+        def to_s
+          commands = @groups.map do |heading, entries|
+            "## #{heading}\n\n#{entries.map { |usage, summary| "- `#{usage}`: #{summary}" }.join("\n")}"
+          end
+          Prompts.markdown("learn-what-a-command-does/every-command-and-how-they-chain",
+                           version: @version, commands: commands.join("\n\n"), executable: @executable)
+        end
+      end
+
+      # One command's page, headed by the command as the running executable takes it: its prose prompt, what it
+      # writes, then its numbered steps.
+      class CommandPage
+        #: (usage: String, prompt: String, writes: String, steps: Array[Step], executable: String) -> void
+        def initialize(usage:, prompt:, writes:, steps:, executable:)
+          @usage = usage
+          @executable = executable
+          @prompt = prompt
+          @writes = writes
+          @steps = steps
+          freeze
+        end
+
+        #: () -> String
+        def to_s
+          numbered = @steps.each_with_index.map { |step, index| "#{index + 1}. #{step_text(step)}" }
+          ["# #{@executable} #{@usage}", Prompts.markdown(@prompt, executable: @executable), @writes, "## Steps",
+           numbered.join("\n"), "A step that fails prints a refusal with its code and a repair.",
+           "`--project PATH` is optional: it defaults to the current directory."].join("\n\n")
+        end
+
+        private
+
+        #: (Step) -> String
+        def step_text(step)
+          branches = step.branches.map { |condition, number| "If #{condition}: step #{number}." }
+          [step.agent ? "**You:** #{step.does}" : "The tool: #{step.does}", *step.handover.lines(@executable),
+           *branches]
+            .join("\n   ")
+        end
+      end
+    end
+  end
+end

data/lib/principles/views/invocation.rb

@@ -0,0 +1,66 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "shell_word"
+
+module Principles
+  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
+  module Views
+    # How the running tool is invoked, so a printed command names the executable and project that are
+    # running now. A controller builds it for each run; a view uses it to print commands, and it is never
+    # stored (alpha 008 friction 16).
+    class Invocation
+      #: String
+      attr_reader :executable
+      #: String
+      attr_reader :project
+
+      #: (executable: String, project: String) -> void
+      def initialize(executable:, project:)
+        @executable = executable
+        @project = project
+        freeze
+      end
+
+      # A command to run in this project, which it names right after the executable, as model repairs do (#580).
+      # Each value is shell-quoted, because ids, paths and headings come from project files that anyone may have
+      # written (#227). options are flags with their values, such as
+      # ["--starting-at", text], quoted the same way. usage is this tool's own placeholder text, such as
+      # "--section HEADING", left for the agent to fill and never quoted. When a value starts with "-", as a
+      # path may, every option comes first and "--" ends them, so the value is not read as an option (#240).
+      #: (String, *String, ?options: Array[String], ?usage: String?) -> String
+      def in_project(command, *values, options: [], usage: nil) = listed_in_project(command, values, options:, usage:)
+
+      # The command that answers request request_id in this project: from file, the --file value an answer was
+      # checked from, as given, or before there is one, from a FILE the agent names (#859).
+      #: (String, ?file: String?) -> String
+      def submit_answer(request_id, file: nil)
+        return in_project("submit-answer", request_id, usage: "--file FILE") unless file
+
+        in_project("submit-answer", request_id, options: ["--file", file])
+      end
+
+      # The same command, its values given as one list, as a refusal's repair command holds them (D56).
+      #: (String, Array[String], ?options: Array[String], ?usage: String?) -> String
+      def listed_in_project(command, values, options: [], usage: nil)
+        flags = options.map { |value| shell_word(value) }
+        words = values.map { |value| shell_word(value) }
+        if values.any? { |value| value.start_with?("-") }
+          return [@executable, project_option, command, *flags, usage, "--", *words].compact.join(" ")
+        end
+
+        [@executable, project_option, command, *words, *flags, usage].compact.join(" ")
+      end
+
+      #: () -> String
+      def project_option
+        "--project #{shell_word(@project)}"
+      end
+
+      private
+
+      #: (String) -> String
+      def shell_word(value) = ShellWord.new(value).to_s
+    end
+  end
+end

data/lib/principles/views/landed_since_base.rb

@@ -0,0 +1,27 @@
+# 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
+    # In git, what landed after a completed audit's base commit, as its result prints it: the commits since the base
+    # that touched each member the audit changed, by member id, and the base and HEAD when HEAD differs from the base
+    # and none touched one (#740). Outside git a completed audit has none, so it is given only in git.
+    class LandedSinceBase
+      #: (commits_by_member: Hash[String, Array[Hash[String, String]]], ?head_past_base: [String, String]?) -> void
+      def initialize(commits_by_member:, head_past_base: nil)
+        @commits_by_member = commits_by_member
+        @head_past_base = head_past_base
+        freeze
+      end
+
+      # The fields as printed: commits_since_base, and head_moved_past_base only when head_past_base is given.
+      #: () -> Hash[String, untyped]
+      def to_h
+        printed = { "commits_since_base" => @commits_by_member } #: Hash[String, untyped]
+        base, head = @head_past_base
+        @head_past_base ? printed.merge("head_moved_past_base" => { "base_commit" => base, "head" => head }) : printed
+      end
+    end
+  end
+end