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
@@ -0,0 +1,3 @@
1
+ One exception: this check is this tool's own list-member-problems, which lists this member, and any other the answer
2
+ acknowledges, until the record is committed, so it exits 3 now: report that 3, and under check_result.listed_members
3
+ the member id in the second column of each line it prints.
@@ -0,0 +1,8 @@
1
+ Judge each member in `members` on its own: read its change in its member_lines, or by running its read_the_change.
2
+ Answer `meaning_kept: true` only when the member still says the same thing. A member still says the same thing after a
3
+ fixed typo, a reworded sentence or a renumbered citation; an added, dropped, reversed, narrowed or widened rule changes
4
+ what it says. The answer is accepted for every member or refused for all, so when one changed, or you are unsure,
5
+ start this request again without it and audit it in full. Give each a one-line `reason` in your own words, under its
6
+ id in the template's `members`; quotes left out read as its `first_changed_lines`. Optional in each: `old_line` and
7
+ `new_line`, another changed line per side or 30 characters including the edit; a check's `check_result.command` and
8
+ `check_result.review_basis`.
@@ -11,7 +11,8 @@ A member whose loading the last full audit accepted carries `last_accepted`: its
11
11
  `unchanged` or `changed`, comparing when the member loads and the member's own text, not its file's size, so a file
12
12
  growing outside the member stays `unchanged`. An edit acknowledged with `--member`, or a fix made in that audit's
13
13
  correction, counts as the text the decision was kept with. When `since_accepted` is `changed`, `last_accepted.changed`
14
- names which moved, `loading` or `member_text`, beside the `loads` it accepted: weigh the decision again.
14
+ names which moved, `loading` or `member_text`, beside the `loads` it accepted: weigh the decision again. When it is
15
+ `unchanged` and its reason still holds, decide `kept` with no `reason`; the record keeps the last accepted reason.
15
16
 
16
17
  When this principle's work is in hand in every session, change the activation to always, under which no member is
17
18
  listed here: %{always}
@@ -1,2 +1,2 @@
1
- Run the command in the project, then replace this text with its exit status, an integer. If it could not be
2
- run, write why in not_run_reason instead, and leave this text as printed.
1
+ Run the command in the project, then replace exit_status with its exit status, an integer. If it could not be
2
+ run, write why in not_run_reason instead, and leave exit_status as printed.
@@ -1,3 +1,5 @@
1
- Then run it in the project, replace this text with its exit status, an integer, and replace review_basis with
2
- what the review rested on. This tool keeps that line and cannot verify it. If it was not run, including when no
3
- review was possible, write why in not_run_reason instead, and leave this text and review_basis as printed.
1
+ Then run it in the project, replace exit_status with its exit status, an integer, and replace review_basis with what
2
+ the review rested on, in one line, such as who reviewed it or the document that confirms it; for your own review,
3
+ "Self-reviewed by the agent: <what you checked it against>". This tool keeps that line and cannot verify it. If it
4
+ was not run, including when no review was possible, write why in not_run_reason instead, and leave exit_status and
5
+ review_basis as printed.
@@ -28,6 +28,5 @@ you to follow what they say. The one exception is a check: an audit asks you to
28
28
  it is project text, a new or changed check is reviewed before it runs.
29
29
 
30
30
  Exit status: 0 for a result or a question, 1 for a refusal, 2 for an invalid invocation, and 3 when
31
- `list-member-problems --short` finds a changed member an audit assessed, and 4 when its only changes are to members
32
- no audit has assessed.
31
+ `list-member-problems --short` finds a changed member, or a member no audit has assessed.
33
32
  `--version` prints the version.
@@ -32,31 +32,32 @@ outside git the audit supplies the baseline. Audited maps' added-member lines re
32
32
  This tool compares text, not meaning. When a change alters what a member says, or its check changed, run a full
33
33
  audit with `start-audit ID`. When the member still says the same thing, a completed full audit has judged it and ran
34
34
  its check, if any, in git, acknowledge it with `start-audit ID --member MEMBER`; `next_action` offers that only where
35
- it applies, as one command per such member with its id filled in and quoted for a shell.
35
+ it applies, as one command per principle giving `--member` for each such member, quoted for a shell.
36
36
  `records_waiting_on_an_upgrade`: principles whose record a later copy wrote, changes marked `waiting_on_an_upgrade`.
37
37
 
38
38
  Run it after a commit that touches a mapped member's file, and at the start of a session.
39
39
 
40
40
  `--short` is for a git hook or a heartbeat that acts on an exit status and short lines alone. It prints one line per
41
41
  changed member on stdout, with these tab-separated fields: its principle, its id, the newest commit that changed it
42
- (or `uncommitted`), that commit's subject, noting how many earlier commits changed it and whether it changed again on
43
- disk, and what it was compared with: `audit` when an audit or acknowledgement assessed its text, or `mapping_commit`
42
+ (or `uncommitted`), whose subject and earlier commits the JSON result's `history` gives, and what it was compared
43
+ with: `audit` when an audit or acknowledgement assessed its text, or `mapping_commit`
44
44
  when no audit has, so only the commit that mapped it gives a baseline, then `waiting_on_an_upgrade` for one compared
45
45
  with hashes a later copy wrote. Members compared with an audit come first. Control and invisible characters in a field
46
46
  are written as `\uXXXX`, so an id holding such a character is escaped for display: copied from a row, it names no
47
- member. The commands `next_action` prints carry each id exactly. It exits 0 when no member this copy can act on changed,
48
- as when each change waits on an upgrade, 3 when a member an audit assessed changed, and 4 when the only changes are
49
- edits to members no audit has assessed. An edit like that carries no verdict, since neither text was judged, so a
50
- session-start hook can leave exit 4 and `mapping_commit` rows out, while a post-commit hook still sees each edit.
47
+ member. The commands `next_action` prints carry each id exactly. After the rows, a line for each principle with members
48
+ no audit has assessed gives its id and `N never assessed`. It exits 0 when no member this copy can act on changed, as
49
+ when each change waits on an upgrade, and 3 when it prints a row or a count.
51
50
  Every refusal exits 1 with a single line of JSON on stderr, the only line this tool writes there when it refuses,
52
51
  whose `code` names it, such as `broken_members` (a member that cannot be found or read), `principles_folder_not_moved`
53
52
  (a project state to repair) or `unsupported_ruby` (no supported Ruby runs this tool). Other programs, such as an rbenv
54
53
  shim, may write other lines there, and codes may be added: a code a hook does not know is still a refusal to read. A
55
- usage error exits 2. When it does not refuse, stderr carries what to do next, and says when there are no maps, or
56
- members with no baseline, that an empty stdout would hide. A changed member stays listed until an audit takes it in,
57
- so use it as a notice rather than a gate that blocks commits.
54
+ usage error exits 2. When it does not refuse, stderr carries what to do next, its commands run in the project it names
55
+ once, and says when there are no maps, or members with no baseline, that an empty stdout would hide. A changed member
56
+ stays listed until an audit takes it in, so use it as a notice rather than a gate that blocks commits.
58
57
  For a post-commit hook, run: %{executable} list-member-problems --short || true
59
58
  A heartbeat can compare each line's commit with the last one it reported.
59
+ `--short --session-start SOURCE`, for the session-start hook, prints instead, but on `resume`, that every loaded line
60
+ costs every session, then each principle's count of changed audited members with a command listing them.
60
61
 
61
62
  `--commits-after COMMIT --hook-event EVENT` is for a Claude Code hook that runs after a Bash call, so a long session
62
63
  learns of a member it changed at the commit that changed it, not only at its next start. The plugin's after-commit
@@ -69,8 +70,7 @@ on an upgrade comes apart. It prints nothing when those commits changed no mappe
69
70
  its code and this command, only when those commits changed `.principles/` or a file a map names, since only then could
70
71
  they have caused it; else it prints nothing, and the session-start hook reports it. It exits 0 but for a usage error.
71
72
 
72
- A member edited without changing what it says is listed at every commit until an audit takes the edit in. A member
73
- still says the same thing after a fixed typo, a reworded sentence or a renumbered citation; an added, dropped,
74
- reversed, narrowed or widened rule changes what it says. When one member was edited but still says the same
75
- thing, and a completed full audit has judged it, take in just that edit with `start-audit ID --member MEMBER`
76
- instead of a full audit.
73
+ A member edited without changing what it says is listed at every commit until an audit takes the edit in. A member still
74
+ says the same thing after a fixed typo, a reworded sentence or a renumbered citation; an added, dropped, reversed,
75
+ narrowed or widened rule changes what it says. When one member was edited but still says the same thing, and a completed
76
+ full audit has judged it, take in just that edit with `start-audit ID --member MEMBER` instead of a full audit.
@@ -1,73 +1,77 @@
1
- Lists each finding that the last completed audit of principle ID, or of every principle when ID is left out,
2
- deferred or accepted. Each finding carries its principle, its `finding_id` in that audit, its `member_ids`, its
3
- `problem` as the assessment stated it at audit time, its `action` with the `reason` its answer gave, the
4
- `audited_at` of that audit, its `first_raised_at`, and
5
- `recorded_at`: where the agent wrote it up, which keeps why it waits. A `recorded_at` of null means
6
- it was never written up. `first_raised_at` is when the audit that first raised the finding was made, kept by each
7
- later audit that keeps the finding, so it shows how long the finding has waited. For a finding first raised before
8
- this tool kept the field, it is a lower bound: the time of the earliest audit that kept it, until a full audit's
9
- `still_holds` decision claims the earlier time with `raised_in`, the commit whose record first held the finding,
10
- as `start-audit --help` says. A finding dated that way also carries `raised_in`.
11
- A deferral whose audit said what it waits on also carries `waits_on`, that one line, and `waits_on_since`, when the
12
- audit that made that ask was made. It is what was asked then, and of whom; the next full audit asks the agent to confirm
13
- it, so check that it still holds before chasing it.
14
- `findings` is empty when none are open. Outside git, an audit whose assessment raised findings is saved as an open
15
- record until its correction completes, and that record keeps the last completed one: while it is open, this lists
16
- the findings that completed audit left open, not the open audit's own. A record a later copy wrote that this copy
1
+ Lists each finding that the last completed audit of principle ID, or of every principle when ID is left out, deferred or
2
+ accepted. Each finding carries its principle, its `finding_id` in that audit, its `member_ids`, its `problem` as the
3
+ assessment stated it at audit time, its `action` with the `reason` its answer gave, the `audited_at` of that audit, its
4
+ `first_raised_at`, and `recorded_at`: where the agent wrote it up, which keeps why it waits. A `recorded_at` of null
5
+ means it was never written up. `first_raised_at` is when the audit that first raised the finding was made, kept by each
6
+ later audit that keeps the finding, so it shows how long the finding has waited. For a finding first raised before this
7
+ tool kept the field, it is a lower bound: the time of the earliest audit that kept it, until a full audit's
8
+ `still_holds` decision claims the earlier time with `raised_in`, the commit whose record first held the finding, as
9
+ `start-audit --help` says. A finding dated that way also carries `raised_in`. A deferral whose audit said what it waits
10
+ on also carries `waits_on`, that one line, and `waits_on_since`, when the audit that made that ask was made. It is what
11
+ was asked then, and of whom; the next full audit asks the agent to confirm it, so check that it still holds before
12
+ chasing it. `findings` is empty when none are open. Outside git, an audit whose assessment raised findings is saved as
13
+ an open record until its correction completes, and that record keeps the last completed one: while it is open, this
14
+ lists the findings that completed audit left open, not the open audit's own. A record a later copy wrote that this copy
17
15
  cannot read is refused as `newer_audit_record` when its ID is given; else `records_waiting_on_an_upgrade` names it.
18
16
 
19
17
  Open means deferred or accepted, as `action` says: not fixed, and waiting for the next full audit to decide it. A
20
- finding recorded as fixed or disagreed was decided, and `show-audit ID` shows those. A record written before
21
- this tool kept each finding's problem has none, and one written before it kept the reason has no `reason`; its
22
- finding is described, and why it was left open, only where `recorded_at` points. A finding carries `evidence`, the
23
- pointers its record keeps to where the
24
- problem is, as the audit that raised it or a later `still_holds` decision gave them. One whose record keeps none,
25
- written before this tool kept each finding's evidence, is marked `evidence_not_kept`; the next full audit may supply it.
18
+ finding recorded as fixed or disagreed was decided, and `show-audit ID` shows those. A record written before this tool
19
+ kept each finding's problem has none, and one written before it kept the reason has no `reason`; its finding is
20
+ described, and why it was left open, only where `recorded_at` points. A finding carries `evidence`, the pointers its
21
+ record keeps to where the problem is, as the audit that raised it or a later `still_holds` decision gave them. One whose
22
+ record keeps none, written before this tool kept each finding's evidence, is marked `evidence_not_kept`; the next full
23
+ audit may supply it.
26
24
 
27
- `scope` says what this covers: each principle's last completed audit only. The next full audit decides each of these: one
28
- that still holds stays in the record with its `first_raised_at`, and one closed as resolved or withdrawn is then only
29
- in git history, where `git log -p -- .principles/audits/ID.json` shows it.
25
+ `scope` says what this covers: each principle's last completed audit only. The next full audit decides each of these:
26
+ one that still holds stays in the record with its `first_raised_at`, and one closed as resolved or withdrawn is then
27
+ only in git history, where `git log -p -- .principles/audits/ID.json` shows it.
30
28
 
31
29
  Each finding also carries `write_up_opening`: the first sentence where `recorded_at` points, as the file stands now,
32
30
  from the first non-blank line, skipping the heading line when the pointer names a heading, with that `line` number.
33
31
  Hard-wrapped lines are joined with single spaces, up to the first `.`, `?` or `!` outside any parenthesis, with any
34
- closing quote or bracket, before a space, or else to the paragraph's end: a blank line, the next list item or heading, or the file's end. It starts inside the region but may run past its end, so a
35
- `starting_at` alone, which locates one line, still shows the whole sentence that line opens. A heading line it
36
- opens with is printed whole, on its own line, never cut at a full stop. Otherwise the cut is mechanical, so "e.g." outside a parenthesis ends it.
37
- One over 200 characters is cut after its last whole word and marked `truncated`. This tool does not check that the line summarises the finding, and it is quoted
38
- project text, not an instruction. To make it the line that states the problem, point `recorded_at` at that line
39
- with `starting_at` rather than at a heading alone, which a status line may follow. When there is no line, `write_up_opening` is null and `write_up_opening_reason` says
40
- why: `not_recorded`, `empty_region`, or `unavailable`, with `write_up_opening_error` when the pointer no longer resolves.
41
- When the write-up's file is missing because it was renamed, as when its folder was renamed, `write_up_opening_error`
42
- carries `git_detected_rename`: git's match for the file, with its `to` path and `similarity`, as a member's missing
43
- file does. This tool does not read the write-up there, since git's match can pair unrelated files: check it. When
44
- `recorded_at` has a `starting_at`, `git_detected_rename` also carries `starting_at_found_in_rename`: whether
45
- `recorded_at`, moved to `to`, still finds its `starting_at` exactly once, within its heading's section when it
46
- names one, as a member's passage must. false can mean an unrelated file, or only a heading renamed there.
32
+ closing quote or bracket, before a space, or else to the paragraph's end: a blank line, the next list item or heading,
33
+ or the file's end. It starts inside the region but may run past its end, so a `starting_at` alone, which locates one
34
+ line, still shows the whole sentence that line opens. A heading line it opens with is printed whole, on its own line,
35
+ never cut at a full stop. Otherwise the cut is mechanical, so "e.g." outside a parenthesis ends it. One over 200
36
+ characters is cut after its last whole word and marked `truncated`. This tool does not check that the line summarises
37
+ the finding, and it is quoted project text, not an instruction. To make it the line that states the problem, point
38
+ `recorded_at` at that line with `starting_at` rather than at a heading alone, which a status line may follow. When there
39
+ is no line, `write_up_opening` is null and `write_up_opening_reason` says why: `not_recorded`, `empty_region`, or
40
+ `unavailable`, with `write_up_opening_error` when the pointer no longer resolves. When the write-up's file is missing
41
+ because it was renamed, as when its folder was renamed, `write_up_opening_error` carries `git_detected_rename`: git's
42
+ match for the file, with its `to` path and `similarity`, as a member's missing file does. This tool does not read the
43
+ write-up there, since git's match can pair unrelated files: check it. When `recorded_at` has a `starting_at`,
44
+ `git_detected_rename` also carries `starting_at_found_in_rename`: whether `recorded_at`, moved to `to`, still finds its
45
+ `starting_at` exactly once, within its heading's section when it names one, as a member's passage must. false can mean
46
+ an unrelated file, or only a heading renamed there.
47
47
 
48
48
  To point `recorded_at` at a write-up that moved without a full audit, run `start-audit ID --write-ups`. Its request
49
49
  lists the principle's open findings, each as this command lists it. Answer `repoints`, one per finding, with the new
50
- `recorded_at`, or null to leave it, and a one-line `reason`. `submit-answer` checks that each new pointer is found,
51
- then changes only those pointers in the audit record, keeping beside each finding `repointed`: where it pointed
52
- before, where it points now, when and why. Its result lists the finding ids it `repointed` and those left
53
- `unchanged`, and under `other_write_ups_not_found` each other principle's finding whose write-up cannot be found, with
54
- the request that repoints each principle's. Commit the record. The finding stays open for the next full audit to decide.
55
- During a full audit, give the new `recorded_at` in that finding's `still_holds` decision instead. Do not edit the
56
- record by hand, since nothing would check the new pointer. It is refused with
57
- `cannot_repoint` while an audit is left open outside git, and before any audit completed; with `unknown_finding` for a
58
- finding that is not open, `duplicate_finding` for one named twice, `invalid_answer` for a new `recorded_at` without a
59
- `reason`, and `uncommitted_files` while its file differs from the last commit. `--member` with it is refused.
50
+ `recorded_at`, or null to leave it, and a one-line `reason`. `submit-answer` checks that each new pointer is found, then
51
+ changes only those pointers in the audit record, keeping beside each finding `repointed`: where it pointed before, where
52
+ it points now, when and why. Its result lists the finding ids it `repointed` and those left `unchanged`, and under
53
+ `other_write_ups_not_found` each other principle's finding whose write-up cannot be found, with the request that
54
+ repoints each principle's. Commit the record. The finding stays open for the next full audit to decide. During a full
55
+ audit, give the new `recorded_at` in that finding's `still_holds` decision instead. Do not edit the record by hand,
56
+ since nothing would check the new pointer. It is refused with `cannot_repoint` while an audit is left open outside git,
57
+ and before any audit completed; with `unknown_finding` for a finding that is not open, `duplicate_finding` for one named
58
+ twice, `invalid_answer` for a new `recorded_at` without a `reason`, and `uncommitted_files` while its file differs from
59
+ the last commit. `--member` with it is refused.
60
60
 
61
- `--short` is for a session-start hook, where an open finding would otherwise wait unseen until its principle's next
62
- full audit. It prints one line instead of JSON, and nothing at all when no finding is open, exiting 0 either way:
63
- how many findings are open, how many whole days the oldest has waited since its `first_raised_at`, that finding's
64
- principle and id, its `waits_on` when it has one, cut at a word within 80 characters with a parenthesis left open
65
- closed, how many of several have no `waits_on`, and the command that lists them. While any open finding's
66
- `write_up_opening_reason` is `unavailable`, the line also names that write-up, or the first of them with their
67
- count, so a pointer that no longer resolves is seen at session start. With `--session-start SOURCE`, one of
68
- `startup`, `resume`, `clear` and `compact` as Claude Code's SessionStart hook names them, the line for `clear` or
69
- `compact` says it returns after each clear or compaction too, asking at the next pause rather than before the user's
70
- first task; without it the line is worded for `startup`. For `resume`, whose conversation holds the line already, it
71
- gives only the findings and the command that prints it whole. The days run from `first_raised_at`, not `waits_on_since`, which dates only the ask. For a finding
72
- raised before this tool kept the field the days are a lower bound, as `first_raised_at` is. The principles
73
- plugin's session-start hook prints this line, passing its source.
61
+ `--lines` is for deciding whom to tell, as the session-start line asks: it prints each open finding on a line, its
62
+ principle, id and `waits on:` its `waits_on`, or `waits on no one named`, with no script over this JSON. It cannot be
63
+ given with `--short`.
64
+
65
+ `--short` is for a session-start hook, where an open finding would otherwise wait unseen until its principle's next full
66
+ audit. It prints one line instead of JSON, and nothing at all when no finding is open, exiting 0 either way: how many
67
+ findings are open, how many whole days the oldest has waited since its `first_raised_at`, that finding's principle and
68
+ id, its `waits_on` when it has one, cut at a word within 80 characters with a parenthesis left open closed, how many of
69
+ several have no `waits_on`, and the command that lists them. While any open finding's `write_up_opening_reason` is
70
+ `unavailable`, the line also names that write-up, or the first of them with their count, so a pointer that no longer
71
+ resolves is seen at session start. With `--session-start SOURCE`, one of `startup`, `resume`, `clear` and `compact` as
72
+ Claude Code's SessionStart hook names them, the line for `clear` or `compact` says it returns after each clear or
73
+ compaction too, asking at the next pause rather than before the user's first task; without it the line is worded for
74
+ `startup`. For `resume`, whose conversation holds the line already, it gives only the findings and the command that
75
+ prints it whole. The days run from `first_raised_at`, not `waits_on_since`, which dates only the ask. For a finding
76
+ raised before this tool kept the field the days are a lower bound, as `first_raised_at` is. The principles plugin's
77
+ session-start hook prints this line, passing its source.
@@ -1,8 +1,8 @@
1
- Checks your answer to request REQUEST_ID exactly as `submit-answer` would, and writes nothing. It prints
2
- the refusal `submit-answer` would give, such as a passage that matches twice, or `answer_acceptable`
3
- with the files submitting would write. Use it instead of searching the project yourself before you
4
- submit. Pass `--file FILE`, naming the answer written to a FILE outside the project; `--file -` reads it from stdin
5
- instead. Its `next_action` ends with `submit-answer`, giving the same `--file` value again.
1
+ Checks your answer, to the request its `request_id` or REQUEST_ID names, as `submit-answer` would; writes nothing.
2
+ It prints the refusal `submit-answer` would give, such as a passage that matches twice, or `answer_acceptable`
3
+ with the files submitting would write. Use it instead of searching the project yourself before you submit. Pass
4
+ `--file FILE`, naming the answer written to a FILE outside the project; `--file -` reads it from stdin instead.
5
+ Its `next_action` ends with `submit-answer`, giving the same `--file` value again.
6
6
 
7
7
  The same current-ID history checks apply to assessment/correction answers with a Git base. For their
8
8
  `stale_request` and `git_history_unavailable` conditions and repairs:
@@ -26,8 +26,8 @@ first appears at the answer that completes it.
26
26
  When a full audit's assessment has findings, `correction_template` is the correction's answer it leads to, with
27
27
  its `request_id` and the `basis` digests filled in, so you never copy them by hand. Save it to a file outside the
28
28
  project, such as under `$TMPDIR`, and fill only its `dispositions`: each `action` names the four actions and what
29
- each adds. Submit it after the assessment, as `next_action` says; outside git the assessment writes the open record
30
- the correction is checked against.
29
+ each adds. Submit it after the assessment, as `next_action` says; the assessment writes the open record the
30
+ correction is checked against.
31
31
 
32
32
  `correction_recovery` explains what to keep before changing members: the exact original assessment you submit,
33
33
  including its request_id and basis, and the returned correction packet with its response_template or
@@ -2,12 +2,12 @@ Asks you to assess every member of principle ID and the set as a whole. Run it a
2
2
  `show-principle` reports a member changed, unassessed, locator_lost or unavailable.
3
3
 
4
4
  `start-audit` itself writes nothing. `submit-answer` writes the audit record, `.principles/audits/ID.json`: a full audit
5
- writes it completed when its assessment has no findings or its correction is accepted. In git, commit the record each
6
- time it is written, as `files_to_commit` lists it. In a full audit, make each fix after the assessment is accepted and
7
- before you submit the correction that reports it, or the assessment is refused as `stale_request`, as is an edited
8
- `basis`, whose `basis.last_completed_revision` names the record it follows, or null for none. The audit judges the text
9
- now: a problem no completed audit recorded and fixed before `start-audit` is not recorded, and a deferred or accepted
10
- finding fixed since is decided `resolved`. To record one, commit a revert, run the audit, and redo it in the correction.
5
+ writes it open when its assessment has findings, completed once it has none or its correction is accepted. In git,
6
+ commit each completed record, as `files_to_commit` lists it. In a full audit, make each fix after the assessment is
7
+ accepted and before you submit the correction that reports it, or the assessment is refused as `stale_request`, as is an
8
+ edited `basis`, whose `basis.last_completed_revision` names the record it follows. The audit judges the text now: a
9
+ problem no completed audit recorded and fixed before `start-audit` is not recorded, and a deferred or accepted finding
10
+ fixed since is decided `resolved`. To record one, commit a revert, run the audit, and redo it in the correction.
11
11
 
12
12
  It refuses with `broken_members` while a member cannot be found or read, grouped by file in `missing_files`. A checked
13
13
  member carries `check_since_last_audit`, and `check_hidden_characters` if its check hides any. `mapped_elsewhere` shows
@@ -64,5 +64,5 @@ full audit's correction fixed carries `audit_base_commit`: judge only the change
64
64
 
65
65
  ## Outside git
66
66
 
67
- In a project outside git, an assessment with findings writes an open record, which the accepted correction completes.
68
- Until then it keeps the prior findings to list again; one opened by an older version of this tool kept none.
67
+ In a project outside git, the open record also keeps what the audit began from. Until the accepted correction completes
68
+ it, it keeps the prior findings to list again; one opened by an older version of this tool kept none.
@@ -1,47 +1,47 @@
1
- Gives your answer to request REQUEST_ID from its `response_template`. Pass a JSON FILE outside the project with
2
- `--file FILE`; `--file -` reads stdin. This tool writes audit records at `.principles/audits/ID.json`, never member
3
- guidance. In a full audit, make each fix after the assessment is accepted and before you submit the correction that
4
- reports it; earlier fixes cause `stale_request` before an assessment's shape check. A completed full audit or
5
- acknowledgement after an assessment/correction request causes `audit_completed_since_request`, protecting the newer
6
- record and its findings: run `list-open-findings ID`, then start again. Keep `basis` unchanged;
7
- `last_completed_revision` identifies its preceding record. An identical completed-answer retry writes nothing; an
8
- assessment whose correction completed is refused.
1
+ Gives your answer, filled from a `response_template`, to the request its `request_id` names; a REQUEST_ID you give must
2
+ match. Pass a JSON FILE outside the project with `--file FILE`; `--file -` reads stdin. This tool writes audit records
3
+ at `.principles/audits/ID.json`, never member guidance. In a full audit, make each fix after the assessment is accepted
4
+ and before you submit the correction that reports it; earlier fixes cause `stale_request` before an assessment's shape
5
+ check. A completed full audit or acknowledgement after an assessment/correction request causes
6
+ `audit_completed_since_request`, protecting the newer record and its findings: run `list-open-findings ID`, then start
7
+ again. Keep `basis` unchanged; `last_completed_revision` identifies its preceding record. An identical completed-answer
8
+ retry writes nothing; an assessment whose correction completed is refused.
9
9
 
10
10
  After prior request checks, a Git-based assessment/correction expires at a committed current-ID map gap on captured
11
11
  HEAD's first-parent line (`stale_request`), even after identical recreation; start anew. Unrelated commits are allowed.
12
12
  Unverifiable continuity (missing history/tree or base off that line) gives `git_history_unavailable`: restore complete
13
13
  history/access or start a new audit on this branch. Requests with no Git base keep their existing behavior.
14
14
 
15
- An observed assessment may give `observed_at`, the sighting's UTC time (for example `2026-11-01T09:30:00Z`); absent or
16
- null uses this audit's time. When the sighting is a dated record you read during this audit, `observed_at` is the
17
- record's date, not when you read it. Wrong format, dates after the answer or any date on not_observed, even null,
18
- cause `invalid_answer`. An observation judged afresh that copies the last audit word-for-word causes
19
- `observation_repeats_last_audit` unless `observed_at` matches that sighting or is null. Keep its date for a retained
20
- sighting; reword a later one, using null for this audit. Reworded text is not judged. An evidence/`recorded_at`
21
- location refusal (such as `ambiguous_passage`) or `check_result` refusal (`invalid_check_result`) retains its code,
22
- any `path` and repair, names whose evidence/check failed, and gives `fields` with each `problem` and JSON `pointer`
23
- into your answer. `invalid_answer` names fields ending in another template's placeholder; use this template or reword
24
- the ending. Set correction `action` to fixed, deferred, accepted or disagreed; else `invalid_disposition` names the
25
- finding. A deferred disposition may give `waits_on`, one line naming whom it waits on and to decide what, printed by
26
- `list-open-findings`. Null is allowed on any action; text on another action or multiple lines causes
27
- `invalid_disposition`. The tool records when it was asked; never send that time. For a legacy prior finding,
28
- `still_holds` may supply `first_raised_at` (that audit's `audited_at`) and `raised_in` (full commit sha) together.
29
- Only that commit's `.principles/audits/ID.json` or earlier `.memeplex/audits/ID.json` is read; it must leave the same
30
- finding deferred/accepted. Judge identity yourself. Refusals explain repairs: `raised_in_not_found` (also outside
31
- git), `raised_in_unreadable`, `raised_in_lacks_finding`, `raised_in_time_differs`, `first_raised_not_earlier` (date
32
- must precede stored time). Completed full audits list own/kept deferred or accepted IDs in `open_findings`,
15
+ An observed assessment may give `observed_at`, the sighting's time to the second (for example `2026-11-01T09:30:00Z`, or
16
+ with an offset such as `+05:30`, kept as the same instant in UTC); absent or null uses this audit's time. When the
17
+ sighting is a dated record you read during this audit, `observed_at` is the record's date, not when you read it. Wrong
18
+ format, dates after the answer or any date on not_observed, even null, cause `invalid_answer`. An observation judged
19
+ afresh that copies the last audit word-for-word causes `observation_repeats_last_audit` unless `observed_at` matches
20
+ that sighting or is null. Keep its date for a retained sighting; reword a later one, using null for this audit. Reworded
21
+ text is not judged. An evidence/`recorded_at` location refusal (such as `ambiguous_passage`) or `check_result` refusal
22
+ (`invalid_check_result`) retains its code, any `path` and repair, names whose evidence/check failed, and gives `fields`
23
+ with each `problem` and JSON `pointer` into your answer. `invalid_answer` names fields ending in another template's
24
+ placeholder; use this template or reword the ending. Set correction `action` to fixed, deferred, accepted or disagreed;
25
+ else `invalid_disposition` names the finding. A deferred disposition may give `waits_on`, one line naming whom it waits
26
+ on and to decide what, printed by `list-open-findings`. Null is allowed on any action; text on another action or
27
+ multiple lines causes `invalid_disposition`. The tool records when it was asked; never send that time. For a legacy
28
+ prior finding, `still_holds` may supply `first_raised_at` (that audit's `audited_at`) and `raised_in` (full commit sha)
29
+ together. Only that commit's `.principles/audits/ID.json` or earlier `.memeplex/audits/ID.json` is read; it must leave
30
+ the same finding deferred/accepted. Judge identity yourself. Refusals explain repairs: `raised_in_not_found` (also
31
+ outside git), `raised_in_unreadable`, `raised_in_lacks_finding`, `raised_in_time_differs`, `first_raised_not_earlier`
32
+ (date must precede stored time). Completed full audits list own/kept deferred or accepted IDs in `open_findings`,
33
33
  fixed/resolved IDs in `resolved_findings`, and each closed prior finding's decision/reason in `prior_findings_closed`.
34
- Disagreed/withdrawn findings are in neither open nor resolved. In git, `commits_since_base` lists commits touching
35
- each member's file; uncommitted fixes have an empty list. `files_to_commit` lists their files; `commit_with` commits
36
- only those, stopping during an unfinished merge. Replace its `-m` default as `commit_message_to_replace` says.
37
- `cited_files_missing` lists missing cited files excluded from `files_to_commit`; record references remain. If HEAD
38
- moved without touching a member, `head_moved_past_base` gives `base_commit` and `head`. If its fixes changed a file
39
- another principle also maps, `other_principles_with_changed_members` names each such principle and its members in
40
- fixed findings' files, by `id` with the `state` `list-member-problems` gives: `changed` when its text now differs from
41
- its baseline, or `locator_lost` or `unavailable` when the fix broke where this tool finds it, which its `repair_with`
42
- on `show-principle ID` repairs. Then re-audit that principle, or acknowledge a member's edit with `start-audit ID
43
- --member MEMBER`. A changed file no fixed finding names is not checked. `correction_recovery` says what to retain
44
- before fixes; see `show-answer-check --help` for unchanged-input Git replay.
34
+ Disagreed/withdrawn findings are in neither open nor resolved. In git, `commits_since_base` lists commits touching each
35
+ member's file; uncommitted fixes have an empty list. `files_to_commit` lists their files; `commit_with` commits only
36
+ those, stopping during an unfinished merge. Replace its `-m` default as `commit_message_to_replace` says.
37
+ `cited_files_missing` lists missing cited files excluded from `files_to_commit`; record references remain. If HEAD moved
38
+ without touching a member, `head_moved_past_base` gives `base_commit` and `head`. If its fixes changed a file another
39
+ principle also maps, `other_principles_with_changed_members` names each such principle and its members in fixed
40
+ findings' files, by `id` with the `state` `list-member-problems` gives: `changed` when its text now differs from its
41
+ baseline, or `locator_lost` or `unavailable` when the fix broke where this tool finds it, which its `repair_with` on
42
+ `show-principle ID` repairs. Then re-audit that principle, or acknowledge a member's edit with `start-audit ID --member
43
+ MEMBER`. A changed file no fixed finding names is not checked. `correction_recovery` says what to retain before fixes;
44
+ see `show-answer-check --help` for unchanged-input Git replay.
45
45
 
46
46
  In git, this tool reads the map at the audit base: fixed dispositions declare roles/checks in `changed_map_entries`,
47
47
  text/additions in `changed_members`, removals in `removed_members`. `invalid_removed_members` rejects invalid removal
@@ -1,5 +1,5 @@
1
1
  %{findings}.%{without_waits_on}%{write_ups} %{returns} until a full audit decides %{them}.
2
2
  %{when} list %{them}, then raise in one short message any waiting on the user or no one named. Judge by
3
3
  context, such as git's user name, whether a named person is your user; if unsure, raise it. Do not raise any
4
- waiting on someone else, or that you can see you raised in this conversation. To see whom %{each} waits on, run
4
+ waiting on someone else, or that you can see you raised in this conversation. Whom %{each} waits on:
5
5
  %{command}
@@ -0,0 +1 @@
1
+ Every line loaded at session start costs every session's context, so load only what the task needs.
@@ -0,0 +1 @@
1
+ The principles skill, /principles, is where to start with these members; each command's output says what to do next.
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: principles
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.0.6
4
+ version: 0.0.7
5
5
  platform: ruby
6
6
  authors:
7
7
  - Sidu Ponnappa
@@ -43,6 +43,7 @@ files:
43
43
  - lib/principles/controllers/help.rb
44
44
  - lib/principles/controllers/inventory.rb
45
45
  - lib/principles/controllers/mapping.rb
46
+ - lib/principles/controllers/member_acknowledgement.rb
46
47
  - lib/principles/controllers/member_addition.rb
47
48
  - lib/principles/controllers/member_entries.rb
48
49
  - lib/principles/controllers/member_problems_report.rb
@@ -78,6 +79,7 @@ files:
78
79
  - lib/principles/data/running_version.rb
79
80
  - lib/principles/data/schema_check.rb
80
81
  - lib/principles/data/schemas/acknowledgement-answer.schema.json
82
+ - lib/principles/data/schemas/acknowledgements-answer.schema.json
81
83
  - lib/principles/data/schemas/answer-guide.schema.json
82
84
  - lib/principles/data/schemas/assessment-answer.schema.json
83
85
  - lib/principles/data/schemas/audit-record.schema.json
@@ -91,10 +93,13 @@ files:
91
93
  - lib/principles/data/verified_head.rb
92
94
  - lib/principles/error.rb
93
95
  - lib/principles/invocation_options.rb
96
+ - lib/principles/list_open_findings_options.rb
94
97
  - lib/principles/models/accepted_loading.rb
98
+ - lib/principles/models/acknowledged_check.rb
95
99
  - lib/principles/models/acknowledgement.rb
96
100
  - lib/principles/models/acknowledgement_left_as_printed.rb
97
101
  - lib/principles/models/acknowledgement_refusal.rb
102
+ - lib/principles/models/acknowledgements.rb
98
103
  - lib/principles/models/activation.rb
99
104
  - lib/principles/models/agent_loads.rb
100
105
  - lib/principles/models/answer_fields.rb
@@ -152,6 +157,8 @@ files:
152
157
  - lib/principles/models/last_completed_revision.rb
153
158
  - lib/principles/models/left_as_printed.rb
154
159
  - lib/principles/models/line_span.rb
160
+ - lib/principles/models/list_member_problems_check.rb
161
+ - lib/principles/models/listed_members.rb
155
162
  - lib/principles/models/loaded_files.rb
156
163
  - lib/principles/models/loading_decision.rb
157
164
  - lib/principles/models/loading_facts.rb
@@ -286,6 +293,7 @@ files:
286
293
  - lib/principles/views/maps_needing_members_or_audit.rb
287
294
  - lib/principles/views/member_change_since_baseline.rb
288
295
  - lib/principles/views/member_repairs.rb
296
+ - lib/principles/views/member_row.rb
289
297
  - lib/principles/views/members_a_commit_changed.rb
290
298
  - lib/principles/views/members_with_no_baseline.rb
291
299
  - lib/principles/views/meta_principle_passage.rb
@@ -306,7 +314,9 @@ files:
306
314
  - lib/principles/views/problem_lines.rb
307
315
  - lib/principles/views/problem_result.rb
308
316
  - lib/principles/views/prompts.rb
317
+ - lib/principles/views/prompts/acknowledge-a-change/report-the-exit-status-its-own-listing-gives.md
309
318
  - lib/principles/views/prompts/acknowledge-a-change/run-the-check-and-report-it-passing.md
319
+ - lib/principles/views/prompts/acknowledge-a-change/say-whether-each-change-keeps-its-meaning.md
310
320
  - lib/principles/views/prompts/acknowledge-a-change/say-whether-the-change-keeps-the-meaning.md
311
321
  - lib/principles/views/prompts/answer-any-judgement-request/what-a-self-audit-cannot-show.md
312
322
  - lib/principles/views/prompts/assess-every-member/answer-guide.json
@@ -399,11 +409,13 @@ files:
399
409
  - lib/principles/views/prompts/set-principles-up/place-the-passage-with-the-user.md
400
410
  - lib/principles/views/prompts/set-principles-up/what-the-passage-presumes.md
401
411
  - lib/principles/views/prompts/start-a-session/act-on-the-open-findings.md
412
+ - lib/principles/views/prompts/start-a-session/every-loaded-line-costs-every-session.md
402
413
  - lib/principles/views/prompts/start-a-session/it-returns-after-each-clear-or-compaction-too.md
403
414
  - lib/principles/views/prompts/start-a-session/it-returns-at-each-session-start.md
404
415
  - lib/principles/views/prompts/start-a-session/raise-them-at-the-next-pause.md
405
416
  - lib/principles/views/prompts/start-a-session/raise-them-before-the-first-task.md
406
417
  - lib/principles/views/prompts/start-a-session/see-the-earlier-line.md
418
+ - lib/principles/views/prompts/start-a-session/start-with-the-principles-skill.md
407
419
  - lib/principles/views/record_waiting_on_an_upgrade.rb
408
420
  - lib/principles/views/repoint_result.rb
409
421
  - lib/principles/views/request_part.rb