principles 0.0.1

data/lib/principles/data/bounded_file.rb

@@ -0,0 +1,45 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+
+module Principles
+  # Every file and process this tool reads or writes. data/CLAUDE.md owns the boundary.
+  module Data
+    # A file this tool reads whole, refused unless it is a regular file no larger than LIMIT. Without the check,
+    # a special file such as /dev/zero, or a file of gigabytes, would hang a run or exhaust its memory.
+    class BoundedFile
+      # Far above any instruction file, map, audit record or answer, and far below what exhausts memory.
+      LIMIT = 4 * 1024 * 1024 #: Integer
+
+      #: (String, ?shown_as: String) -> void
+      def initialize(path, shown_as: path)
+        @path = path
+        @shown_as = shown_as
+        freeze
+      end
+
+      # The file's text, read once it is known to be a regular file within LIMIT.
+      #: (?encoding: String) -> String
+      def read(encoding: "UTF-8")
+        unless File.file?(@path)
+          raise Error.new("not_a_file", "#{@shown_as} is not a regular file", "Name a regular file.", @shown_as)
+        end
+
+        refuse_larger(File.size(@path))
+
+        File.read(@path, encoding: encoding)
+      end
+
+      # Refuses bytes of text, such as stdin's, that are more than this tool reads from one file.
+      #: (Integer) -> void
+      def refuse_larger(bytes)
+        return if bytes <= LIMIT
+
+        raise Error.new("file_too_large", "#{@shown_as} holds #{bytes} bytes, more than the #{LIMIT} bytes " \
+                                          "read at most",
+                        "Name a smaller file, or map a smaller part of it.", @shown_as)
+      end
+    end
+  end
+end

data/lib/principles/data/candidate_files_found.rb

@@ -0,0 +1,105 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "find"
+require_relative "../error"
+require_relative "ignored_by_git"
+
+module Principles
+  # Every file and process this tool reads or writes. data/CLAUDE.md owns the boundary.
+  module Data
+    # The instruction files an agent host loads by convention, as list-candidate-files finds them in the project: each
+    # readable one with its length, those that cannot be read, those in a folder that often holds test data, and in
+    # git those git ignores.
+    class CandidateFilesFound
+      # Folders the inventory never enters: version control, this tool's own records, and installed packages.
+      PRUNED_FOLDERS = %w[.git .principles .memeplex .coord node_modules vendor .bundle].freeze
+
+      # The instruction files an agent host loads by convention. The inventory lists only these.
+      CANDIDATE_NAMES = %w[CLAUDE.md AGENTS.md].freeze
+      CANDIDATE_PATH = %r{(?:\A|/)\.claude/(?:rules/|skills/|agents/|settings[^/]*\.json\z)}
+
+      # Folder names that often hold test data shaped like guidance, such as a sample CLAUDE.md under
+      # spec/fixtures/. A name is a hint, not a fact: the agent decides, so these files stay listed and are
+      # named here with the folder that matched (alpha 009 friction 1).
+      TEST_DATA_FOLDER = %r{(?:\A|/)(fixtures?|examples?|samples?)/}
+
+      # One readable candidate: its path, its length in characters, and for a link the file it leads to (#695).
+      # The stand-in project lists by it too, so the two cannot disagree on the shape.
+      #: (String, text: String, leads_to: String) -> Hash[String, untyped]
+      def self.listed(path, text:, leads_to:)
+        entry = { "path" => path, "characters" => text.length }
+        leads_to == path ? entry : entry.merge("symlink_to" => leads_to)
+      end
+
+      #: (ProjectFiles) -> void
+      def initialize(files)
+        @files = files
+      end
+
+      #: () -> Hash[String, untyped]
+      def to_h
+        candidates = candidate_paths
+        ignored = IgnoredByGit.new(@files.root, candidates).facts
+        entries, skipped = readable(candidates - (ignored&.fetch("ignored") || []))
+        entries = entries.sort_by { |entry| entry.fetch("path") }
+        listed = { "files" => entries, "unreadable" => skipped,
+                   "possibly_test_data" => entries.filter_map { |entry| test_data_hint(entry.fetch("path")) } }
+        ignored ? listed.merge(ignored) : listed
+      end
+
+      private
+
+      # Each candidate's path relative to the root, in the order the walk finds them.
+      #: () -> Array[String]
+      def candidate_paths
+        paths = [] #: Array[String]
+        Find.find(@files.root) do |absolute|
+          if File.directory?(absolute)
+            Find.prune if PRUNED_FOLDERS.include?(File.basename(absolute)) || nested_repository?(absolute)
+            next
+          end
+          relative = absolute.delete_prefix("#{@files.root}/")
+          paths << relative if candidate?(relative)
+        end
+        paths
+      end
+
+      # A folder below the root holding its own .git, a worktree's file or a clone's folder, is another project,
+      # as git treats it (#376). The root may hold one too: this tool runs in a worktree.
+      #: (String) -> bool
+      def nested_repository?(absolute)
+        absolute != @files.root && File.exist?(File.join(absolute, ".git"))
+      end
+
+      # Each path with its length in characters, and the refusal for each that cannot be read.
+      #: (Array[String]) -> [Array[Hash[String, untyped]], Array[Hash[String, untyped]]]
+      def readable(paths)
+        entries = [] #: Array[Hash[String, untyped]]
+        skipped = [] #: Array[Hash[String, untyped]]
+        paths.each do |relative|
+          entries << listed(relative)
+        rescue Error => e
+          skipped << e.payload
+        end
+        [entries, skipped]
+      end
+
+      #: (String) -> Hash[String, untyped]
+      def listed(relative)
+        CandidateFilesFound.listed(relative, text: @files.read_text(relative), leads_to: @files.leads_to(relative))
+      end
+
+      #: (String) -> Hash[String, String]?
+      def test_data_hint(relative)
+        folder = relative[TEST_DATA_FOLDER, 1]
+        { "path" => relative, "folder" => folder } if folder
+      end
+
+      #: (String) -> bool
+      def candidate?(relative)
+        CANDIDATE_NAMES.include?(File.basename(relative)) || relative.match?(CANDIDATE_PATH)
+      end
+    end
+  end
+end

data/lib/principles/data/command-steps.json

@@ -0,0 +1,305 @@
+{
+  "groups": [
+    { "id": "read", "heading": "Read; these change nothing on disk",
+      "writes": "Writes nothing." },
+    { "id": "write-map", "heading": "Write the member map, `.principles/maps/ID.json`, which the project commits",
+      "writes": "Writes `.principles/maps/ID.json`; commit it as it changes. Never a member's file." },
+    { "id": "write-audit-record", "heading": "Audit; these write only the audit record, `.principles/audits/ID.json`, which the project commits",
+      "writes": "Writes `.principles/audits/ID.json`, listed under `wrote` when it does; commit it. Never the map or a member's file." }
+  ],
+  "refusal_groups": {
+    "any-command": ["file_too_large", "invalid_invocation", "invalid_shape", "filesystem_error", "unknown_command", "missing_id", "invalid_command_steps"],
+    "read-map": ["principles_folder_not_moved", "both_principles_folders", "symlinked_directory", "unknown_principle", "unparseable_map", "invalid_map", "newer_format", "duplicate_member"],
+    "read-audit": ["principles_folder_not_moved", "both_principles_folders", "symlinked_directory", "unparseable_audit", "invalid_audit_record"],
+    "locate-text": ["outside_project", "not_a_file", "unreadable_file", "invalid_encoding", "section_needs_markdown", "query_needs_frontmatter", "query_with_other_locators", "unsupported_query", "unsupported_frontmatter", "duplicate_frontmatter_key", "field_not_found", "section_not_found",
+                    "ambiguous_heading", "passage_not_found", "ambiguous_passage", "passage_end_not_found",
+                    "broken_members"]
+  },
+  "commands": [
+    {
+      "name": "list-candidate-files", "usage": "list-candidate-files", "group": "read", "options": [],
+      "summary": "Ask what in this project looks like a principle.",
+      "help": "learn-what-a-command-does/list-candidate-files",
+      "steps": [
+        { "id": "list-instruction-files", "actor": "cli",
+          "does": "Lists the instruction files agent hosts load by convention, naming git-ignored ones unread rather than listing them, each folder git ignores counted once, leaving out folders that hold their own git repository, and names any under a fixtures, examples or samples folder and, in git, any git does not track." },
+        { "id": "choose-one-principle", "actor": "agent",
+          "does": "Choose one principle several listed files reinforce. Decide whether each file named in possibly_test_data is guidance or a sample.",
+          "prompt": "find-a-principle-to-map/choose-one-principle",
+          "cannot_check": "whether a file is guidance or test data; ask the project's owner when you cannot tell.",
+          "answer_with": "create-principle" }
+      ]
+    },
+    {
+      "name": "list-principles", "usage": "list-principles", "group": "read", "options": [],
+      "summary": "Every mapped principle and whether its members are current.",
+      "help": "learn-what-a-command-does/list-principles",
+      "steps": [
+        { "id": "count-members-by-freshness", "actor": "cli",
+          "does": "Reads every map and the audit record of each, and counts its members as current, changed, unassessed, locator_lost or unavailable.",
+          "refuses_like": ["read-map", "read-audit"] }
+      ]
+    },
+    {
+      "name": "list-member-problems", "usage": "list-member-problems [ID] [--short | --commits-after COMMIT --hook-event EVENT]", "group": "read", "options": ["short", "commits-after", "hook-event"],
+      "summary": "Members whose reference is broken, or whose own text changed since their baseline.",
+      "help": "learn-what-a-command-does/list-member-problems",
+      "steps": [
+        { "id": "compare-members-with-their-baselines", "actor": "cli",
+          "does": "Finds each member of map ID, or of every map, and compares its own text with the last audit's hash for it, or else with its text at the commit that mapped it where it is. Refuses while any member cannot be found or read, or a map cannot be read, so a gate can stop on the exit status; otherwise lists each changed member with what it was compared with, and counts every state. With --short, prints one tab-separated line per changed member and exits 3 when any changed.",
+          "refuses": ["broken_members"], "refuses_like": ["read-map", "read-audit"] },
+        { "id": "repair-or-audit", "actor": "agent",
+          "does": "For a refusal, say whether each listed member moved or is gone, and repair it. For a changed member, audit its principle when the change was meant to alter the principle.",
+          "cannot_check": "whether a change alters what a member means; this tool compares text, not meaning.",
+          "answer_with": "move-member" }
+      ]
+    },
+    {
+      "name": "show-principle", "usage": "show-principle ID", "group": "read", "options": [],
+      "summary": "Each member, where it is and whether it changed.",
+      "help": "learn-what-a-command-does/show-principle",
+      "steps": [
+        { "id": "compare-members-with-last-audit", "actor": "cli",
+          "does": "Compares each member's text with the audit record: current, changed, unassessed, locator_lost when its passage no longer matches, or unavailable. Adds last_audit: its status, time and commit, and whether the map changed since.",
+          "refuses_like": ["read-map", "read-audit"] }
+      ]
+    },
+    {
+      "name": "show-audit", "usage": "show-audit ID", "group": "read", "options": [],
+      "summary": "The record of a principle's last audit.",
+      "help": "learn-what-a-command-does/show-audit",
+      "steps": [
+        { "id": "show-record", "actor": "cli",
+          "does": "Prints the audit record: its status, base commit, each member's hash and each finding's members and disposition.",
+          "refuses": ["unknown_principle", "unknown_audit"], "refuses_like": ["read-audit"] }
+      ]
+    },
+    {
+      "name": "list-open-findings", "usage": "list-open-findings [ID] [--short [--session-start SOURCE]]", "group": "read", "options": ["short", "session-start"],
+      "summary": "The findings the last audit of each principle deferred or accepted, and where each is written up.",
+      "help": "learn-what-a-command-does/list-open-findings",
+      "steps": [
+        { "id": "read-open-findings", "actor": "cli",
+          "does": "Reads the last audit record of principle ID, or of every principle, and lists each deferred or accepted finding with its action, its members, its recorded_at pointer and when the audit was made. Says that an earlier audit's open findings are only in git. With --short, prints one line saying how many are open, how long the oldest has waited and what it waits on, and nothing when none is open; --session-start clear or compact words it for a context just cleared or compacted.",
+          "refuses_like": ["read-map", "read-audit"] },
+        { "id": "follow-up-each-finding", "actor": "agent",
+          "does": "Read each finding where its recorded_at points, and decide each one at its principle's next full audit.",
+          "cannot_check": "whether a deferred or accepted finding still holds; this tool keeps only its members and action.",
+          "answer_with": "start-audit" }
+      ]
+    },
+    {
+      "name": "show-answer-check", "usage": "show-answer-check REQUEST --file FILE|-", "group": "read", "options": ["file"],
+      "summary": "Check an answer without submitting it.",
+      "help": "learn-what-a-command-does/show-answer-check",
+      "steps": [
+        { "id": "check-without-writing", "actor": "cli",
+          "does": "Runs every check submit-answer would and prints the same refusal, or names the files submitting would write. Writes nothing.",
+          "refuses": ["unparseable_json", "unreadable_file", "request_mismatch", "unknown_request", "stale_request", "stale_map", "undeclared_move", "moves_need_git", "map_entries_need_git",
+                      "incomplete_coverage", "invalid_delivery", "observation_repeats_last_audit", "invalid_check_result", "invalid_answer", "unknown_member", "duplicate_finding",
+                      "incomplete_dispositions", "invalid_disposition", "claimed_change_missing", "unassessed_changes"],
+          "refuses_like": ["read-map", "read-audit", "locate-text"] },
+        { "id": "submit-the-checked-answer", "actor": "agent",
+          "does": "Fix what a refusal names and check again, or submit the answer unchanged.",
+          "answer_with": "submit-answer" }
+      ]
+    },
+    {
+      "name": "show-meta-principle-passage", "usage": "show-meta-principle-passage", "group": "read", "options": [],
+      "summary": "Set principles up: propose the passage that keeps the others held between audits, and the add-member that maps it.",
+      "help": "learn-what-a-command-does/show-meta-principle-passage",
+      "steps": [
+        { "id": "propose-meta-principle-passage", "actor": "cli",
+          "does": "Writes nothing. Shows the sticking-to-your-principles map that the printed add-member creates, its description and an activation for all work, or, where that map is already there, shows it and names its members already in an entry file; says which of CLAUDE.md and AGENTS.md exist and whether one links the other, and proposes the passage each would take, with its size.",
+          "refuses_like": ["read-map"] },
+        { "id": "place-the-passage", "actor": "agent",
+          "does": "With no member mapped, show the user the passage, agree where it goes, write it there, and map it as the principle's member, or map another file or setting that keeps the principles held, such as a timer. With a member mapped, agree with the user which step each member lacks, and add any that is missing.",
+          "cannot_check": "where the passage belongs, or whether a passage or member already in the project does its job; agree that with the user.",
+          "answer_with": "add-member" }
+      ]
+    },
+    {
+      "name": "create-principle", "usage": "create-principle ID --description TEXT", "group": "write-map", "options": ["description"],
+      "summary": "Map a new principle and say what it is.",
+      "help": "learn-what-a-command-does/create-principle",
+      "steps": [
+        { "id": "write-new-map", "actor": "cli",
+          "does": "Checks that ID is lower-kebab-case, not yet mapped and not sticking-to-your-principles, which setup starts, then writes a map with the description and no members.",
+          "refuses": ["invalid_id", "principle_exists", "meta_principle_id", "invalid_answer"] },
+        { "id": "choose-members", "actor": "agent",
+          "does": "Choose the files, sections or passages that reinforce the principle, and the part each plays.",
+          "cannot_check": "whether the members you choose are the right ones.",
+          "answer_with": "add-member" }
+      ]
+    },
+    {
+      "name": "change-description", "usage": "change-description ID --description TEXT", "group": "write-map", "options": ["description"],
+      "summary": "Reword a mapped principle.",
+      "help": "learn-what-a-command-does/change-description",
+      "steps": [
+        { "id": "write-description", "actor": "cli", "does": "Replaces the map's description.",
+          "refuses": ["invalid_answer"], "refuses_like": ["read-map"] }
+      ]
+    },
+    {
+      "name": "change-activation", "usage": "change-activation ID (--when-files GLOB [--when-files GLOB ...] | --when-invoked | --always)", "group": "write-map", "options": ["when-files", "when-invoked", "always"],
+      "summary": "Record when a principle's work is in hand.",
+      "help": "learn-what-a-command-does/change-activation",
+      "steps": [
+        { "id": "write-activation", "actor": "cli",
+          "does": "Checks that exactly one form is given and no glob is empty, then replaces the map's activation.",
+          "refuses": ["invalid_activation", "invalid_answer"], "refuses_like": ["read-map"] }
+      ]
+    },
+    {
+      "name": "add-member", "usage": "add-member ID PATH [--section HEADING] [--starting-at TEXT [--ending-at TEXT]] [--query QUERY] --role ROLE [--check COMMAND]", "group": "write-map", "options": ["section", "starting-at", "ending-at", "query", "role", "check"],
+      "summary": "Add a file, a Markdown section or a passage.",
+      "help": "learn-what-a-command-does/add-member",
+      "steps": [
+        { "id": "locate-new-member", "actor": "cli",
+          "does": "Finds the member's text, so a locator that matches nothing is refused now rather than at the audit.",
+          "refuses": ["invalid_answer", "ending_without_start"], "refuses_like": ["read-map", "locate-text"] },
+        { "id": "write-member", "actor": "cli",
+          "does": "Refuses a member already in the map, then adds it with its role; the first member of sticking-to-your-principles creates its map.",
+          "refuses": ["member_exists"] },
+        { "id": "add-next-or-audit", "actor": "agent",
+          "does": "Add the next member the same way. Once the map lists every member, commit it: in git, that commit is the members' baseline until their first full audit, which judges them and may come later; outside git, the first full audit gives them one.",
+          "answer_with": "start-audit", "answer_usage": "start-audit ID",
+          "answer_when": "When you choose to start the first full audit" }
+      ]
+    },
+    {
+      "name": "move-member", "usage": "move-member ID MEMBER [--path PATH] [--section HEADING] [--starting-at TEXT [--ending-at TEXT]] [--query QUERY]", "group": "write-map", "options": ["path", "section", "starting-at", "ending-at", "query"],
+      "summary": "Point a member at a new place in its file, or in another file: the one its file was renamed to, or one its text moved into.",
+      "help": "learn-what-a-command-does/move-member",
+      "steps": [
+        { "id": "find-member", "actor": "cli", "does": "Finds MEMBER in the map.",
+          "refuses": ["unknown_member", "invalid_answer"], "refuses_like": ["read-map"] },
+        { "id": "locate-new-place", "actor": "cli",
+          "does": "Finds the text at the new locator, in PATH when --path names the file the member's file was renamed to or its text moved into, or else in its own file. The locator replaces the old one whole, and the member keeps its role and the key its audit is filed under.",
+          "refuses": ["invalid_answer", "ending_without_start", "member_exists"], "refuses_like": ["locate-text"] }
+      ]
+    },
+    {
+      "name": "change-member-role", "usage": "change-member-role ID MEMBER --role ROLE", "group": "write-map", "options": ["role"],
+      "summary": "Reword a member's role.",
+      "help": "learn-what-a-command-does/change-member-role",
+      "steps": [
+        { "id": "write-role", "actor": "cli", "does": "Finds MEMBER in the map and replaces its role.",
+          "refuses": ["unknown_member", "invalid_answer"], "refuses_like": ["read-map"] }
+      ]
+    },
+    {
+      "name": "change-member-check", "usage": "change-member-check ID MEMBER --check COMMAND", "group": "write-map", "options": ["check"],
+      "summary": "Name the command that enforces a member, which each audit asks you to run.",
+      "help": "learn-what-a-command-does/change-member-check",
+      "steps": [
+        { "id": "write-check", "actor": "cli", "does": "Finds MEMBER in the map and stores COMMAND as its check. This tool never runs it.",
+          "refuses": ["unknown_member", "invalid_answer"], "refuses_like": ["read-map"] }
+      ]
+    },
+    {
+      "name": "remove-member-check", "usage": "remove-member-check ID MEMBER", "group": "write-map", "options": [],
+      "summary": "Stop naming a check for a member.",
+      "help": "learn-what-a-command-does/remove-member-check",
+      "steps": [
+        { "id": "drop-check", "actor": "cli", "does": "Finds MEMBER in the map and removes its check, refusing a member that has none.",
+          "refuses": ["unknown_member", "no_check", "invalid_answer"], "refuses_like": ["read-map"] }
+      ]
+    },
+    {
+      "name": "remove-member", "usage": "remove-member ID MEMBER", "group": "write-map", "options": [],
+      "summary": "Take a member out of the map.",
+      "help": "learn-what-a-command-does/remove-member",
+      "steps": [
+        { "id": "drop-member", "actor": "cli", "does": "Finds MEMBER in the map and removes it.",
+          "refuses": ["unknown_member", "invalid_answer"], "refuses_like": ["read-map"] }
+      ]
+    },
+    {
+      "name": "start-audit", "usage": "start-audit ID [--member MEMBER | --write-ups]", "group": "write-audit-record", "options": ["member", "write-ups"],
+      "summary": "Ask for an assessment of every member and the set.",
+      "help": "learn-what-a-command-does/start-audit",
+      "steps": [
+        { "id": "snapshot-members", "actor": "cli",
+          "does": "Refuses an empty map or, in git, an uncommitted map or member file; bases the audit on HEAD. Writes nothing.",
+          "refuses": ["map_has_no_members", "uncommitted_files"], "refuses_like": ["read-map", "locate-text"],
+          "next": [{ "to": "assess-every-member", "when": "you passed neither --member nor --write-ups" },
+                   { "to": "start-acknowledgement", "when": "you passed --member" },
+                   { "to": "start-repointing", "when": "you passed --write-ups" }] },
+        { "id": "assess-every-member", "actor": "agent",
+          "does": "Assess each member not carried forward, and any carried one whose sighting is too old to stand behind, the set as a whole and one decision you made recently under it, with a finding for each problem. Decide each prior finding and member to check against the activation the request lists. The request says how to answer each part.",
+          "prompt": "assess-every-member/assess-each-member-and-the-set",
+          "checks": "every member is assessed or carried forward once, a marker only where the request carries the member, and each piece of evidence resolves to project text that has not changed since the request.",
+          "cannot_check": "whether your assessment is true, a member reached your context, or your findings are the right ones.",
+          "answer_with": "submit-answer" },
+        { "id": "start-acknowledgement", "actor": "cli",
+          "does": "With --member, starts a one-member audit instead: in git, for a member the last completed audit assessed whose text changed since, names its baseline commit and the change to read. Writes nothing.",
+          "refuses": ["cannot_acknowledge"] },
+        { "id": "judge-the-change", "actor": "agent",
+          "does": "Say whether the change keeps the member's principle, with a one-line reason and a quote from then and now.",
+          "prompt": "acknowledge-a-change/say-whether-the-change-keeps-the-meaning",
+          "checks": "the meaning is said to be kept, the reason is one line, and both quotes are the member's.",
+          "cannot_check": "whether the change keeps the meaning, or whether you read it.",
+          "answer_with": "submit-answer" },
+        { "id": "start-repointing", "actor": "cli",
+          "does": "With --write-ups, lists instead each finding the last completed audit left open, its recorded_at and what list-open-findings says of it, and asks where you found each moved write-up, which it cannot check. Writes nothing.",
+          "refuses": ["cannot_repoint"] }
+      ]
+    },
+    {
+      "name": "submit-answer", "usage": "submit-answer REQUEST --file FILE|-", "group": "write-audit-record", "options": ["file"],
+      "summary": "Give the answer a request asked for.",
+      "help": "learn-what-a-command-does/submit-answer",
+      "steps": [
+        { "id": "match-request", "actor": "cli",
+          "does": "Reads FILE, or stdin for -, and checks that its request_id is REQUEST, an id this tool prints.",
+          "refuses": ["unparseable_json", "unreadable_file", "request_mismatch", "unknown_request"],
+          "next": [{ "to": "acknowledge-the-change", "when": "the request was a one-member audit" },
+                   { "to": "record-the-repoints", "when": "the request was a repoint of write-ups" },
+                   { "to": "recheck-members", "when": "the request was an assessment or a correction" }] },
+        { "id": "acknowledge-the-change", "actor": "cli",
+          "does": "For a one-member audit, checks that the answer says the meaning is kept, with a one-line reason and a quote of the member then and now, then moves its hash in the audit record and keeps the acknowledgement beside it.",
+          "refuses": ["stale_request", "cannot_acknowledge", "quote_not_found"] },
+        { "id": "commit-the-acknowledgement", "actor": "agent",
+          "does": "Commit the audit record, then check that list-member-problems --short no longer reports the member.",
+          "cannot_check": "that you committed, or that the change keeps the meaning.",
+          "answer_with": "list-member-problems" },
+        { "id": "record-the-repoints", "actor": "cli",
+          "does": "Points each finding at its new recorded_at, once found, in the last completed record, keeping the old one, when and why; names other principles' lost write-ups; refuses once that record changed, unless it writes nothing.",
+          "refuses": ["cannot_repoint", "audit_completed_since_request", "unknown_finding", "duplicate_finding", "invalid_answer", "uncommitted_files"], "refuses_like": ["locate-text"] },
+        { "id": "commit-the-repoint", "actor": "agent",
+          "does": "Commit the audit record, then check that list-open-findings --short no longer names those write-ups.",
+          "cannot_check": "that you committed, or that the new places hold the write-ups.",
+          "answer_with": "list-open-findings" },
+        { "id": "recheck-members", "actor": "cli",
+          "does": "Re-reads the map and every member's text, and the record outside git.",
+          "refuses_like": ["read-map", "read-audit", "locate-text"],
+          "next": [{ "to": "check-assessment", "when": "the request was an assessment" },
+                   { "to": "check-dispositions", "when": "the request was a correction" }] },
+        { "id": "check-assessment", "actor": "cli",
+          "does": "Refuses an answer when the map, a member, its base commit or the listed loads changed since the request. Then checks every member is covered once, every field and piece of evidence resolves, and each listed loading and prior finding is decided once. Prints a correction request for findings; outside git, writes the record as open.",
+          "refuses": ["stale_request", "audit_completed_since_request", "incomplete_prior_findings", "invalid_decision", "raised_in_not_found", "raised_in_unreadable", "raised_in_lacks_finding", "raised_in_time_differs", "first_raised_not_earlier", "incomplete_loading_decisions", "invalid_loading_decision", "incomplete_coverage", "invalid_delivery", "observation_repeats_last_audit", "invalid_check_result", "invalid_answer", "unknown_member", "duplicate_finding"],
+          "refuses_like": ["locate-text"],
+          "next": [{ "to": "complete-audit", "when": "there are no findings" },
+                   { "to": "dispose-of-each-finding", "when": "there are findings" }] },
+        { "id": "dispose-of-each-finding", "actor": "agent",
+          "does": "Fix each finding and reassess what you changed, or record why it waits: deferred, accepted or disagreed.",
+          "prompt": "dispose-of-each-finding/fix-or-record-each-finding",
+          "checks": "each finding has one disposition, and each fixed finding changed the members it names.",
+          "cannot_check": "whether a fix is right or a deferral justified.",
+          "answer_with": "submit-answer" },
+        { "id": "check-dispositions", "actor": "cli",
+          "does": "Refuses a correction when the map changed since the assessment beyond moved_members. Then checks one disposition per finding, that only fixed findings' members changed since the base, and that each recorded_at resolves.",
+          "refuses": ["stale_map", "undeclared_move", "moves_need_git", "map_entries_need_git", "stale_request", "audit_completed_since_request", "incomplete_dispositions", "invalid_disposition", "invalid_answer", "claimed_change_missing", "unassessed_changes"],
+          "refuses_like": ["locate-text"] },
+        { "id": "complete-audit", "actor": "cli",
+          "does": "Writes the record unless it already says the same, and prints the open and resolved findings and the files to commit, in git only those differing from HEAD, with the commits since the base touching each changed member.",
+          "prompt": "report-the-completed-audit/what-completion-means" },
+        { "id": "report-the-outcome", "actor": "agent",
+          "does": "Commit the record with your fixes, and report the outcome, open findings included, to the project's owner.",
+          "cannot_check": "that the owner was told, or that you committed." }
+      ]
+    }
+  ]
+}

data/lib/principles/data/command_steps_file.rb

@@ -0,0 +1,50 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "json"
+require_relative "../error"
+
+module Principles
+  # Every file and process this tool reads or writes. data/CLAUDE.md owns the boundary.
+  module Data
+    # command-steps.json, which ships in the gem beside this file and lists every command's steps.
+    #
+    # A run reads it without its schema. The file is part of the gem, and `rake ci` checks it against the
+    # schema before every commit (spec/unit/principles/data/command_steps_file_spec.rb). So --version and
+    # --help need nothing beyond the standard library, even on a Ruby where json_schemer is not installed.
+    class CommandStepsFile
+      PATH = File.join(__dir__, "command-steps.json").freeze #: String
+      SCHEMA = File.join(__dir__, "schemas", "command-steps.schema.json").freeze #: String
+
+      #: String
+      attr_reader :path
+
+      # path defaults to the file shipped in the gem; a spec passes a changed copy.
+      #: (?String) -> void
+      def initialize(path = PATH)
+        @path = path
+        freeze
+      end
+
+      #: () -> untyped
+      def read
+        JSON.parse(File.read(path))
+      rescue JSON::ParserError => e
+        raise Error.new("invalid_command_steps", e.message, "Repair the JSON of this file.", path)
+      end
+
+      # The file's content once it passes its schema, or a refusal naming each failing field.
+      #: () -> untyped
+      def read_checked
+        require "json_schemer"
+        require "pathname"
+        data = read
+        errors = JSONSchemer.schema(Pathname.new(SCHEMA)).validate(data).map { |error| error.fetch("error") }
+        return data if errors.empty?
+
+        raise Error.new("invalid_command_steps", errors.join("; "),
+                        "Repair the file against schemas/command-steps.schema.json.", path)
+      end
+    end
+  end
+end

data/lib/principles/data/expected_type.rb

@@ -0,0 +1,71 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../prose_list"
+
+module Principles
+  # Every file and process this tool reads or writes. data/CLAUDE.md owns the boundary.
+  module Data
+    # The type one schema asks for, from its type keyword: whether a value has it, and how a refusal names it,
+    # with the keys an object takes, so an agent that sent another type learns the shape from the refusal (#737).
+    class ExpectedType
+      TYPES = {
+        "object" => Hash, "array" => Array, "string" => String, "integer" => Integer, "boolean" => [true, false],
+        "null" => NilClass
+      }.freeze #: Hash[String, untyped]
+      # This tool's own schema keyword: what a refusal of the value's type adds, such as when to point inside a
+      # file, which the keys alone do not say (#758), as {"keys", "says"}. The refusal says it after the required
+      # keys, in place of the optional keys it names, so it names each key once (#765).
+      ADVICE = "x-type-refusal-advice"
+
+      #: (Hash[String, untyped]) -> void
+      def initialize(schema)
+        advice = schema.fetch(ADVICE, {}) #: Hash[String, untyped]
+        @names = Array(schema["type"]) #: Array[String]
+        @required = schema.fetch("required", []) #: Array[String]
+        @optional = schema.fetch("properties", {}).keys - @required - advice.fetch("keys", []) #: Array[String]
+        @advice = advice["says"] #: String?
+        freeze
+      end
+
+      # Whether value has the type; a schema that names no type allows any.
+      #: (untyped) -> bool
+      def matches?(value)
+        @names.empty? || @names.any? do |name|
+          kind = TYPES.fetch(name)
+          kind.is_a?(Array) ? kind.include?(value) : value.is_a?(kind)
+        end
+      end
+
+      # The type as a refusal says it, such as "an object or null, with path and optionally heading", with any
+      # advice the schema gives for it.
+      #: () -> String
+      def to_s
+        @names.map { |name| %w[object array integer].include?(name) ? "an #{name}" : "a #{name}" }
+              .join(" or ").sub("a null", "null") + keys
+      end
+
+      private
+
+      # The keys an object takes: its required ones, then the advice, then the others it may take.
+      #: () -> String
+      def keys
+        return any_of if @required.empty?
+
+        text = [", with #{ProseList.new(@required)}", *@advice].join(", ")
+        return text if @optional.empty?
+
+        "#{text}#{"," if @advice} and optionally #{optional}"
+      end
+
+      # The keys an object that requires none may take, then the advice; nothing when there are neither.
+      #: () -> String
+      def any_of
+        [*("with any of #{optional}" unless @optional.empty?), *@advice].sum("") { |part| ", #{part}" }
+      end
+
+      #: () -> ProseList
+      def optional = ProseList.new(@optional, conjunction: "or")
+    end
+  end
+end

data/lib/principles/data/ignored_by_git.rb

@@ -0,0 +1,54 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "open3"
+
+module Principles
+  # Every file and process this tool reads or writes. data/CLAUDE.md owns the boundary.
+  module Data
+    # What git ignores among a project's candidate files: the files, by every ignore file git reads, a global one
+    # included, so build output and personal settings are named rather than read (#397), and each folder above
+    # them that git ignores, so a build folder's many copies can be counted once (#406).
+    class IgnoredByGit
+      #: (String, Array[String]) -> void
+      def initialize(root, candidates)
+        @root = root
+        @candidates = candidates
+        freeze
+      end
+
+      # The ignored candidates and the ignored folders above them, or nil when git gave no answer to either
+      # question: outside a repository, and when git refuses one, as one of doubtful ownership. nil means not
+      # checked, not that nothing is ignored, so it must not become empty lists; and both or neither, since a
+      # folder list git did not give would make every file look ignored on its own.
+      #: () -> Hash[String, Array[String]]?
+      def facts
+        paths = asked(@candidates) or return nil
+        folders = paths.empty? ? [] : asked(ancestor_folders(paths))
+        { "ignored" => paths.sort, "ignored_ancestor_folders" => folders.sort } if folders
+      end
+
+      private
+
+      # Every folder above each path, as "a/" and "a/b/", once each: the trailing "/" lets git match a folder
+      # pattern such as build/.
+      #: (Array[String]) -> Array[String]
+      def ancestor_folders(paths)
+        paths.flat_map do |path|
+          folders = path.split("/").first(path.count("/"))
+          (1..folders.length).map { |depth| "#{folders.first(depth).join("/")}/" }
+        end.uniq
+      end
+
+      # The paths git ignores, or nil when it gave no answer.
+      #: (Array[String]) -> Array[String]?
+      def asked(paths)
+        output, _, status = Open3.capture3("git", "-C", @root, "check-ignore", "-z", "--stdin",
+                                           stdin_data: paths.map { |path| "#{path}\0" }.join)
+        output.split("\0") if status.exitstatus.to_i <= 1
+      rescue SystemCallError
+        nil
+      end
+    end
+  end
+end