principles 0.0.1

data/lib/principles/controllers/command.rb

@@ -0,0 +1,201 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "shellwords"
+require_relative "../error"
+require_relative "../models/answer_text"
+require_relative "../models/audit"
+require_relative "../models/carried_assessments"
+require_relative "../models/member"
+require_relative "../models/member_grounds"
+require_relative "../models/member_map_history"
+require_relative "../models/members_sharing_lines"
+require_relative "../models/project"
+require_relative "../models/record_judged_against"
+require_relative "../views/audit_result"
+require_relative "../views/lines_shared_with_member"
+require_relative "../views/map_result"
+require_relative "../views/member_repairs"
+require_relative "running_tool"
+
+module Principles
+  # Each runs one command: reads models, applies their rules and prints through a view.
+  # controllers/CLAUDE.md owns the boundary.
+  module Controllers
+    # What every command controller shares: the project and its models, the views that print, and the
+    # running executable, which only a controller knows. Reads change nothing on disk, map writes touch only
+    # the committed map, and audit writes only the committed audit record; lib/principles/CLAUDE.md owns the
+    # naming rule that keeps the three apart.
+    class Command
+      # The command as the agent can run it from a checkout or an installed gem: this Ruby and this checkout's
+      # executable, because this tool is not on the PATH there. The path is shell-quoted, since an install
+      # directory may hold a space. An entry point that is on the PATH names itself instead.
+      INVOCATION = "ruby #{Shellwords.escape(File.expand_path("../../../exe/principles", __dir__))}".freeze #: String
+
+      # tool is this run of the tool: the executable every printed command names, and the version running.
+      #: (Models::Project, tool: RunningTool) -> void
+      def initialize(project, tool:)
+        @project = project
+        @tool = tool
+        @member_maps = @project.member_maps #: Models::MemberMaps
+        @audit_records = @project.audit_records #: Models::AuditRecords
+        @history = @project.history #: Models::ProjectHistory
+      end
+
+      # Runs command; each controller runs its own group's commands and refuses the rest.
+      #: (String, String?, Hash[String, untyped]) -> untyped
+      def call(command, _id, _options)
+        naming_the_executable { unknown(command) }
+      end
+
+      private
+
+      # The history of principle_id's map, read through the collaborators this controller already holds.
+      #: (String) -> Models::MemberMapHistory
+      def map_history(principle_id)
+        Models::MemberMapHistory.new(id: principle_id, history: @history, member_maps: @member_maps)
+      end
+
+      # Saves the map, and nothing else, then prints the result the block builds from the map as written.
+      #: (Models::MemberMap) { (Views::PrintedPrinciple) -> Hash[String, untyped] } -> untyped
+      def write_map(map, &)
+        wrote = @member_maps.save(map)
+        yield(printed_principle(map)).merge("wrote" => [wrote])
+      end
+
+      # Runs the block, putting the running executable into any refusal a model raised, followed by this project,
+      # so a repair runs on the same project from anywhere, as answer_with does (#572). rerun, when given, prints the
+      # command running now with another member id, which a refusal naming a near miss leads its repair with (D56).
+      #: [T] (?rerun: (^(String) -> String)?) { () -> T } -> T
+      def naming_the_executable(rerun: nil, &)
+        yield
+      rescue Error => e
+        refusal = (rerun ? e.rerun_with_near_miss(&rerun) : e).printing_commands do |command|
+          invocation.listed_in_project(command.command, command.values, options: command.options, usage: command.usage)
+        end
+        raise with_member_repairs(refusal).naming("#{@tool.executable} #{invocation.project_option}")
+      end
+
+      # A broken_members refusal, with each member's own repair commands beside it as repair_with, since a
+      # model's repair can only name placeholders (#252). Any other refusal is returned as it is.
+      #: (Error) -> Error
+      def with_member_repairs(error)
+        return error unless error.payload["code"] == "broken_members"
+
+        repairs = Views::MemberRepairs.new(invocation)
+        members = error.payload.fetch("members").map do |entry|
+          repaired({ "principle" => error.payload["principle"] }.compact.merge(entry), repairs)
+        end
+        error.including("members" => members)
+      end
+
+      # entry with repair_with, when it names a member its map still lists.
+      #: (Hash[String, untyped], Views::MemberRepairs) -> Hash[String, untyped]
+      def repaired(entry, repairs)
+        principle = entry["principle"] or return entry
+        id = entry["id"] or return entry
+        fields = @member_maps.find(principle).member(id).merge(entry.slice("code")).merge("id" => id)
+        entry.merge("repair_with" => repairs.commands(principle, fields))
+      rescue Error
+        entry
+      end
+
+      #: (String) -> bot
+      def unknown(command)
+        raise Error.new("unknown_command", "Unknown command #{command}",
+                        "To see every command: #{@tool.executable} --help")
+      end
+
+      # The controller this one hands part of its command to, over the same project and naming the same executable.
+      #: [C < Command] (Class[C], **untyped) -> C
+      def handed(controller, **)
+        controller.new(@project, tool: @tool, **)
+      end
+
+      # The executable and project that printed commands name, built for each run and never stored.
+      #: () -> Views::Invocation
+      def invocation
+        Views::Invocation.new(executable: @tool.executable, project: @project.root)
+      end
+
+      #: () -> Views::AuditResult
+      def audit_result
+        Views::AuditResult.new(invocation)
+      end
+
+      #: () -> Views::MapResult
+      def map_result
+        Views::MapResult.new(invocation, in_git: @history.inside_git?)
+      end
+
+      #: (String?) -> String
+      def required_id(id)
+        unless id
+          raise Error.new("missing_id", "An id is required",
+                          "To see each command's examples: #{@tool.executable} --help")
+        end
+
+        id
+      end
+
+      #: (untyped, String) -> String
+      def text(value, field) = Models::AnswerText.new(value).required(field)
+
+      # The principle as the view prints it, with each member's id beside its locator.
+      #: (Models::MemberMap, ?members: Array[Hash[String, untyped]]) -> Views::PrintedPrinciple
+      def printed_principle(map, members: map.members_shown)
+        Views::PrintedPrinciple.new(id: map.id, file: @member_maps.file(map.id), description: map.description,
+                                    members: members, activation: map.activation)
+      end
+
+      # Each member's hash at base, or nil outside git.
+      #: (String?, Models::MemberMap) -> Hash[String, String]?
+      def committed(base, map) = base ? @history.hashes_at(base, map.members) : nil
+
+      # When each of the map's members loads, by id, which a full audit's request lists against the activation and
+      # show-principle prints, from the project's hooks as hooks read them.
+      #: (Models::MemberMap, ?Models::HookCommands) -> Hash[String, Models::MemberLoads]
+      def member_loads(map, hooks = @project.hook_commands) = @project.member_loads(map.members, hooks)
+
+      # The members a full audit lists to check against its activation, each with the decision its last completed
+      # audit, whose record is given or read now, accepted on the member's loading (#355, #502).
+      #: (Models::Audit, ?Models::AuditRecord?) -> Models::LoadsToCheck
+      def loads_to_check(audit, record = @audit_records.find(audit.id))
+        audit.loads_to_check(member_loads(audit.map), record)
+      end
+
+      # The principle's audit record as it stands, as an assessment answer is judged against it: the members whose
+      # loads it decides and the assessments it may carry forward, from one read of the record.
+      #: (Models::Audit) -> Models::RecordJudgedAgainst
+      def record_judged_against(audit)
+        record = @audit_records.find(audit.id)
+        Models::RecordJudgedAgainst.new(loads: loads_to_check(audit, record),
+                                        carried: carried_assessments(audit, record), record: record)
+      end
+
+      # What each member's assessment was judged on beside its text: its map entry and when it loads (D49).
+      #: (Models::Audit) -> Models::MemberGrounds
+      def grounds(audit) = audit.grounds(member_loads(audit.map))
+
+      # Which members' last assessments a full audit carries forward, from its record, given or read now, and the
+      # question it asks (D49).
+      #: (Models::Audit, ?Models::AuditRecord?) -> Models::CarriedAssessments
+      def carried_assessments(audit, record = @audit_records.find(audit.id))
+        audit.carried_assessments(record, grounds: grounds(audit), question: Views::AssessmentRequest.question)
+      end
+
+      # Where a member is in its file now, and the hash of what it says there.
+      #: (Models::Locator) -> Hash[String, untyped]
+      def snapshot(locator)
+        @project.locate(locator)
+      end
+
+      # The members sharing a line with member where it is now, in map and in the other maps, as add-member and
+      # show-principle print them (#383, #541).
+      #: (Models::Member, Models::MemberMap) -> Views::LinesSharedWithMember
+      def lines_shared(member, map)
+        Views::LinesSharedWithMember.new(**Models::MembersSharingLines.of(@project, member).facts_beside(map))
+      end
+    end
+  end
+end

data/lib/principles/controllers/correction.rb

@@ -0,0 +1,99 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "command"
+require_relative "../models/audit"
+require_relative "../models/correction_answer"
+require_relative "../models/declared_map_changes"
+require_relative "../models/request_id"
+require_relative "../views/prompts"
+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
+    # A full audit's correction, which submit-answer and show-answer-check hand over: this tool checks each
+    # disposition, and any members moved or whose role or check a fix changed, against the map and hashes the
+    # audit began from, and completes the audit (D28, D40).
+    class Correction < Command
+      # The result of answering a correction request, and the record change it makes, not yet written. A refused
+      # answer to a request printed before the record changed is refused as stale, so the agent starts again rather
+      # than repairing it (#671).
+      #: (Models::RequestId, untyped, Models::Audit) -> [untyped, Array[Models::AuditRecord]]
+      def answered(request_id, response, audit)
+        Models::CorrectionBasis.new(response.fetch("basis")).printed_after
+                               .refusing_stale_first(audit.id, @audit_records.find(audit.id)) do
+          judged_correction(request_id, response, audit)
+        end
+      end
+
+      # What each map entry a fix claims changed, from the map the audit the block gives started from and its map
+      # now; the audit is built and the base map read only when a fix claims one (#462).
+      #: (untyped) { () -> Models::Audit } -> Array[Hash[String, untyped]]
+      def map_entry_changes(response, &)
+        changes = Models::DeclaredMapChanges.declared_in(response)
+        changes.entry_changes do
+          audit = yield
+          [started_from(Models::CorrectionBasis.new(response.fetch("basis")), audit, changes), audit.map]
+        end
+      end
+
+      private
+
+      # The result of judging a correction answer: its basis, moves and dispositions checked, and the audit completed.
+      #: (Models::RequestId, untyped, Models::Audit) -> [untyped, Array[Models::AuditRecord]]
+      def judged_correction(request_id, response, audit)
+        basis = Models::CorrectionBasis.new(response.fetch("basis"))
+        changes = Models::DeclaredMapChanges.declared_in(response)
+        moves = Models::MemberMoves.new(response["moved_members"])
+        before = moves.hashes(confirmed_start(request_id, basis, audit, changes))
+        findings = moves.findings(basis.findings)
+        start = audit.resumed(basis, before, moves)
+        completion(changes, basis).completed(start, audit, dispositions(response, findings, start, audit), findings,
+                                             basis.prior_decided.moved(moves))
+      end
+
+      # The packaged answer guide, which the correction request prints, is the one owner of its samples, the text
+      # the agent saw, so its sample for each action is handed to the model, which refuses a field given back as
+      # its sample (#789). Should the tool be upgraded between request and answer, that answer is checked only
+      # against the new guide's samples.
+      #: (untyped, Array[untyped], Models::AuditStart, Models::Audit) -> Array[Models::Disposition]
+      def dispositions(response, findings, start, audit)
+        samples = Views::Prompts.data("dispose-of-each-finding/answer-guide").fetch("disposition")
+        Models::CorrectionAnswer.new(response, findings, samples:) { |locator| snapshot(locator) }
+                                .dispositions(changed: start.changed(now: audit.now))
+      end
+
+      # The map the audit began from, read from the base commit when the answer declares changes to the map.
+      #: (Models::CorrectionBasis, Models::Audit, Models::DeclaredMapChanges) -> Models::MemberMap
+      def started_from(basis, audit, changes)
+        audit.map_started_from(basis, changes, map_file: @member_maps.file(audit.id)) do |base|
+          committed_map(base, audit.id)
+        end
+      end
+
+      # The map id as the base commit holds it.
+      #: (String, String) -> Models::MemberMap
+      def committed_map(base, id)
+        map_history(id).map_at(base)
+      end
+
+      # Each member's hash when the audit began, checked against the request id: from the map it started from at the
+      # base commit in git, after the declared changes are checked against that map, or from the open record outside
+      # git.
+      #: (Models::RequestId, Models::CorrectionBasis, Models::Audit, Models::DeclaredMapChanges) -> Hash[String, String]
+      def confirmed_start(request_id, basis, audit, changes)
+        map = started_from(basis, audit, changes)
+        base = basis.base_commit
+        found = base ? committed(base, map) : @audit_records.find(audit.id)&.base_members
+        audit.confirmed_start(request_id, basis, found)
+      end
+
+      #: (Models::DeclaredMapChanges, Models::CorrectionBasis) -> AuditCompletion
+      def completion(map_changes, basis)
+        handed(AuditCompletion, map_changes: map_changes, replacing: basis.printed_after)
+      end
+    end
+  end
+end

data/lib/principles/controllers/help.rb

@@ -0,0 +1,107 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../models/command_steps"
+require_relative "command"
+require_relative "../views/help"
+require_relative "../views/workflow_diagram"
+
+module Principles
+  # Each runs one command: reads models, applies their rules and prints through a view.
+  # controllers/CLAUDE.md owns the boundary.
+  module Controllers
+    # --help: reads every command's steps through the model and hands the help view the plain values it prints.
+    class Help
+      # tool is the running tool. Only the overview reads its version, which the command line reads from the build
+      # or the checkout; its executable heads each command's page and starts the command it says to run next. The
+      # diagram names neither.
+      #: (tool: RunningTool, ?steps: Models::CommandSteps) -> void
+      def initialize(tool:, steps: Models::CommandSteps.load)
+        @tool = tool
+        @steps = steps
+      end
+
+      #: () -> String
+      def overview
+        groups = @steps.groups.map do |group|
+          entries = @steps.commands.select { |command| command.group == group.id }
+                          .map { |command| [command.usage, command.summary] }
+          [group.heading, entries]
+        end
+        Views::Help::Overview.new(version: @tool.version, groups: groups, executable: @tool.executable).to_s
+      end
+
+      # The page for the named command, or nil when there is no such command.
+      #: (String) -> String?
+      def command(name)
+        command = @steps.command(name)
+        return unless command
+
+        Views::Help::CommandPage.new(usage: command.usage, prompt: command.help, writes: @steps.writes(command),
+                                     steps: command.steps.map { |step| page_step(command, step) },
+                                     executable: @tool.executable).to_s
+      end
+
+      # The docs page drawing every command's steps and where each leads.
+      #: () -> String
+      def diagram
+        commands = @steps.commands.map do |command|
+          nodes = command.steps.map do |step|
+            Views::WorkflowDiagram::Node.new(key: key(command, step), label: step.id, agent: step.agent?)
+          end
+          [command.usage, nodes] #: [String, Array[Views::WorkflowDiagram::Node]]
+        end
+        Views::WorkflowDiagram.new(commands: commands, edges: @steps.commands.flat_map { |command| edges(command) })
+                              .to_s
+      end
+
+      private
+
+      # Each step's edges: to each branch with its condition, to the step after it, or to the first step of
+      # the command the agent answers with.
+      #: (Models::CommandSteps::Command) -> Array[Views::WorkflowDiagram::Edge]
+      def edges(command)
+        command.steps.flat_map do |step|
+          inside = command.successors(step).each_with_index.map do |successor, index|
+            Views::WorkflowDiagram::Edge.new(from: key(command, step), to: key(command, successor),
+                                             label: step.branches[index]&.condition)
+          end
+          [*inside, *handover(command, step)]
+        end
+      end
+
+      #: (Models::CommandSteps::Command, Models::CommandSteps::Step) -> Array[Views::WorkflowDiagram::Edge]
+      def handover(command, step)
+        target = step.handover.answer_with
+        answered = target && @steps.command(target)
+        return [] unless target && answered
+
+        [Views::WorkflowDiagram::Edge.new(from: key(command, step), to: key(answered, answered.steps.fetch(0)),
+                                          label: target, handover: true)]
+      end
+
+      # A step's Mermaid id: its command's and its own position, since step ids repeat across commands.
+      #: (Models::CommandSteps::Command, Models::CommandSteps::Step) -> String
+      def key(command, step)
+        "c#{@steps.commands.index(command)}s#{command.steps.index(step)}"
+      end
+
+      #: (Models::CommandSteps::Command, Models::CommandSteps::Step) -> Views::Help::Step
+      def page_step(command, step)
+        branches = step.branches.map do |branch|
+          [branch.condition, command.steps.index(command.find(branch.to)).to_i + 1] #: [String, Integer]
+        end
+        Views::Help::Step.new(agent: step.agent?, does: step.does, handover: page_handover(step.handover),
+                              branches: branches)
+      end
+
+      #: (Models::CommandSteps::Handover) -> Views::Help::Handover
+      def page_handover(handover)
+        target = handover.answer_with
+        Views::Help::Handover.new(checks: handover.checks, cannot_check: handover.cannot_check,
+                                  then_run: handover.answer_usage || (target && @steps.command(target)&.usage),
+                                  then_run_when: handover.answer_when)
+      end
+    end
+  end
+end

data/lib/principles/controllers/inventory.rb

@@ -0,0 +1,181 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "command"
+require_relative "members_a_commit_changed"
+require_relative "../models/member_problems"
+require_relative "../models/member_state"
+require_relative "../models/meta_principle"
+require_relative "../models/problem_report"
+require_relative "../views/problem_result"
+require_relative "../views/problem_lines"
+require_relative "../views/candidate_files_result"
+require_relative "../views/principle_read_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
+    # The reads that show what a project holds: its candidate instruction files, its principles, and each
+    # member and how fresh it is against the last audit. None changes anything on disk.
+    class Inventory < Command
+      #: (String, String?, Hash[String, untyped]) -> untyped
+      def call(command, id, options)
+        naming_the_executable do
+          case command
+          when "list-candidate-files" then list_candidate_files.merge("wrote" => [])
+          when "list-principles" then listing.merge("wrote" => [])
+          when "list-member-problems" then problems_printed(id, options)
+          when "show-principle" then members(required_id(id)).merge("wrote" => [])
+          else unknown(command)
+          end
+        end
+      end
+
+      # Each principle id names as list-principles lists it: its description and its members by freshness, or the
+      # refusal that kept its map from being read.
+      #: (Array[String]) -> Array[Hash[String, untyped]]
+      def rows(ids) = ids.map { entry(it) }
+
+      private
+
+      #: () -> untyped
+      def list_candidate_files
+        found = @project.candidate_files
+        listed = Views::CandidateFilesResult::Found.new(inventory: found.to_h, untracked: found.untracked,
+                                                        owner_asks: found.owner_asks)
+        Views::CandidateFilesResult.new(invocation).question(listed, existing_maps: @member_maps.ids,
+                                                                     map_file: @member_maps.file("ID"), set_up: set_up?)
+      end
+
+      #: (String) -> untyped
+      def members(id)
+        principle = @member_maps.find(id)
+        audit = @audit_records.find(id)
+        hooks = @project.hook_commands
+        members = shown_members(principle, audit, hooks)
+        shown = read_result.shown(printed_principle(principle, members: members),
+                                  broken: broken_ids(members), hook_settings_not_read: hooks.not_read,
+                                  loaded_files: @project.loaded_files(principle.members, hooks).to_h)
+        return shown unless audit
+
+        shown.merge("last_audit" => audit.last_audit(map_version: principle.version))
+      end
+
+      # Each member as show-principle prints it, with its loads read once for the whole map, from hooks.
+      #: (Models::MemberMap, Models::AuditRecord?, Models::HookCommands) -> Array[Hash[String, untyped]]
+      def shown_members(principle, audit, hooks)
+        loads = member_loads(principle, hooks)
+        principle.members_shown.map do |member|
+          shown_member(member, audit, loads.fetch(member.fetch("id"))).merge(shared(member, map: principle))
+        end
+      end
+
+      # What show-principle prints of one member: where it is now, its freshness and when its file loads (D38).
+      # The span sits beside the id too, as in add-member's and move-member's results (alpha friction).
+      #: (Hash[String, untyped], Models::AuditRecord?, Models::MemberLoads) -> Hash[String, untyped]
+      def shown_member(member, audit, loads)
+        now = fresh(member, audit)
+        member.merge(now.fetch("snapshot", {}).slice("first_line", "last_line"), now,
+                     "loads" => loads.to_h)
+      end
+
+      # The id of each shown member whose reference is broken, so an audit would refuse it, in the map's order.
+      #: (Array[Hash[String, untyped]]) -> Array[String]
+      def broken_ids(members)
+        members.select { |member| Models::MemberState.new(member.fetch("id"), member.fetch("freshness")).broken? }
+               .map { |member| member.fetch("id") }
+      end
+
+      # The members sharing a line with this one, in its map and in others, as add-member names them, so a member
+      # whose lines others hold too does not look as if its member_bytes were its alone (#541). A member this tool
+      # cannot find now shares nothing it can name.
+      #: (Hash[String, untyped], map: Models::MemberMap) -> Hash[String, untyped]
+      def shared(member, map:)
+        lines_shared(Models::Member.new(member), map).to_h
+      rescue Error
+        {}
+      end
+
+      # Where the member is now and whether it changed since the last audit assessed it.
+      #: (Hash[String, untyped], Models::AuditRecord?) -> Hash[String, untyped]
+      def fresh(member, audit)
+        @project.freshness(Models::Member.new(member).locator) do |sha|
+          audit ? audit.members.freshness(Models::Member.new(member).key, sha) : "unassessed"
+        end
+      end
+
+      #: () -> Views::PrincipleReadResult
+      def read_result
+        Views::PrincipleReadResult.new(invocation)
+      end
+
+      #: () -> untyped
+      def listing
+        read_result.listing(rows(@member_maps.ids), set_up: set_up?)
+      end
+
+      # Whether principles is set up, as MemberMaps decides it (D68, D75).
+      #: () -> bool
+      def set_up? = @member_maps.set_up?
+
+      # list-member-problems' JSON result, or with --short its lines for a trigger (#291), or with --hook-event the
+      # after-commit hook's JSON, which MembersACommitChanged prints (D73).
+      #: (String?, Hash[String, untyped]) -> untyped
+      def problems_printed(id, options)
+        if (event = options["hook_event"])
+          return handed(MembersACommitChanged, report: -> { checked_report(id) })
+                 .printed(after: options.fetch("commits_after"), event: event)
+        end
+
+        problems = Models::ProblemReport.new(problems_of(id), history: @history)
+        report = member_problems(problems)
+        return report.merge("wrote" => []) unless options["short"]
+
+        Views::ProblemLines.new(invocation).short(report, nothing_changed: Views::ProblemResult::NOTHING_CHANGED,
+                                                          assessed_change: problems.assessed_change?)
+      end
+
+      # list-member-problems' JSON result for map id, or every map, without the files it wrote.
+      #: (String?) -> Hash[String, untyped]
+      def checked_report(id) = member_problems(Models::ProblemReport.new(problems_of(id), history: @history))
+
+      # The result for problems, every member of map id or of every map that is broken or whose own text changed
+      # (#187).
+      #: (Models::ProblemReport) -> untyped
+      def member_problems(problems)
+        report = problems.checked do |map_id, member, baseline, now|
+          map_history(map_id).member_history(member, baseline: baseline, now: now)
+        end
+        Views::ProblemResult.new(invocation).checked(report, not_read: @project.unread_older_files,
+                                                             no_baseline_files: problems.files_to_commit(@member_maps),
+                                                             acknowledgeable: problems.acknowledgeable)
+      end
+
+      # Map id's members against their baselines, or every map's, listing a map it cannot read among them.
+      #: (String?) -> Array[Models::MemberProblems]
+      def problems_of(id)
+        return [Models::MemberProblems.for(@project, id)] if id
+
+        @member_maps.ids.map { Models::MemberProblems.for(@project, it, listing_all: true) }
+      end
+
+      # One map's row; a map this tool cannot read is listed with its refusal, so the others still show (D29).
+      #: (String) -> Hash[String, untyped]
+      def entry(id)
+        map = @member_maps.find(id)
+        row = { "id" => id, "description" => map.description, "members_by_freshness" => members_by_freshness(map) }
+        map.unstarted? ? row.merge(read_result.no_members(@member_maps.file(id))) : row
+      rescue Error => e
+        { "id" => id, "refusal" => e.payload }
+      end
+
+      # How many of map's members are in each freshness state, against its principle's last audit.
+      #: (Models::MemberMap) -> Hash[String, Integer]
+      def members_by_freshness(map)
+        audit = @audit_records.find(map.id)
+        map.members_shown.map { |member| fresh(member, audit).fetch("freshness") }.tally.sort.to_h
+      end
+    end
+  end
+end

data/lib/principles/controllers/mapping.rb

@@ -0,0 +1,56 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "command"
+require_relative "../models/activation"
+
+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 what a principle declares as a whole in its committed map: that it exists, its
+    # description, and when its work is in hand (D38). This tool asks, the agent answers, and this tool writes
+    # the map and nothing else. MemberEntries writes each member's entry.
+    class Mapping < Command
+      # Each command and the method that runs it.
+      COMMANDS = {
+        "create-principle" => :create_principle, "change-description" => :change_description,
+        "change-activation" => :change_activation
+      }.freeze #: Hash[String, Symbol]
+
+      #: (String, String?, Hash[String, untyped]) -> untyped
+      def call(command, id, options)
+        naming_the_executable do
+          method = COMMANDS[command] or unknown(command)
+          send(method, required_id(id), options)
+        end
+      end
+
+      private
+
+      #: (String, Hash[String, untyped]) -> untyped
+      def create_principle(id, options)
+        map = @member_maps.create(id) { text(options["description"], "--description") }
+        write_map(map) { |printed| map_result.created(printed) }
+      end
+
+      #: (String, Hash[String, untyped]) -> untyped
+      def change_description(id, options)
+        map = @member_maps.find(id).describing(text(options["description"], "--description"))
+        write_map(map) { |printed| map_result.description_changed(printed) }
+      end
+
+      # Records when the principle's work is in hand, as the agent judged it (D38).
+      #: (String, Hash[String, untyped]) -> untyped
+      def change_activation(id, options)
+        activation = Models::Activation.declared(when_files: options["when_files"],
+                                                 when_invoked: options["when_invoked"], always: options["always"])
+        map = @member_maps.find(id)
+        activated = map.activating(activation)
+        return map_result.activation_unchanged(printed_principle(map)).merge("wrote" => []) if activated.same_as?(map)
+
+        write_map(activated) { |printed| map_result.activation_changed(printed, lists: activation.full_audit_lists) }
+      end
+    end
+  end
+end