principles 0.0.1

data/lib/principles/invocation_options.rb

@@ -0,0 +1,77 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "optparse"
+
+module Principles
+  # The options one invocation gives: each value or flag, and which the agent typed, which CommandLine checks
+  # against what its command takes.
+  class InvocationOptions
+    # The options that take a value; --help, -h and --version take none.
+    VALUE_OPTIONS = %w[project file description path section starting-at ending-at query role
+                       check member session-start commits-after hook-event].freeze #: Array[String]
+    # The options that take no value, as list-member-problems --short (#291).
+    FLAG_OPTIONS = %w[short when-invoked always write-ups].freeze #: Array[String]
+    # The options that may be given more than once, each value kept in order, as change-activation --when-files.
+    LIST_OPTIONS = %w[when-files].freeze #: Array[String]
+    # The words that name an option taking the next word as its value.
+    VALUE_WORDS = (VALUE_OPTIONS + LIST_OPTIONS).map { |name| "--#{name}" }.freeze #: Array[String]
+    # Every word the parser reads as an option, which an option taking a value refuses as its value (#750).
+    WORDS = [*VALUE_WORDS, *FLAG_OPTIONS.map { |name| "--#{name}" }, "--help", "-h",
+             "--version"].freeze #: Array[String]
+
+    # Whether word is the name of an option that takes the next word as its value.
+    #: (String) -> bool
+    def self.takes_a_value?(word) = VALUE_WORDS.include?(word)
+
+    #: () -> void
+    def initialize
+      @values = { "project" => Dir.pwd } #: Hash[String, untyped]
+      @given = [] #: Array[String]
+    end
+
+    # Takes the options out of words, leaving the command and its positional arguments; an option no command
+    # defines is refused with OptionParser::InvalidOption.
+    #: (Array[String]) -> void
+    def parse!(words)
+      parser.parse!(words)
+    end
+
+    # An option's value, or true for a flag that was given; its name is written with underscores.
+    #: (String) -> untyped
+    def value(name)
+      @values[name]
+    end
+
+    # Each option the agent typed, once, by its name on the command line.
+    #: () -> Array[String]
+    def given = @given.uniq
+
+    # Every option's value, under its name with underscores.
+    #: () -> Hash[String, untyped]
+    def to_h = @values.dup
+
+    private
+
+    # Records that the agent typed name, and keeps its value: appended for an option that may repeat, else set.
+    #: (String, untyped) -> void
+    def store(name, value)
+      @given << name
+      key = name.tr("-", "_")
+      @values[key] = LIST_OPTIONS.include?(name) ? [*@values[key], value] : value
+    end
+
+    # A parser that fills the options, and records each value or flag option the agent typed.
+    #: () -> OptionParser
+    def parser
+      OptionParser.new do |opts|
+        (VALUE_OPTIONS + FLAG_OPTIONS + LIST_OPTIONS).each do |name|
+          # A flag yields true; a value option yields its value.
+          opts.on(FLAG_OPTIONS.include?(name) ? "--#{name}" : "--#{name} VALUE") { |value| store(name, value) }
+        end
+        opts.on("--help", "-h") { @values["help"] = true }
+        opts.on("--version") { @values["version"] = true }
+      end
+    end
+  end
+end

data/lib/principles/models/accepted_loading.rb

@@ -0,0 +1,36 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "loading_facts"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # The decision a completed audit accepted on a member's loading, kept in the member's record entry with the
+    # member's text hash, as the next full audit shows it beside the member's row (#502 step 5). It changed since when
+    # what it weighed changed: when the member loads, or the member's own text. A file's size alone moves with every
+    # edit elsewhere in a shared file, so it does not count (second alpha user on 5bedec4, #515).
+    class AcceptedLoading
+      # entry is the member's record entry, holding loading_accepted and sha256.
+      #: (Hash[String, untyped]) -> void
+      def initialize(entry)
+        decision = entry.fetch("loading_accepted")
+        @reason = decision.fetch("reason") #: String
+        @loads = decision.fetch("loads") #: Hash[String, untyped]
+        @sha256 = entry.fetch("sha256") #: String
+        freeze
+      end
+
+      # The reason, and whether what the decision weighed changed since, given the member's loads and hash now; when
+      # it did, which of the two changed and the loads accepted, for the agent to see what moved.
+      #: (Hash[String, untyped], String?) -> Hash[String, untyped]
+      def last_accepted(loads_now, hash_now)
+        changed = [("loading" if LoadingFacts.new(@loads) != LoadingFacts.new(loads_now)),
+                   ("member_text" if @sha256 != hash_now)].compact
+        return { "reason" => @reason, "since_accepted" => "unchanged" } if changed.empty?
+
+        { "reason" => @reason, "since_accepted" => "changed", "changed" => changed, "loads" => @loads }
+      end
+    end
+  end
+end

data/lib/principles/models/acknowledgement.rb

@@ -0,0 +1,203 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "request_id"
+require_relative "audit_record"
+require_relative "member"
+require_relative "placement"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # A one-member audit (D33): the agent says a committed change to one member keeps its meaning, quoting a line
+    # from before and after it, so the record's baseline for that member moves on and --short stops repeating it.
+    # Refused outside git, for a member no completed audit assessed, and for an unchanged or checked member.
+    class Acknowledgement
+      # One side of the change a quote is checked against: the member's lines then, and when they read.
+      class SideOfTheChange
+        #: String
+        attr_reader :reads_at
+
+        #: (Array[String], String) -> void
+        def initialize(lines, reads_at)
+          @lines = lines.map(&:chomp) #: Array[String]
+          @reads_at = reads_at
+          freeze
+        end
+
+        #: (String) -> bool
+        def whole_line?(quote) = @lines.include?(quote)
+
+        #: (String) -> bool
+        def holds?(text) = @lines.any? { |line| line.include?(text) }
+      end
+
+      PHASE = "acknowledgement"
+      # The fewest characters a quoted fragment of a line may have, so it shows which edit was read (#352).
+      FRAGMENT_LENGTH = 30
+
+      # before holds the member's lines at its baseline commit, now its lines and hash at base, HEAD.
+      #: (principle_id: String, member: Member, record: AuditRecord?, base: String?, now_sha256: String) -> void
+      def initialize(principle_id:, member:, record:, base:, now_sha256:)
+        @principle_id = principle_id
+        @member = member
+        @record = record
+        @base = base
+        @now_sha256 = now_sha256
+        freeze
+      end
+
+      # The member's lines at its baseline and now, which the answer quotes; refused when the member cannot be found
+      # where its baseline was read, since there is no line there to quote (#459); #baseline reads a moved member
+      # where the map then placed it (#547).
+      #: (MemberLines?) -> MemberLines
+      def compared(lines)
+        lines or refuse("it cannot be found in its file at its baseline commit #{last_judged_commit}")
+      end
+
+      # The member's baseline: the oldest of placements, from the commit it was last judged at on, that holds the
+      # text the record vouches for, which is later than that commit when its full audit fixed it (#550), and as the
+      # map then placed it when it has moved since (#547). Refused when none does, since that text is not the
+      # audited one.
+      #: (Enumerable[Placement]) -> Placement
+      def baseline(placements)
+        recorded = acknowledgeable.members.hash_for(@member.key)
+        placements.find { |placement| placement.holds?(recorded) } ||
+          refuse("its text does not match the audit record at #{last_judged_commit} or any later commit")
+      end
+
+      # Where the member was at baseline, when that is not where it is now, as after a move (#547).
+      #: (Placement) -> Hash[String, untyped]?
+      def moved_from(baseline)
+        baseline.reference unless baseline.reference == @member.reference
+      end
+
+      # The paths the change since baseline spans, which the baseline's placement owns (#551).
+      #: (Placement) -> Array[String]
+      def paths_since(baseline) = baseline.paths_to(@member.path)
+
+      # The commit the member was last judged at, when baseline is later than it, as when the member's own full
+      # audit fixed it after its base (#550).
+      #: (Placement) -> String?
+      def audit_base(baseline)
+        judged = last_judged_commit
+        judged unless baseline.commit == judged
+      end
+
+      # The commit the member was last judged at: its last acknowledgement's, or the audit's base commit. Refused
+      # unless the member can be acknowledged now.
+      #: () -> String
+      def last_judged_commit
+        record = acknowledgeable
+        record.members.acknowledgements_for(@member.key).last&.fetch("commit") || record.base_commit.to_s
+      end
+
+      # The request's id: the member, its hash at the baseline and now, and the commit it is judged at.
+      #: () -> RequestId
+      def request_id
+        RequestId.for(principle_id: @principle_id, phase: PHASE,
+                      parts: [@member.key, acknowledgeable.members.hash_for(@member.key), @now_sha256, @base])
+      end
+
+      # The ids of the deferred and the accepted findings the last audit left on this member, which the request
+      # and the acknowledgement name (D33), the accepted ones since an edit may bear on whether they still hold
+      # (D35 brief, finding 11).
+      #: () -> Hash[String, Array[String]]
+      def open_findings
+        { "deferred_findings" => findings_on_member("deferred"), "accepted_findings" => findings_on_member("accepted") }
+      end
+
+      # The record with this member's baseline moved to its text now, once the answer is checked against the
+      # member's lines at the baseline commit and now.
+      #: (untyped, before: Array[String], now: Array[String], at: String) -> AuditRecord
+      def accepted(answer, before:, now:, at:)
+        checked(answer, before, now)
+        acknowledgeable.acknowledged(@member.key, { "from_sha256" => acknowledgeable.members.hash_for(@member.key),
+                                                    "to_sha256" => @now_sha256, "commit" => @base,
+                                                    "reason" => answer.fetch("reason"), "acknowledged_at" => at,
+                                                    **open_findings })
+      end
+
+      private
+
+      # The ids of the findings the last audit left open on this member with action.
+      #: (String) -> Array[String]
+      def findings_on_member(action)
+        acknowledgeable.open_findings
+                       .select { |finding| finding.fetch("action") == action }
+                       .select { |finding| finding.fetch("member_ids").any? { |id| on_member?(id) } }
+                       .map { |finding| finding.fetch("finding_id") }
+      end
+
+      # Whether the record's id names this member, by key, so a member moved since keeps its findings (#547).
+      #: (String) -> bool
+      def on_member?(id) = acknowledgeable.members.key_of(id) == @member.key
+
+      # The completed record, once the member can be acknowledged.
+      #: () -> AuditRecord
+      def acknowledgeable
+        refuse("an acknowledgement is judged against committed text, so it needs git") unless @base
+        record = @record or no_completed_audit
+        refused_for(record.acknowledgement_refusal(@member, now_sha256: @now_sha256))
+        record
+      end
+
+      # Raises the refusal the record gives for this member, if any.
+      #: (Symbol?) -> void
+      def refused_for(reason)
+        case reason
+        when :not_completed then no_completed_audit
+        when :not_assessed then refuse("no completed audit assessed #{@member.id}")
+        when :unchanged then nothing_to_acknowledge
+        when :checked then refuse("#{@member.id} has a check, and acknowledging a checked member is not built yet")
+        when nil then nil
+        else raise ArgumentError, "unknown acknowledgement refusal #{reason}"
+        end
+      end
+
+      #: (untyped, Array[String], Array[String]) -> void
+      def checked(answer, before, now)
+        refuse("the answer says the change does not keep #{@member.id}'s meaning") unless answer["meaning_kept"] == true
+        reason = answer.fetch("reason").to_s
+        refuse("the reason must be one line") if reason.include?("\n")
+        then_side = SideOfTheChange.new(before, "before the change")
+        now_side = SideOfTheChange.new(now, "at HEAD")
+        quoted(answer.fetch("old_line"), then_side, now_side)
+        quoted(answer.fetch("new_line"), now_side, then_side)
+      end
+
+      # A quote is a whole line of this side, or a fragment long enough to show the edit that only this side reads.
+      #: (String, SideOfTheChange, SideOfTheChange) -> void
+      def quoted(line, side, other)
+        return if side.whole_line?(line) || (line.length >= FRAGMENT_LENGTH && side.holds?(line) && !other.holds?(line))
+
+        raise Error.new("quote_not_found", "#{line.inspect} is not a line of #{@member.id} #{side.reads_at}",
+                        "Quote a whole line of the member as it reads #{side.reads_at}, or at least " \
+                        "#{FRAGMENT_LENGTH} characters of one that the member #{other.reads_at} does not hold, " \
+                        "from the change the request names.")
+      end
+
+      #: () -> bot
+      def no_completed_audit = refuse("#{@principle_id} has no completed audit, so no baseline has been judged")
+
+      # A member whose text is the one last judged, as after a pure move, needs nothing: not an acknowledgement, and
+      # not the full audit the other refusals send the agent to (#553).
+      #: () -> bot
+      def nothing_to_acknowledge
+        raise Error.new("cannot_acknowledge",
+                        "#{@member.id}'s text is the one last judged, so there is nothing to acknowledge",
+                        "Nothing needs doing.")
+                   .ending_with([Error::RepairCommand.new(purpose: "After a committed edit changes it, acknowledge it",
+                                                          command: "start-audit", values: [@principle_id],
+                                                          options: ["--member", @member.id])])
+      end
+
+      #: (String) -> bot
+      def refuse(why)
+        raise Error.new("cannot_acknowledge", "#{@member.id} cannot be acknowledged: #{why}",
+                        "For a full audit instead: #{Error::EXECUTABLE} start-audit #{@principle_id}")
+      end
+    end
+  end
+end

data/lib/principles/models/activation.rb

@@ -0,0 +1,64 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # When a principle's work is in hand, as the agent judged it (D38): when files matching its globs are read or
+    # changed, when its work is invoked, or always. This tool stores what the agent declared and does not choose it.
+    class Activation
+      FORMS = "Give exactly one of --when-files GLOB (repeat it for each glob), --when-invoked, or --always."
+
+      # The activation change-activation's options declare, refused unless they name exactly one form.
+      #: (when_files: Array[String]?, when_invoked: bool?, always: bool?) -> Activation
+      def self.declared(when_files:, when_invoked:, always:)
+        given = { "files" => when_files, "invoked" => when_invoked, "always" => always }.compact
+        unless given.length == 1
+          raise Error.new("invalid_activation", "change-activation needs one activation, not #{given.length}", FORMS)
+        end
+
+        globs = when_files
+        return new({ "when" => given.keys.first }) unless globs
+
+        new({ "when" => "files", "files" => globs })
+      end
+
+      #: (Hash[String, untyped]) -> void
+      def initialize(fields)
+        @fields = fields.freeze #: Hash[String, untyped]
+        check_globs
+        freeze
+      end
+
+      # The activation as the map stores it.
+      #: () -> Hash[String, untyped]
+      def to_h
+        @fields
+      end
+
+      # What a full audit lists against this activation for the agent to weigh: the members that load at every
+      # session start under a files activation; none under always, where the work is in hand in every session; and,
+      # under invoked, a listing not built yet (#355, #523).
+      #: () -> String
+      def full_audit_lists
+        case @fields.fetch("when")
+        when "files" then "session_start_members"
+        when "invoked" then "not_built"
+        else "none"
+        end
+      end
+
+      private
+
+      #: () -> void
+      def check_globs
+        return unless @fields.fetch("files", []).any? { |glob| glob.strip.empty? }
+
+        raise Error.new("invalid_activation", "an empty glob matches no file",
+                        "Give each --when-files a glob such as 'spec/**'.")
+      end
+    end
+  end
+end

data/lib/principles/models/agent_loads.rb

@@ -0,0 +1,64 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "frontmatter_fields"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # When Claude Code loads a project subagent's definition. Its description, which Claude reads to decide when
+    # to delegate, loads at session start in the main session; its body is the subagent's own system prompt, loaded
+    # in the subagent's context when Claude delegates to it. Claude Code reads .claude/agents recursively, from
+    # the start folder up to the repository root, as its subagents documentation says; the #354 experiment saw
+    # a project subagent's description listed at start.
+    class AgentLoads
+      # An agent's definition: a Markdown file at any depth in a .claude/agents folder, at the root or below it.
+      AGENT_FILE = %r{\A(?<folder>(?:.*/)?)\.claude/agents/(?:[^/]+/)*[^/]+\.md\z} #: Regexp
+
+      # text is the agent's whole file, or nil when it cannot be read.
+      #: (String, String?) -> void
+      def initialize(path, text)
+        @path = path
+        @text = text
+        freeze
+      end
+
+      #: () -> Hash[String, untyped]
+      def to_h
+        lines = @text&.lines or return { "when" => "not_determined" }
+        return not_derived("an agents folder below the project root") unless folder.empty?
+
+        description = FrontmatterFields.new(path: @path, lines: lines).field_lines("$.description")
+        return not_derived("an agent file without a description field") unless description
+
+        { "when" => "on_delegation", "context" => "subagent", "description" => { "when" => "session_start" } }
+      rescue Error => e
+        { "when" => "not_determined", "frontmatter_refused" => e.payload.fetch("code") }
+      end
+
+      # The description lines Claude reads at start to decide when to delegate, as written; nil without the field, or
+      # when the file cannot be read. The subagents page states no cap on one description.
+      #: () -> String?
+      def description_text
+        lines = @text&.lines or return nil
+        FrontmatterFields.new(path: @path, lines: lines).field_lines("$.description")&.join
+      rescue Error
+        nil
+      end
+
+      private
+
+      # The folder whose .claude/agents holds the agent: empty at the project root, else ending in a slash.
+      #: () -> String
+      def folder
+        AGENT_FILE.match(@path)&.[](:folder).to_s
+      end
+
+      #: (String) -> Hash[String, untyped]
+      def not_derived(why)
+        { "when" => "not_determined", "not_derived" => why }
+      end
+    end
+  end
+end

data/lib/principles/models/answer_fields.rb

@@ -0,0 +1,67 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "locator"
+require_relative "answer_place"
+require_relative "answer_text"
+require_relative "write_up_pointer"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # The checks every answer's fields share: a field is a nonempty string or an array, and each piece of
+    # evidence names a path that the caller's block locates in the project.
+    class AnswerFields
+      #: (^(Locator) -> void) -> void
+      def initialize(locate)
+        @locate = locate
+      end
+
+      #: (untyped, String) -> String
+      def text(value, field) = AnswerText.new(value).required(field)
+
+      # value as text, refused as field at its place in the answer, so one of many entries is found (#787).
+      #: (untyped, String, AnswerPlace) -> String
+      def text_at(value, field, place)
+        text(value, field)
+      rescue Error => e
+        raise place.refusal(e)
+      end
+
+      #: (untyped, String) -> untyped
+      def array(value, field)
+        unless value.is_a?(Array)
+          raise Error.new("invalid_answer", "#{field} must be an array",
+                          "Supply #{field} as the question asks.")
+        end
+
+        value
+      end
+
+      # Each piece of evidence, located where place says the answer holds it; a refusal locating one names its place.
+      #: (untyped, AnswerPlace) -> void
+      def evidence(references, place)
+        array(references, "evidence").each_with_index { |reference, index| pointer(reference, place.child(index)) }
+      end
+
+      # One pointer into the project, such as where a finding is written up, located at its place in the answer.
+      #: (untyped, AnswerPlace) -> void
+      def pointer(reference, place)
+        text(reference["path"], "evidence.path")
+        begin
+          @locate.call(Locator.new(reference))
+        rescue Error => e
+          raise place.refusal(e)
+        end
+      end
+
+      # Where a finding is written up, located at its place in the answer, as the value its record keeps (#768).
+      #: (untyped, AnswerPlace) -> WriteUpPointer
+      def write_up_pointer(reference, place)
+        pointer(reference, place)
+        WriteUpPointer.new(reference)
+      end
+    end
+  end
+end

data/lib/principles/models/answer_place.rb

@@ -0,0 +1,53 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "member_file"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # A place in an agent's answer: its JSON pointer, and whose part of the answer it is, such as "Finding F1".
+    # A refusal about what sits there names both, so the agent can find the one pointer to repair (#702).
+    class AnswerPlace
+      # What a pointer in an answer may do instead of quoting exactly a passage its file does not hold (#742).
+      ELSEWHERE = " Or point it at text the file holds."
+
+      #: String
+      attr_reader :pointer
+
+      # Whose part of the answer it is, such as "Finding F1".
+      #: String
+      attr_reader :subject
+
+      #: (String, String) -> void
+      def initialize(pointer, subject)
+        @pointer = pointer
+        @subject = subject
+        freeze
+      end
+
+      # The place of name, a key or an index, inside this one, with the same subject.
+      #: (String | Integer) -> AnswerPlace
+      def child(name) = AnswerPlace.new("#{@pointer}/#{name}", @subject)
+
+      # error, a refusal about what sits here, saying whose it is and where, as a malformed answer's fields do (D29).
+      #: (Error) -> Error
+      def refusal(error)
+        payload = error.payload
+        message = payload.fetch("message")
+        Error.new(payload.fetch("code"), "#{@subject}: #{message}", repair(payload))
+             .including(payload.except("message", "repair"))
+             .including("fields" => [{ "pointer" => @pointer, "problem" => message }])
+      end
+
+      private
+
+      #: (Hash[String, untyped]) -> String
+      def repair(payload)
+        repair = payload.fetch("repair")
+        MemberFile::QUOTE_NOT_FOUND.include?(payload.fetch("code")) ? repair + ELSEWHERE : repair
+      end
+    end
+  end
+end

data/lib/principles/models/answer_text.rb

@@ -0,0 +1,37 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # A value an agent gave where its answer asks for text, the one owner of whether it wrote any (#796).
+    class AnswerText
+      #: (untyped) -> void
+      def initialize(value)
+        @value = value
+        freeze
+      end
+
+      # Whether the agent wrote it: a string with more than whitespace in it.
+      #: () -> bool
+      def written? = @value.is_a?(String) && !@value.strip.empty? ? true : false
+
+      # Whether the agent wrote it as one line: written, with no line break in it.
+      #: () -> bool
+      def one_line? = written? && !@value.include?("\n")
+
+      # The text where field requires it: as written, or refused naming field (#798).
+      #: (String) -> String
+      def required(field)
+        unless written?
+          raise Error.new("invalid_answer", "#{field} must be a nonempty string",
+                          "Supply #{field} as the question asks.")
+        end
+
+        @value
+      end
+    end
+  end
+end

data/lib/principles/models/answered_time.rb

@@ -0,0 +1,65 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "time"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # A time as an agent wrote it in an answer, such as a sighting's observed_at, which the record compares with
+    # audited_at only in audited_at's own form: a UTC time to the second (#699).
+    class AnsweredTime
+      #: (untyped) -> void
+      def initialize(value)
+        @value = value
+        freeze
+      end
+
+      # Whether it is a UTC time in audited_at's form. Only a time that reads back as written is: Time.iso8601 takes an
+      # offset or a fraction, and rolls 30 February over to March.
+      #: () -> bool
+      def utc?
+        return false unless @value.is_a?(String)
+
+        Time.iso8601(@value).utc.iso8601 == @value
+      rescue ArgumentError
+        false
+      end
+
+      # Whether it is written as a date alone, such as 2026-11-01, whether or not a calendar has that date.
+      #: () -> bool
+      def date_alone?
+        return false unless @value.is_a?(String)
+
+        @value.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+      end
+
+      # The UTC time in audited_at's form that it names exactly, or nil when it names none: a date alone at its
+      # midnight, and a time to the second with an offset as the same instant (#801). A fraction, or a date no
+      # calendar has, names none.
+      #: () -> String?
+      def exact_utc
+        return midnight if date_alone?
+        return unless @value.is_a?(String)
+
+        time = Time.iso8601(@value)
+        time.utc.iso8601 if time.iso8601 == @value
+      rescue ArgumentError
+        nil
+      end
+
+      # Whether it is later than time, both UTC times in audited_at's form: a sighting is made before the answer that
+      # reports it (#699), so a repair never prints one later (#801).
+      #: (String) -> bool
+      def after?(time) = Time.iso8601(@value) > Time.iso8601(time)
+
+      private
+
+      #: () -> String?
+      def midnight
+        at_midnight = "#{@value}T00:00:00Z"
+        at_midnight if AnsweredTime.new(at_midnight).utc?
+      end
+    end
+  end
+end