principles 0.0.6 → 0.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. checksums.yaml +4 -4
  2. data/lib/principles/cli.rb +9 -0
  3. data/lib/principles/command_line.rb +22 -5
  4. data/lib/principles/command_routes.rb +2 -2
  5. data/lib/principles/controllers/acknowledgement.rb +79 -102
  6. data/lib/principles/controllers/answer.rb +7 -6
  7. data/lib/principles/controllers/assessment.rb +13 -21
  8. data/lib/principles/controllers/audit.rb +24 -4
  9. data/lib/principles/controllers/audit_completion.rb +7 -3
  10. data/lib/principles/controllers/correction.rb +13 -6
  11. data/lib/principles/controllers/full_audit_request.rb +7 -2
  12. data/lib/principles/controllers/member_acknowledgement.rb +137 -0
  13. data/lib/principles/controllers/member_problems_report.rb +31 -23
  14. data/lib/principles/data/command-steps.json +9 -9
  15. data/lib/principles/data/schemas/acknowledgement-answer.schema.json +3 -2
  16. data/lib/principles/data/schemas/acknowledgements-answer.schema.json +88 -0
  17. data/lib/principles/data/schemas/assessment-answer.schema.json +15 -1
  18. data/lib/principles/data/schemas/command-steps.schema.json +1 -1
  19. data/lib/principles/data/schemas/correction-answer.schema.json +6 -54
  20. data/lib/principles/invocation_options.rb +5 -4
  21. data/lib/principles/list_open_findings_options.rb +23 -0
  22. data/lib/principles/models/acknowledged_check.rb +94 -0
  23. data/lib/principles/models/acknowledgement.rb +18 -36
  24. data/lib/principles/models/acknowledgement_left_as_printed.rb +25 -4
  25. data/lib/principles/models/acknowledgements.rb +99 -0
  26. data/lib/principles/models/answered_time.rb +9 -0
  27. data/lib/principles/models/assessment_report.rb +13 -13
  28. data/lib/principles/models/audit.rb +17 -4
  29. data/lib/principles/models/audit_record.rb +5 -0
  30. data/lib/principles/models/correction_basis.rb +14 -5
  31. data/lib/principles/models/list_member_problems_check.rb +80 -0
  32. data/lib/principles/models/listed_members.rb +49 -0
  33. data/lib/principles/models/loading_decision.rb +17 -8
  34. data/lib/principles/models/loads_to_check.rb +0 -1
  35. data/lib/principles/models/member_assessments.rb +11 -2
  36. data/lib/principles/models/member_problems.rb +9 -5
  37. data/lib/principles/models/member_sighting.rb +5 -8
  38. data/lib/principles/models/problem_report.rb +19 -4
  39. data/lib/principles/models/project.rb +5 -4
  40. data/lib/principles/models/reported_check.rb +14 -11
  41. data/lib/principles/models/request_id.rb +1 -1
  42. data/lib/principles/models/sent_answer.rb +29 -9
  43. data/lib/principles/positional_arguments.rb +3 -2
  44. data/lib/principles/session_start_options.rb +3 -3
  45. data/lib/principles/start_audit_options.rb +10 -2
  46. data/lib/principles/version.rb +2 -2
  47. data/lib/principles/views/acknowledgement_result.rb +46 -12
  48. data/lib/principles/views/assessed_members.rb +26 -5
  49. data/lib/principles/views/assessment_request.rb +22 -3
  50. data/lib/principles/views/audit_result.rb +9 -1
  51. data/lib/principles/views/check_result_template.rb +18 -17
  52. data/lib/principles/views/correction_request.rb +6 -9
  53. data/lib/principles/views/findings_result.rb +21 -0
  54. data/lib/principles/views/invocation.rb +19 -4
  55. data/lib/principles/views/loads_to_check_result.rb +3 -2
  56. data/lib/principles/views/member_row.rb +61 -0
  57. data/lib/principles/views/members_a_commit_changed.rb +2 -1
  58. data/lib/principles/views/members_with_no_baseline.rb +8 -1
  59. data/lib/principles/views/one_member_check_result_template.rb +21 -9
  60. data/lib/principles/views/open_findings_line.rb +2 -1
  61. data/lib/principles/views/problem_lines.rb +48 -45
  62. data/lib/principles/views/problem_result.rb +55 -26
  63. data/lib/principles/views/prompts/acknowledge-a-change/report-the-exit-status-its-own-listing-gives.md +3 -0
  64. data/lib/principles/views/prompts/acknowledge-a-change/say-whether-each-change-keeps-its-meaning.md +8 -0
  65. data/lib/principles/views/prompts/assess-every-member/decide-each-member-loading.md +2 -1
  66. data/lib/principles/views/prompts/assess-every-member/run-the-check-then-report-it.md +2 -2
  67. data/lib/principles/views/prompts/assess-every-member/run-the-reviewed-check-and-say-what-its-review-rested-on.md +5 -3
  68. data/lib/principles/views/prompts/learn-what-a-command-does/every-command-and-how-they-chain.md +1 -2
  69. data/lib/principles/views/prompts/learn-what-a-command-does/list-member-problems.md +15 -15
  70. data/lib/principles/views/prompts/learn-what-a-command-does/list-open-findings.md +65 -61
  71. data/lib/principles/views/prompts/learn-what-a-command-does/show-answer-check.md +7 -7
  72. data/lib/principles/views/prompts/learn-what-a-command-does/start-audit.md +8 -8
  73. data/lib/principles/views/prompts/learn-what-a-command-does/submit-answer.md +37 -37
  74. data/lib/principles/views/prompts/start-a-session/act-on-the-open-findings.md +1 -1
  75. data/lib/principles/views/prompts/start-a-session/every-loaded-line-costs-every-session.md +1 -0
  76. data/lib/principles/views/prompts/start-a-session/start-with-the-principles-skill.md +1 -0
  77. metadata +13 -1
@@ -30,20 +30,29 @@ module Principles
30
30
  #: () -> String
31
31
  def member_id = @decision["member_id"].to_s
32
32
 
33
- # What the record keeps of this decision once checked: its reason and the loads it accepted, from its
34
- # member's row in the listing.
33
+ # What the record keeps of this decision: its reason, or for kept the last accepted reason, and the loads it
34
+ # accepted, from its member's row in the listing; refused unless the decision is one the record can keep.
35
35
  #: (Hash[String, untyped]) -> Hash[String, untyped]
36
- def kept(row) = { "reason" => @decision["reason"], "loads" => row.fetch("loads") }
36
+ def kept(row)
37
+ check(row)
38
+ reason = @decision["decision"] == "kept" ? row.dig("last_accepted", "reason") : @decision["reason"]
39
+ { "reason" => reason, "loads" => row.fetch("loads") }
40
+ end
41
+
42
+ private
37
43
 
38
- # Refuses the decision unless it is accepted with a one-line reason.
39
- #: () -> void
40
- def check
44
+ # Refuses the decision unless it is accepted with a one-line reason, or kept on a member row whose loading
45
+ # the last audit accepted and is unchanged since, so its reason still holds (#1186).
46
+ #: (Hash[String, untyped]) -> void
47
+ def check(row)
41
48
  return if @decision["decision"] == "accepted" && AnswerText.new(@decision["reason"]).written?
49
+ return if @decision["decision"] == "kept" && row.dig("last_accepted", "since_accepted") == "unchanged"
42
50
 
43
51
  raise Error.new("invalid_loading_decision",
44
52
  "loading_decisions[#{@index}] for #{@decision["member_id"]} needs decision accepted with a " \
45
- "reason",
46
- "Give decision accepted with a one-line reason why the member loads as it does, or, if the " \
53
+ "reason, or kept where its last_accepted.since_accepted is unchanged",
54
+ "Give decision accepted with a one-line reason why the member loads as it does, or kept to " \
55
+ "repeat the last accepted reason while since_accepted is unchanged, or, if the " \
47
56
  "activation is what is wrong, change it with change-activation and run start-audit again, " \
48
57
  "as the request's loads_to_check_instruction says; a finding decision is not built yet.")
49
58
  end
@@ -46,7 +46,6 @@ module Principles
46
46
  expected = listed_by_id
47
47
  raise incomplete(expected.keys) unless given.map(&:member_id).sort == expected.keys.sort
48
48
 
49
- given.each(&:check)
50
49
  given.to_h { |decision| [decision.member_id, decision.kept(expected.fetch(decision.member_id))] }
51
50
  end
52
51
 
@@ -7,6 +7,7 @@ require_relative "answer_fields"
7
7
  require_relative "answer_place"
8
8
  require_relative "carried_assessments"
9
9
  require_relative "principle_members"
10
+ require_relative "answered_time"
10
11
  require_relative "member_sighting"
11
12
  require_relative "misspelt_member_id"
12
13
  require_relative "record_judged_against"
@@ -88,12 +89,20 @@ module Principles
88
89
 
89
90
  private
90
91
 
91
- # assessments without the sighting fields each leaves as printed, which it does not give (#1010).
92
+ # assessments without the sighting fields each leaves as printed, which it does not give (#1010), each
93
+ # observed_at given with an offset read in audited_at's form (#1187).
92
94
  #: (untyped) -> untyped
93
95
  def given(assessments)
94
96
  return assessments unless assessments.is_a?(Array)
95
97
 
96
- assessments.map { |assessment| assessment.is_a?(Hash) ? SIGHTING.given(assessment) : assessment }
98
+ assessments.map { |assessment| assessment.is_a?(Hash) ? in_utc(SIGHTING.given(assessment)) : assessment }
99
+ end
100
+
101
+ #: (Hash[String, untyped]) -> Hash[String, untyped]
102
+ def in_utc(assessment)
103
+ return assessment unless assessment.key?("observed_at")
104
+
105
+ assessment.merge("observed_at" => AnsweredTime.new(assessment["observed_at"]).in_audited_at_form)
97
106
  end
98
107
 
99
108
  # Refuses answered, the ids the assessments name, unless they are the mapped ids, each once, hinting at any
@@ -154,12 +154,16 @@ module Principles
154
154
  # Whether a member an audit or acknowledgement assessed changed since, rather than only a member edited since
155
155
  # the commit that mapped it, which no audit assessed (D44).
156
156
  #: () -> bool
157
- def assessed_change? = changes_to_act_on.any? { |member| assessed?(member) }
157
+ def assessed_change? = assessed_changes.positive?
158
158
 
159
- # Whether a member no audit assessed was edited since the commit that mapped it, which --short exits 4 for
160
- # when it is the only kind of change (D44).
161
- #: () -> bool
162
- def unassessed_change? = changes_to_act_on.any? { |member| !assessed?(member) }
159
+ # How many such members changed, which the session-start hook counts by principle (#1261).
160
+ #: () -> Integer
161
+ def assessed_changes = changes_to_act_on.count { |member| assessed?(member) }
162
+
163
+ # How many members no audit has assessed, compared only with the commit that mapped them, edited or not, which
164
+ # --short counts on stdout (#1254); none while the principle's audits wait on an upgrade.
165
+ #: () -> Integer
166
+ def never_assessed = @baselines.waiting? ? 0 : compared_with.fetch("mapping_commit", 0)
163
167
 
164
168
  # The entries whose own text changed since this tool last knew it, those an audit assessed first. Given a
165
169
  # block, each gains "history", what the block makes of its member, the hash it was compared with, and its
@@ -111,8 +111,8 @@ module Principles
111
111
  end
112
112
 
113
113
  # An observed_at is a UTC time in audited_at's form, as the record dates every other sighting, to compare; a
114
- # date alone, an offset or fractional seconds cannot, nor a time no calendar has (#699). Null or none is this
115
- # audit's.
114
+ # date alone or fractional seconds cannot, nor a time no calendar has (#699). One given with an offset arrives
115
+ # here already in that form (#1187). Null or none is this audit's.
116
116
  #: () -> void
117
117
  def refuse_unshaped_observed_at
118
118
  observed_at = @assessment["observed_at"]
@@ -125,15 +125,12 @@ module Principles
125
125
  "problem" => "must be a UTC time like #{SHAPE_EXAMPLE}" }])
126
126
  end
127
127
 
128
- # The repair for an observed_at not in audited_at's form: the value it names exactly, to copy, when that is no
129
- # later than the answer, which would refuse it in turn; otherwise the form, and how to date a date alone (#801).
128
+ # The repair for an observed_at not in audited_at's form: for a date alone, its midnight, to copy, when that is
129
+ # no later than the answer, which would refuse it in turn; otherwise the form to follow (#801).
130
130
  #: (AnsweredTime) -> String
131
131
  def shape_repair(given)
132
132
  exact = given.exact_utc
133
- return FORM_REPAIR if exact.nil? || AnsweredTime.new(exact).after?(@answered_at)
134
- unless given.date_alone?
135
- return %(Give "observed_at" as "#{exact}", the same time in UTC, #{OR_NULL_FOR_THIS_AUDIT})
136
- end
133
+ return FORM_REPAIR if !given.date_alone? || exact.nil? || AnsweredTime.new(exact).after?(@answered_at)
137
134
 
138
135
  %(Give "observed_at" as "#{exact}", that date at 00:00:00Z, and say in observation that the time is ) +
139
136
  "unknown, #{OR_NULL_FOR_THIS_AUDIT}"
@@ -12,6 +12,16 @@ module Principles
12
12
  # broken, so a gate can stop on its exit status alone, and otherwise every changed member and a count of
13
13
  # each state.
14
14
  class ProblemReport
15
+ # What list-member-problems reports for map id, or every map, listing a map it cannot read among them, with the
16
+ # project's history, which lets each missing file carry the rename git detects for it.
17
+ #: (Project, String?) -> ProblemReport
18
+ def self.for(project, id)
19
+ maps = if id then [MemberProblems.for(project, id)]
20
+ else project.principles.ids.map { MemberProblems.for(project, it, listing_all: true) }
21
+ end
22
+ new(maps, history: project.history)
23
+ end
24
+
15
25
  # history, when given, lets each missing file carry the rename git detects for it (#276).
16
26
  #: (Array[MemberProblems], ?history: ProjectHistory?) -> void
17
27
  def initialize(maps, history: nil)
@@ -44,12 +54,17 @@ module Principles
44
54
  #: () -> bool
45
55
  def assessed_change? = @maps.any?(&:assessed_change?)
46
56
 
47
- # Whether any map's member no audit assessed was edited since the commit that mapped it (D44).
48
- #: () -> bool
49
- def unassessed_change? = @maps.any?(&:unassessed_change?)
57
+ # For each map with a changed member an audit or acknowledgement assessed, how many, which --session-start
58
+ # counts instead of listing each (#1261).
59
+ #: () -> Hash[String, Integer]
60
+ def assessed_changes = @maps.to_h { [it.principle_id, it.assessed_changes] }.reject { |_, count| count.zero? }
61
+
62
+ # For each map with members no audit has assessed, how many, which --short counts on stdout (#1254).
63
+ #: () -> Hash[String, Integer]
64
+ def never_assessed = @maps.to_h { [it.principle_id, it.never_assessed] }.reject { |_, count| count.zero? }
50
65
 
51
66
  # For each map with a changed member a one-member audit may judge, the ids of those members, which
52
- # list-member-problems offers that audit for, one command each (#626, D56).
67
+ # list-member-problems offers that audit for, one command per principle (#626, D56, #1263).
53
68
  #: () -> Hash[String, Array[String]]
54
69
  def acknowledgeable
55
70
  @maps.to_h { |map| [map.principle_id, map.acknowledgeable_member_ids] }.reject { |_, ids| ids.empty? }
@@ -207,10 +207,11 @@ module Principles
207
207
  #: () -> EntryFiles
208
208
  def entry_files = EntryFiles.read(@files, history)
209
209
 
210
- # An answer to a phase's request from file, where - means it was read from stdin, its head checked against
211
- # the phase's answer schema (D29) and the rest left to check once its request is known (#1052).
212
- #: (String, stdin: String?, phase: String) -> SentAnswer
213
- def answer(file, stdin:, phase:) = SentAnswer.read(@files, file, stdin:, phase:)
210
+ # An answer to the request given, or to the one it names when none is (#995), from file, where - means it was
211
+ # read from stdin, its head checked against that request's phase's answer schema (D29) and the rest left to
212
+ # check once its request is known (#1052).
213
+ #: (String, stdin: String?, given: String?) -> SentAnswer
214
+ def answer(file, stdin:, given:) = SentAnswer.read(@files, file, stdin:, given:)
214
215
 
215
216
  # What list-candidate-files found, as CandidateInventory reads it from the project, after a commit when given.
216
217
  #: (?after: String?, ?also: Array[String]) -> CandidateInventory
@@ -18,28 +18,31 @@ module Principles
18
18
  # How review_basis records a review the agent made itself, which the placeholder and the repair both give.
19
19
  SELF_REVIEWED = "\"Self-reviewed by the agent: <what you checked it against>\"" #: String
20
20
  # The not_run_reason a template prints beside exit_status's placeholder, which an answer that leaves it as
21
- # printed has not given, so filling exit_status alone reports a run (#993).
22
- NOT_RUN_PLACEHOLDER = "Only if the command could not be run here: why, such as a missing tool or a sandbox. " \
23
- "Leave this as printed once exit_status gives the run's status" #: String
21
+ # printed has not given, so filling exit_status alone reports a run (#993). Short, as the template's rule on
22
+ # fields left as printed says the rest (#1191).
23
+ NOT_RUN_PLACEHOLDER = "Only if the check could not run here: why" #: String
24
24
  # The review_basis a template prints for a check no audit ran, or one changed since, which an exit_status needs
25
- # beside it, and which beside not_run_reason left as printed is not given (D63, #993).
26
- REVIEW_BASIS_PLACEHOLDER = "One line saying what the review before the run rested on, such as who reviewed " \
27
- "it or the document that confirms it; for your own review, #{SELF_REVIEWED}. " \
28
- "Leave this as printed only beside not_run_reason".freeze #: String
25
+ # beside it, and which beside not_run_reason left as printed is not given (D63, #993); what to write is the
26
+ # check's instruction (#1191).
27
+ REVIEW_BASIS_PLACEHOLDER = "One line: what the review before the run rested on" #: String
29
28
  # Why an exit status for a check no audit ran is refused without review_basis, and when given its placeholder.
30
29
  NEEDS_BASIS = "check_result needs review_basis beside exit_status, since no audit ran this command" #: String
31
30
  LEFT_BASIS = "check_result.review_basis is the template's placeholder, unchanged, and an exit_status for a " \
32
31
  "command no audit ran needs it" #: String
32
+ # The exit_status a template prints where the run's status goes, what to do being the check's instruction
33
+ # (#1170, #1191).
34
+ EXIT_STATUS_PLACEHOLDER = "the check's exit status, an integer" #: String
33
35
  # The placeholder a template prints in each field an answer may leave as printed to give none.
34
- PLACEHOLDERS = TemplatePlaceholders.new({ "not_run_reason" => NOT_RUN_PLACEHOLDER,
36
+ PLACEHOLDERS = TemplatePlaceholders.new({ "exit_status" => EXIT_STATUS_PLACEHOLDER,
37
+ "not_run_reason" => NOT_RUN_PLACEHOLDER,
35
38
  "review_basis" => REVIEW_BASIS_PLACEHOLDER }) #: TemplatePlaceholders
36
39
  # The review_basis a template prints for a check the last audit ran, which left as printed keeps the line that
37
40
  # audit kept, and replaced gives a new one (#1010).
38
- KEPT_BASIS_PLACEHOLDER = "Only to give a new line for what this run's review rested on; leave this as " \
39
- "printed to keep the line the last audit kept, if any" #: String
41
+ KEPT_BASIS_PLACEHOLDER = "Only for a new line on what this run's review rested on; else kept" #: String
40
42
  # The placeholders a template prints for a check the last audit ran.
41
43
  UNCHANGED_PLACEHOLDERS = TemplatePlaceholders.new(
42
- { "not_run_reason" => NOT_RUN_PLACEHOLDER, "review_basis" => KEPT_BASIS_PLACEHOLDER }
44
+ { "exit_status" => EXIT_STATUS_PLACEHOLDER, "not_run_reason" => NOT_RUN_PLACEHOLDER,
45
+ "review_basis" => KEPT_BASIS_PLACEHOLDER }
43
46
  ) #: TemplatePlaceholders
44
47
  BASIS = "Say in review_basis, in one line, what the review before the run rested on, such as " \
45
48
  "\"The owner reviewed the command in this session.\" or the document that confirms it. If you did " \
@@ -12,7 +12,7 @@ module Principles
12
12
  # the digest from the project as it is now: a different digest means something the request depended
13
13
  # on has changed (D25). The digest has no secret, so it catches mistakes, not forgery.
14
14
  class RequestId
15
- PHASES = %w[assessment correction acknowledgement repointing].freeze
15
+ PHASES = %w[assessment correction acknowledgement acknowledgements repointing].freeze
16
16
  FORMAT = /\A(?<principle>[a-z0-9]+(?:-[a-z0-9]+)*)\.(?<phase>[a-z]+)\.(?<digest>[0-9a-f]{12})\z/
17
17
 
18
18
  #: String
@@ -5,6 +5,7 @@ require_relative "../data/schema_check"
5
5
  require_relative "../data/project_files"
6
6
  require_relative "../error"
7
7
  require_relative "refusal_before_shape"
8
+ require_relative "request_id"
8
9
 
9
10
  module Principles
10
11
  module Models
@@ -23,22 +24,41 @@ module Principles
23
24
 
24
25
  REPAIR = "Repair each field listed, starting from the request's response_template." #: String
25
26
 
26
- # The answer read from the file or stdin the agent named, using its phase's schema.
27
- #: (Data::ProjectFiles, String, stdin: String?, phase: String) -> SentAnswer
28
- def self.read(files, file, stdin:, phase:)
27
+ # The answer read from the file or stdin the agent named, to the request given, the REQUEST_ID the agent typed,
28
+ # or when it typed none the request_id the answer names, as its template printed it (#995), using that request's
29
+ # phase's schema.
30
+ #: (Data::ProjectFiles, String, stdin: String?, given: String?) -> SentAnswer
31
+ def self.read(files, file, stdin:, given:)
29
32
  parsed = if file == "-" then files.parse_json(stdin.to_s, "-", named: NAMED)
30
33
  else files.read_json(file, named: FILE_NAMED)
31
34
  end
32
- new(parsed, file, Data::SchemaCheck.new("#{phase}-answer"))
35
+ new(parsed, file, RequestId.parse(given || named_request(parsed)))
33
36
  end
34
37
 
35
- # parsed is the answer as its source, a file or - for stdin, holds it; check is its phase's answer schema.
36
- #: (untyped, String, Data::SchemaCheck) -> void
37
- def initialize(parsed, source, check)
38
+ # The request_id the answer names, refused when it names none, since no REQUEST_ID was typed either (#995).
39
+ #: (untyped) -> String
40
+ def self.named_request(parsed)
41
+ named = parsed["request_id"] if parsed.is_a?(Hash)
42
+ return named if named.is_a?(String)
43
+
44
+ raise Error.new("unknown_request", "#{NAMED} names no request_id, and no REQUEST_ID was given",
45
+ "Keep the request_id the request's response_template printed in the answer, or give it as " \
46
+ "REQUEST_ID.")
47
+ end
48
+ private_class_method :named_request
49
+
50
+ #: RequestId
51
+ attr_reader :request_id
52
+
53
+ # parsed is the answer as its source, a file or - for stdin, holds it, to request_id, whose phase's answer schema
54
+ # it is checked against.
55
+ #: (untyped, String, RequestId) -> void
56
+ def initialize(parsed, source, request_id)
38
57
  @parsed = parsed
39
58
  @source = source
40
- @check = check
41
- check.only(HEAD).checked(parsed, code: "invalid_answer", source: source, repair: REPAIR, named: NAMED)
59
+ @request_id = request_id
60
+ @check = Data::SchemaCheck.new("#{request_id.phase}-answer") #: Data::SchemaCheck
61
+ @check.only(HEAD).checked(parsed, code: "invalid_answer", source: source, repair: REPAIR, named: NAMED)
42
62
  freeze
43
63
  end
44
64
 
@@ -14,10 +14,11 @@ module Principles
14
14
  #: () -> String?
15
15
  def id = %w[id id?].include?(@names.first) ? @values.first : nil
16
16
 
17
- # Every named argument other than the principle id, as the controller receives it.
17
+ # Every named argument other than the principle id, as the controller receives it, an optional one by its name
18
+ # without the ?.
18
19
  #: () -> Hash[String, untyped]
19
20
  def bindings
20
- bound = @names.zip(@values).to_h.except("id", "id?")
21
+ bound = @names.map { it.chomp("?") }.zip(@values).to_h.except("id")
21
22
  repeated = @names.last
22
23
  return bound unless repeated == "path..."
23
24
 
@@ -4,8 +4,8 @@
4
4
  require_relative "invocation_options"
5
5
 
6
6
  module Principles
7
- # The option list-open-findings --short takes from Claude Code's SessionStart hook, --session-start (#717), and what
8
- # is wrong with it as given, which CommandLine refuses as a usage error.
7
+ # The option list-open-findings --short and list-member-problems --short take from Claude Code's SessionStart hook,
8
+ # --session-start (#717, #1261), and what is wrong with it as given, which CommandLine refuses as a usage error.
9
9
  class SessionStartOptions
10
10
  # The sources Claude Code's SessionStart hook names.
11
11
  SOURCES = %w[startup resume clear compact].freeze #: Array[String]
@@ -17,7 +17,7 @@ module Principles
17
17
  freeze
18
18
  end
19
19
 
20
- # What is wrong with the option as given, or nil when it fits or is not given; it words only the --short line.
20
+ # What is wrong with the option as given, or nil when it fits or is not given; it shapes only --short's lines.
21
21
  #: () -> String?
22
22
  def fault
23
23
  start = @start or return
@@ -9,7 +9,8 @@ module Principles
9
9
  class StartAuditOptions
10
10
  #: (InvocationOptions) -> void
11
11
  def initialize(options)
12
- @member = !options.value("member").nil? #: bool
12
+ @members = options.value("member") || [] #: Array[String]
13
+ @member = !@members.empty? #: bool
13
14
  @write_ups = !options.value("write_ups").nil? #: bool
14
15
  @form = options.value("as") #: String?
15
16
  @instruction = !options.value("instruction").nil? #: bool
@@ -21,11 +22,18 @@ module Principles
21
22
  def fault
22
23
  return "--member and --write-ups each start a different audit; give one" if @member && @write_ups
23
24
 
24
- instruction_fault || form_fault
25
+ member_fault || instruction_fault || form_fault
25
26
  end
26
27
 
27
28
  private
28
29
 
30
+ # A member given twice, which the agent would judge once (#1169); nil when each is given once.
31
+ #: () -> String?
32
+ def member_fault
33
+ twice = @members.find { |member| @members.count(member) > 1 } or return
34
+ "--member #{twice} is given twice; give each member once"
35
+ end
36
+
29
37
  # --instruction prints one field of a full audit's request whole (D81 step 2); nil when nothing beside it prints
30
38
  # another output.
31
39
  #: () -> String?
@@ -3,9 +3,9 @@
3
3
 
4
4
  module Principles
5
5
  # The next production release, as major.minor.patch. A production build is versioned with this alone.
6
- RELEASE = "0.0.6"
6
+ RELEASE = "0.0.7"
7
7
  # The version a built gem prints. `rake build[production]` stamps RELEASE here, in the copy of lib/ it
8
8
  # packages, and `rake build[development]` stamps RELEASE.g<short sha>. A checkout leaves it nil, and
9
9
  # Data::RunningVersion reads the commit this tool runs from instead.
10
- BUILT_VERSION = "0.0.6" #: String?
10
+ BUILT_VERSION = "0.0.7" #: String?
11
11
  end
@@ -5,6 +5,7 @@ require_relative "invocation"
5
5
  require_relative "answered_request"
6
6
  require_relative "member_change_since_baseline"
7
7
  require_relative "prompts"
8
+ require_relative "../prose_list"
8
9
 
9
10
  module Principles
10
11
  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
@@ -17,26 +18,59 @@ module Principles
17
18
  freeze
18
19
  end
19
20
 
20
- # change is the member's change since its baseline; context, what the request's context shows beside it, such
21
- # as the record's findings on the member; placeholders, the text the template prints in each field the agent
22
- # writes. What the agent judges is under context, the question last, as in a full audit's request (D60).
23
- #: (request_id: String, principle_id: String, change: MemberChangeSinceBaseline,
24
- #| context: Hash[String, untyped], placeholders: Hash[String, untyped]) -> Hash[String, untyped]
25
- def request(request_id:, principle_id:, change:, context:, placeholders:)
21
+ # asked is what the request asks of its member: under :change its change since its baseline; under :context
22
+ # what the request's context shows beside it, such as the record's findings on the member; and under
23
+ # :placeholders the text the template prints in each field the agent writes. What the agent judges is under
24
+ # context, the question last, as in a full audit's request (D60).
25
+ #: (request_id: String, principle_id: String, asked: Hash[Symbol, untyped]) -> Hash[String, untyped]
26
+ def request(request_id:, principle_id:, asked:)
26
27
  { "status" => "agent_judgement_required", "request_id" => request_id, "phase" => "acknowledgement",
27
- "context" => { "principle_id" => principle_id, **change.to_h, **context,
28
+ "context" => { "principle_id" => principle_id, **asked.fetch(:change).to_h, **asked.fetch(:context),
28
29
  "question" => Prompts.text("acknowledge-a-change/say-whether-the-change-keeps-the-meaning") },
29
- "response_template" => answer_to_fill(request_id:, change:, placeholders:),
30
+ "response_template" => answer_to_fill(request_id:, asked:),
30
31
  "answer_with" => @invocation.submit_answer(request_id) }
31
32
  end
32
33
 
33
34
  # The answer to the request request_id names, to fill: the request prints it as response_template, and
34
35
  # start-audit --member --as template prints it alone, each field the agent writes holding its placeholder (#773),
35
36
  # and only those: the fields the answer may add, the question names (#1170).
36
- #: (request_id: String, change: MemberChangeSinceBaseline, placeholders: Hash[String, untyped])
37
- #| -> Hash[String, untyped]
38
- def answer_to_fill(request_id:, change:, placeholders:)
39
- { "request_id" => request_id, "basis" => { "member_id" => change.member_id }, **placeholders }
37
+ #: (request_id: String, asked: Hash[Symbol, untyped]) -> Hash[String, untyped]
38
+ def answer_to_fill(request_id:, asked:)
39
+ { "request_id" => request_id, "basis" => { "member_id" => asked.fetch(:change).member_id },
40
+ **asked.fetch(:placeholders) }
41
+ end
42
+
43
+ # The request for several members' acknowledgements in one answer (#1169): each of members holds a member's
44
+ # change, the context its own request shows beside it and the placeholders its template prints, as one member's
45
+ # request holds them, under context.members and the template's members in the order the agent named them.
46
+ #: (request_id: String, principle_id: String, members: Array[Hash[Symbol, untyped]]) -> Hash[String, untyped]
47
+ def several_request(request_id:, principle_id:, members:)
48
+ { "status" => "agent_judgement_required", "request_id" => request_id, "phase" => "acknowledgements",
49
+ "context" => { "principle_id" => principle_id,
50
+ "members" => members.map { { **it.fetch(:change).to_h, **it.fetch(:context) } },
51
+ "question" => Prompts.text("acknowledge-a-change/say-whether-each-change-keeps-its-meaning") },
52
+ "response_template" => several_to_fill(request_id:, members:),
53
+ "answer_with" => @invocation.submit_answer(request_id) }
54
+ end
55
+
56
+ # The answer to the request for several members request_id names, to fill: its basis names each member, and
57
+ # its members hold each one's placeholders under its id, as start-audit --as template prints it alone.
58
+ #: (request_id: String, members: Array[Hash[Symbol, untyped]]) -> Hash[String, untyped]
59
+ def several_to_fill(request_id:, members:)
60
+ { "request_id" => request_id, "basis" => { "member_ids" => members.map { it.fetch(:change).member_id } },
61
+ "members" => members.to_h { [it.fetch(:change).member_id, it.fetch(:placeholders)] } }
62
+ end
63
+
64
+ # The acknowledgement of each of member_ids was accepted, and file holds them all.
65
+ #: (principle_id: String, member_ids: Array[String], file: String) -> AnsweredRequest
66
+ def several_acknowledged(principle_id:, member_ids:, file:)
67
+ AnsweredRequest.new(
68
+ "status" => "acknowledged", "principle_id" => principle_id, "member_ids" => member_ids,
69
+ "files_to_commit" => [file],
70
+ "next_action" => "Commit #{file}. #{ProseList.new(member_ids)} read as judged until each is edited again.\n" \
71
+ "After committing, this no longer lists them: " \
72
+ "#{@invocation.in_project("list-member-problems", principle_id, usage: "--short")}"
73
+ )
40
74
  end
41
75
 
42
76
  # The acknowledgement was accepted and file holds it.
@@ -46,12 +46,20 @@ module Principles
46
46
  #: () -> Array[Hash[String, untyped]]
47
47
  def shown
48
48
  @members.map do |member|
49
- next fields(member, SHOWN) unless compact?(member)
49
+ next fields(member, SHOWN).merge(instruction(member)) unless compact?(member)
50
50
 
51
- fields(member, COMPACT).merge("carried_forward" => member.fetch("carried_forward").slice(*CARRIED_COMPACTLY))
51
+ fields(member, COMPACT).merge(instruction(member),
52
+ "carried_forward" => member.fetch("carried_forward").slice(*CARRIED_COMPACTLY))
52
53
  end
53
54
  end
54
55
 
56
+ # How to run and report each checked member's check, by id, as the template printed alone gives it beside the
57
+ # members, since it has no context to show it in (#1024, #1191).
58
+ #: () -> Hash[String, String]
59
+ def check_instructions
60
+ @members.to_h { [it.fetch("id"), check_template(it)&.instruction] }.compact
61
+ end
62
+
55
63
  # Each member's template entry: a fresh assessment to fill in, or, for a member whose last assessment is
56
64
  # carried forward, the marker that keeps it (D49); either with its check's result when it has a check.
57
65
  #: () -> Array[Hash[String, untyped]]
@@ -111,9 +119,22 @@ module Principles
111
119
  #: (Hash[String, untyped]) -> Hash[String, untyped]
112
120
  def template(member)
113
121
  assessed = member["carried_forward"] ? carried(member) : fresh(member)
114
- template = CheckResultTemplate.for(member, reviewed_placeholders: @reviewed_check_placeholders,
115
- unchanged_placeholders: @unchanged_check_placeholders)
116
- template ? assessed.merge("check_result" => template) : assessed
122
+ template = check_template(member)
123
+ template ? assessed.merge("check_result" => template.to_h) : assessed
124
+ end
125
+
126
+ # The check_result template of a checked member, with its instruction; nil for one without a check.
127
+ #: (Hash[String, untyped]) -> CheckResultTemplate?
128
+ def check_template(member)
129
+ CheckResultTemplate.for(member, reviewed_placeholders: @reviewed_check_placeholders,
130
+ unchanged_placeholders: @unchanged_check_placeholders)
131
+ end
132
+
133
+ # The member's check_instruction, as the request's context shows it beside the member; none without a check.
134
+ #: (Hash[String, untyped]) -> Hash[String, String]
135
+ def instruction(member)
136
+ template = check_template(member) or return {}
137
+ { "check_instruction" => template.instruction }
117
138
  end
118
139
 
119
140
  #: (Hash[String, untyped]) -> Hash[String, untyped]
@@ -88,16 +88,35 @@ module Principles
88
88
 
89
89
  # The answer to fill in as printed alone, with no request beside it: each placeholder says what its field
90
90
  # takes, and points at nothing left unprinted (D81 step 1), after one note saying how a field left as printed is
91
- # read (#1043, D88).
91
+ # read (#1043, D88), and the carried members whose check it still asks to run, named before the members so a
92
+ # reader skipping carried markers still runs each (D12, D19).
92
93
  #: () -> Hash[String, untyped]
93
94
  def template_to_fill
94
- filled = assessed(@placeholders.fetch("recent_decision"), @members.templates_to_fill)
95
+ members = @members.templates_to_fill
96
+ filled = assessed(@placeholders.fetch("recent_decision"), members)
95
97
  @head.leading(@parts.filled_after({ "left_as_printed_rule" => @placeholders.fetch("left_as_printed_rule"),
96
- **filled, "findings" => [@placeholders.fetch("new_finding")] }))
98
+ **carried_checks_to_run(members), **check_instructions, **filled,
99
+ "findings" => [@placeholders.fetch("new_finding")] }))
97
100
  end
98
101
 
99
102
  private
100
103
 
104
+ # How to run and report each checked member's check, by its id, under check_instructions; nothing when no member
105
+ # has a check (#1191).
106
+ #: () -> Hash[String, untyped]
107
+ def check_instructions
108
+ instructions = @members.check_instructions
109
+ instructions.empty? ? {} : { "check_instructions" => instructions }
110
+ end
111
+
112
+ # The ids of the carried members whose template entry asks for a check_result, under carried_checks_to_run,
113
+ # or nothing when there are none.
114
+ #: (Array[Hash[String, untyped]]) -> Hash[String, Array[String]]
115
+ def carried_checks_to_run(members)
116
+ ids = members.select { it["carried_forward"] && it.key?("check_result") }.map { it.fetch("member_id") }
117
+ ids.empty? ? {} : { "carried_checks_to_run" => ids }
118
+ end
119
+
101
120
  # The answer's fields after its head and before its parts' slots, recent_decision and the members' templates as
102
121
  # given.
103
122
  #: (Hash[String, String], Array[Hash[String, untyped]]) -> Hash[String, untyped]
@@ -46,7 +46,7 @@ module Principles
46
46
  #| ?map_entry_changes: Array[Hash[String, untyped]]) -> Hash[String, untyped]
47
47
  def acceptable(request_id, would_write, answer_file:, open_findings_will_print: nil, map_entry_changes: [])
48
48
  submit = @invocation.submit_answer(request_id, file: answer_file)
49
- waits = "Submitting this answer writes nothing yet: the audit record is written when the audit completes.\n"
49
+ waits = "Submitting this answer writes nothing: the audit record already holds what it would write.\n"
50
50
  waits = "" unless would_write.empty?
51
51
  result = { "status" => "answer_acceptable", "request_id" => request_id, "would_write" => would_write }
52
52
  result = result.merge("open_findings_will_print" => open_findings_will_print) if open_findings_will_print
@@ -114,6 +114,14 @@ module Principles
114
114
  "The last audit's record, #{file}, is not committed. Commit it, so the project keeps it."
115
115
  end
116
116
 
117
+ # The notice start-audit adds, in git, when the last audit's record is open: its correction completes it, so it
118
+ # is never committed (D87).
119
+ #: (String) -> String
120
+ def open_record_notice(file)
121
+ "The last audit's record, #{file}, holds an open audit, waiting on its correction. Do not commit it: submit " \
122
+ "that correction, or answer this request, which replaces it, or discard it with `git restore #{file}`."
123
+ end
124
+
117
125
  # Wraps a known judgement request with this run's project and answer command.
118
126
  #: (Hash[String, untyped]) -> Hash[String, untyped]
119
127
  def request(output)