principles 0.0.1

data/lib/principles/views/prompts/learn-what-a-command-does/show-principle.md

@@ -0,0 +1,86 @@
+Shows each member of principle ID, where its text is now and whether it changed since the last audit. Audit when a
+member is changed, unassessed, locator_lost or unavailable. A member that is locator_lost or unavailable carries
+`repair_with`: a `move-member` with its `NEW_PATH`, `HEADING` or `QUERY` to fill in, for a section or passage a
+second `move-member` for text moved into another file, and a `remove-member`. Run the one that fits;
+`next_action` names those members.
+
+Each member's `loads` says, for each host this tool derives, when that host loads the member's file into the agent's
+context. Only `claude_code` is derived; Codex is not yet. The derivation follows Claude Code's documented loading
+from the file's path alone, for a session started at the project root, not what loaded in any session:
+
+- `session_start`: the project's `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md`, in every session.
+- `on_files` with `files`: one of those files in a folder below the root, once a file in that folder is read,
+  written or edited.
+- `session_start` too: a rule in `.claude/rules/`, or a folder within it, without a `paths` field in its
+  frontmatter.
+- `on_files` with `paths_field`: a rule with a `paths` field, once a file it matches is read, written or edited.
+  `paths_field` is the field's lines as written; this tool does not read the globs, so read them yourself.
+- `on_invocation`: a skill's `SKILL.md` in `.claude/skills/NAME/`, whose body loads when the skill is invoked.
+  `invoked_by` is `model_or_person`, or `person` when its frontmatter says `disable-model-invocation: true`, so only
+  a person's `/NAME` invokes it. This tool reads that field only as a plain `true` or `false` on its line.
+  `description` says when the skill's description, which tells the model the skill exists, loads: `session_start`;
+  `on_files` with `paths_field`, for a skill with a `paths` field; `on_files` with `files`, for a skill in a folder
+  below the root; or `not_loaded`, for a skill only a person invokes. Other files in a skill's folder are
+  `no_known_carrier`: the skill's body may tell the agent to read them. A member that is the skill's description
+  field, by a query that names its `description` field such as `$.description`, has `skill_part: description` and
+  the description's moment as its own `when`, with only its own `member_bytes`, since the file's size is the body's
+  cost; any other frontmatter field's member gets the body's answer.
+- `on_delegation` with `context: subagent`: a subagent's definition, a `.md` file at any depth in `.claude/agents/`.
+  Its body is the subagent's own system prompt, loaded in the subagent's context, not the main session's, when
+  Claude delegates to it; `description` is `session_start`, since Claude reads every subagent's description to
+  decide when to delegate. An agents folder below the root, or an agent file without a `description` field, such as
+  a note kept beside the agents, is `not_determined`.
+- `not_determined`: This tool knows the file is a rule, a skill or an agent but not when it loads.
+  `frontmatter_refused` names the code this tool refused its frontmatter with, so read the frontmatter; `not_derived`
+  names a kind it does not derive yet, such as a rules folder below the project root.
+- `no_known_carrier`: This tool knows no Claude Code facility that loads this path by itself. An `@` import from
+  another instruction file, or a user-level file, may still load it; read the importing file to check.
+
+Whatever `when` says, `named_in_hooks` lists each project hook whose command names the member's file: its `settings`
+file, `event`, `matcher` (left out when the event has none), and `command` and `args` as written. A command names
+the file when it or one of its args gives the file's path from the project root, bare or after
+`$CLAUDE_PROJECT_DIR`; a path reached another way, such as after a `cd`, is not recognised. This tool does not run
+the command, so a name is not proof the hook runs the file, and it says nothing of whether the hook's output reaches
+context: that depends on the event and on what the command prints, so read the event in Claude Code's hooks
+documentation and the script. It reads only command handlers in `.claude/settings.json` and
+`.claude/settings.local.json`; the local file is this checkout's own, and a handler in both runs once. It reads the
+local file even where git ignores it, as Claude Code runs its hooks either way, so an owner's personal commands can
+show here; list-candidate-files leaves an ignored file out of what it lists to map, not out of what loads. This tool
+only prints them here and never writes them to a map or an audit record; if you quote one in an audit answer, that
+answer is written to the audit record, which the project commits, so leave a personal command out of it. It does not
+read user, managed, plugin or skill and agent frontmatter hooks, `prompt` or `agent` handlers, or `disableAllHooks`.
+`hook_settings_not_read` names each of those two settings files this tool could not read, with its refusal code, so
+an unreadable file is not taken for one without hooks.
+
+A carrier loads its whole file, so `file_bytes` is the file's size, shared by every member in it, and
+`estimated_tokens` is its characters divided by four, rounded up: an estimate, not a tokenizer count. For a skill,
+they are what its body costs once invoked, and for an agent what its body costs in the subagent's context; the
+description is a smaller part of the file. A `loads` without `context` loads into the main session's context.
+`member_bytes` and `member_tokens` are the member's own lines, its share of that file, which moving the member out
+of it would save; for a member that is its whole file they equal `file_bytes` and `estimated_tokens`, and they are
+left out when this tool cannot find the member in its file.
+Those lines may be other members' too: `overlaps` names this principle's members sharing a line with it, `same_lines_as`
+those spanning exactly its lines, and `mapped_elsewhere` other principles' members, each with its role, `first_line`,
+`last_line`, and `same_lines` when spanning exactly the same lines, `spans_these_lines` when its lines include all of
+this member's, or `within_these_lines` when they all lie within this member's. Each is left out when none shares a line.
+Before narrowing a section to save its `member_bytes`, check whose lines they are.
+
+Members in one file each show that file's size, so adding up the members counts a shared file once per member.
+`files_loaded` lists each file the members load once, with its `path`, when it loads and its size, as a member's
+`loads.claude_code` gives them, leaving out a file with no known carrier; the hooks that name a file show on its
+members. `session_start_total` adds up the files that load whole at session start, the one moment
+they all load together; the files that load on files, on invocation or on delegation each load apart, so they are not
+added up. Beside them, `descriptions` gives the `count` of skill and agent descriptions that load at session start
+while their bodies wait, with their `description_bytes` and `description_tokens`: for a skill, its `description` and
+`when_to_use` lines together, cut at 1,536 characters as Claude Code cuts each skill's listing
+(code.claude.com/docs/en/skills, read 2026-11-09; a `skillListingMaxDescChars` setting changes that cap), and for an
+agent its `description` lines. A skill only a person can invoke is left out, since its description does not load.
+They are measured as written, each line with its key, quoting and trailing newline, so they are an estimate of what
+the listing holds, and a skill's can exceed a description member's own `member_bytes` when it has `when_to_use`.
+The total leaves out a file this tool cannot read, and whatever this principle does not map, such as user-level files,
+imports and hook output: it is what this principle's own files cost at start, not what a session starts with. The
+files and descriptions it counts load at start whatever its activation, since the host loads them before an agent
+reads the principle; the activation says when the agent works with the principle, and its other members load as their
+own `when` says. Both are left out when there is nothing to list. Within the total, `files`, `file_bytes` and
+`estimated_tokens` are left out when no file that loads whole at start could be measured, as `descriptions` is when
+no description could; a file listed in `files_loaded` with no size loads at start uncounted.

data/lib/principles/views/prompts/learn-what-a-command-does/start-audit.md

@@ -0,0 +1,68 @@
+Asks you to assess every member of principle ID and the set as a whole. Run it after mapping, and again when
+`show-principle` reports a member changed, unassessed, locator_lost or unavailable.
+
+`start-audit` itself writes nothing. `submit-answer` writes the audit record, `.principles/audits/ID.json`: a full audit
+writes it completed when its assessment has no findings or its correction is accepted. In git, commit the record each
+time it is written, as `files_to_commit` lists it. In a full audit, make each fix after the assessment is accepted and
+before you submit the correction that reports it, or the assessment is refused as `stale_request`, as is an edited
+`basis`, whose `basis.last_completed_revision` names the record it follows, or null for none. The audit judges the text
+now: a problem no completed audit recorded and fixed before `start-audit` is not recorded, and a deferred or accepted
+finding fixed since is decided `resolved`. To record one, commit a revert, run the audit, and redo it in the correction.
+
+It refuses with `broken_members` while any member cannot be found or read; `missing_files` groups them by file. A member
+with a check carries `check_since_last_audit`, and `check_hidden_characters` when its check hides characters.
+`mapped_elsewhere` shows other principles' members on its lines, judged as `mapped_elsewhere_instruction` says, with
+`open_finding_ids` from `open_findings_elsewhere`, whose `evidence` items say `shares_lines_with`, `shares_no_lines`,
+`whole_file` or `not_located`, or which says `evidence_not_kept`. In git, `context.uncommitted_files_outside_the_map`
+lists up to ten files outside the map that differ from the base commit or are untracked, `not_named` counting the rest.
+A meta-principle audit adds `package_since_last_audit`, `passage_changed` and `other_principles_with_unjudged_changes`.
+
+## Since the last full audit
+
+After a full audit, each member carries `carried_forward`, with its `assessed_at`, an observed one's `observed_at` (or
+`observed_at_from_assessed_at`), `evidence_changed` and, in git, `file_changed_outside_member`, or else `judge_because`
+with `read_the_change`, and a moved one `moved_from`; `carried_forward_instruction` and `judge_because_instruction`
+explain them. One acknowledged with `--member` since carries `acknowledged_since_last_audit`, with that audit's
+`last_audited_commit`, each acknowledgement and its lines then and now, or `{"omitted": "not_found_at_last_audit"}` when
+it has moved. A new or changed check's exit status needs `review_basis`: what its review rested on, kept unverified. An
+unchanged check also shows its `review_basis` and `review_basis_since`, a changed one `last_run_review_basis`.
+
+## Prior findings
+
+When the last completed audit deferred or accepted findings, `context.prior_findings` lists them, with `first_raised_at`
+and a deferral's `waits_on` and `waits_on_since`. Decide each in `prior_finding_decisions` as `still_holds`, `resolved`,
+`withdrawn` or `raised_again`, as `context.prior_findings_instruction` says. An older finding may claim an earlier
+`first_raised_at` with `raised_in`, from `git log --follow -p -- .principles/audits/ID.json`. Each gives its `evidence`,
+in git each item with `changed_since_last_audit` and `found_now`, or `evidence_not_kept` and an `evidence_request` for
+`problem_evidence`, whose `replaces` re-points a lost item. The result names drops and re-points:
+`prior_findings_pointers_dropped`, `prior_findings_waits_on_dropped`, `prior_findings_evidence_replaced`.
+
+## Members to check against the activation
+
+When the principle's activation is a set of files, `context.loads_to_check_against_activation` lists each member whose
+file Claude Code loads at session start, with its `loads` and `listed_for`, to weigh whether a principle meant for that
+work loads in every session; this tool compares no globs, and `not_listed_no_known_carrier` names the members this tool
+knows no carrier for. Decide every row in `loading_decisions`, as `context.loads_to_check_instruction` explains, or this
+tool refuses it with `incomplete_loading_decisions`. The record keeps an accepted decision as `loading_accepted`, which
+the next audit shows as `last_accepted`, with `last_accepted.since_accepted` and whether `member_text` or `loading`
+changed. Not listed yet: members loading on files, skills or agents, members this tool could not determine, members a
+hook names, and anything under an invoked or always activation or in a one-member audit.
+
+## One member's edit: `--member`
+
+Use `--member MEMBER` when one member was edited but still says the same thing, as `list-member-problems --help`
+describes; without it, `list-member-problems --short` reports the edit at every commit until a full audit. Its request
+shows the `baseline_commit` it was last judged at, `member_lines` then and now (or a long member's `changed_region`,
+`context_lines` and `from_line`, or `read_instead`), `read_the_change` and the member's `deferred_findings` and
+`accepted_findings`, which stay; its `question` asks for `meaning_kept`. This tool checks both quotes. An id near a
+mapped one is refused with `unknown_member`, naming the mapped one under `did_you_mean`. A one-member audit writes the
+record once its answer is accepted, keeping the edit in the member's `acknowledgements`; commit it. It is refused with
+`cannot_acknowledge` outside git, while an audit is open, and for a member no completed audit assessed or whose text at
+its baseline commit does not match the audit record; until built, it is refused for a member with a check: run a full
+audit. A member moved with `move-member` since its baseline carries `evidence_at_baseline`, and one the last full
+audit's correction fixed carries `audit_base_commit`: judge only the change since `baseline_commit`.
+
+## Outside git
+
+In a project outside git, an assessment with findings writes an open record, which the accepted correction completes.
+Until then it keeps the prior findings to list again; one opened by an older version of this tool kept none.

data/lib/principles/views/prompts/learn-what-a-command-does/submit-answer.md

@@ -0,0 +1,56 @@
+Gives your answer to request REQUEST, built from that request's `response_template`. Write the JSON to a FILE outside
+the project and pass `--file FILE`, which needs no shell quoting; `--file -` reads stdin. This tool edits none of the
+project's files. In a full audit, make each fix after the assessment is accepted and before you submit the correction
+that reports it: an earlier fix changes a member the request was computed from, and is refused as `stale_request`.
+Answer each request once. If another full audit of the principle completed, or a member was acknowledged, after an
+assessment or correction request was printed, its answer is refused as `audit_completed_since_request`, since it would
+replace the newer record and drop what it left open: run `list-open-findings ID`, then start the audit again. Copy the
+basis unchanged: its `last_completed_revision` says which record its request was printed after. The same answer
+submitted again after it completed the audit writes nothing, and is accepted; an assessment whose correction completed
+the audit is refused instead, since it would print a new correction.
+An observed assessment may give `observed_at`, when you saw what `observation` describes, as a UTC time like
+`2026-11-01T09:30:00Z`; none or null dates it at this audit's time. When the sighting is a dated record you read during
+this audit, `observed_at` is the record's date, not when you read it. Another form, a time after the answer, or any on a
+not_observed one, even null, is refused as `invalid_answer`. An `observation` judged afresh copying the last full
+audit's word for word is refused as `observation_repeats_last_audit` unless `observed_at` is the date it names or null:
+the date if you kept that sighting; reword a later one, null if in this audit. It checks no reworded text.
+When this tool cannot place a piece of evidence or a `recorded_at`, such as a quote that occurs twice
+(`ambiguous_passage`), or refuses a `check_result` (`invalid_check_result`), the refusal keeps its code, any `path`
+and repair, starts its message with whose it is, such as "Finding F1" or "Member CLAUDE.md#Names", and gives `fields`,
+each with its `problem` and the JSON `pointer` into your answer.
+The correction template leaves each `action` null for you to choose: fixed, deferred, accepted or disagreed; a null or
+unknown one is refused as `invalid_disposition`, naming the finding. A deferred disposition may give `waits_on`, one
+line saying whom the finding waits on and to decide what, such as "<person>, to approve a CI change", which
+`list-open-findings` prints. Null, accepted on any disposition, says it waits on no one; a line on any other action, or
+one that spans lines, is refused as `invalid_disposition`. This tool records when it was asked; never send that time.
+A full audit's `still_holds` decision on a prior finding may give `first_raised_at` with `raised_in`, the full sha of a
+commit whose audit record, at `.principles/audits/ID.json` or the earlier `.memeplex/audits/ID.json`, left the same
+finding open then, deferred or accepted, with `first_raised_at` that record's `audited_at`, to date a finding from
+records older than the field. Give both or neither; this tool reads only that commit, and whether it is the same finding
+is yours to judge. A claim it cannot confirm is refused, saying why and how to repair it: `raised_in_not_found`, as
+outside git, `raised_in_unreadable`, `raised_in_lacks_finding`, `raised_in_time_differs`, or `first_raised_not_earlier`
+when it is not earlier than the time stored.
+A completed full audit's `open_findings` are the ids `list-open-findings` will list, its own and kept prior ones,
+deferred or accepted; `resolved_findings`, those fixed now and prior ones decided resolved. A disagreed or withdrawn
+finding is in neither; `prior_findings_closed` gives each prior one closed, with its decision and reason.
+In git, `commits_since_base` lists by member id the commits since the base touching its file; an uncommitted fix shows
+an empty list, `files_to_commit` names its file, and `commit_with`, its `-m` default replaced as
+`commit_message_to_replace` says, commits only those, stopping during an unfinished merge. In or out of git,
+`cited_files_missing` names each file the record cites that no longer exists, which `files_to_commit` leaves out though
+the record still points at it. If HEAD moved but no commit touched one, `head_moved_past_base` gives `base_commit` and
+`head`. If its fixes changed a file another principle also maps, `other_principles_with_changed_members` names each such
+principle and its members in fixed findings' files, by `id` with the `state` `list-member-problems` gives: `changed`
+when its text now differs from its baseline, or `locator_lost` or `unavailable` when the fix broke where this tool finds
+it, which its `repair_with` on `show-principle ID` repairs. Then re-audit that principle, or acknowledge a member's edit
+with `start-audit ID --member MEMBER`. A changed file no fixed finding names is not checked.
+
+A fix changing a member's role or check with `change-member-role` or `change-member-check` lists its id, after any move,
+in `changed_map_entries`, which only a fixed disposition may list, and may leave `changed_members` empty. A fix mapping
+a missing member with `add-member` names it in `changed_members`. In git, this tool reads the map the audit began from
+and refuses with `stale_map` when anything else changed, a removal too, after any `moved_members`, and
+`claimed_change_missing` when a listed role and check are as they were; `files_to_commit` names the map. An added member
+gets no baseline: `members_added_awaiting_assessment` names it for the next full audit. Outside git, defer the finding:
+an entry is refused as `map_entries_need_git`, an added member as `stale_map`.
+
+For a `start-audit --member` request, this tool checks `old_line` at the baseline commit and `new_line` now, refuses
+with `quote_not_found` when either is not found, and prints `acknowledged` with the record in `files_to_commit`.

data/lib/principles/views/prompts/repoint-write-ups/point-each-moved-write-up-at-its-new-place.md

@@ -0,0 +1,10 @@
+Each open finding in `findings` has its `recorded_at`, and what list-open-findings says of the write-up there: its
+`write_up_opening`, or why there is none in `write_up_opening_reason`. When the file is missing, git's match for it is
+in `write_up_opening_error.git_detected_rename`, with `starting_at_found_in_rename` when the pointer quotes a
+`starting_at`. Git's match can pair a deleted file with an unrelated similar one, so read the file it names before you
+use it. For each finding whose write-up you found, set its `recorded_at` in `repoints` to where the write-up is now,
+as `{"path": ..., "heading": ...}` or with `starting_at`, and give a one-line `reason`. Leave `recorded_at` null for a
+finding you do not repoint. Only `recorded_at` changes: the finding stays open, with its problem, action and dates,
+for the next full audit to decide. During a full audit, give the new `recorded_at` in that finding's still_holds
+decision instead, since a repoint changes the record that audit's request was printed after. Do not edit the audit
+record by hand: nothing would check that the new pointer is found.

data/lib/principles/views/prompts/report-after-a-commit/it-refused-after-the-commits-touched-the-maps.md

@@ -0,0 +1,2 @@
+principles: list-member-problems refused with %{code} after commits that changed this project's maps or
+mapped files. This command shows why and how to repair it:

data/lib/principles/views/prompts/report-after-a-commit/others-are-still-listed.md

@@ -0,0 +1 @@
+%{count} other changed %{members} still listed from earlier commits.

data/lib/principles/views/prompts/report-after-a-commit/the-commits-changed-these-members.md

@@ -0,0 +1,2 @@
+principles: the commits this Bash call brought in changed these mapped members, one per line with its
+principle, id, newest changing commit, that commit's subject and what it was compared with:

data/lib/principles/views/prompts/report-after-a-commit/this-command-shows-each-one.md

@@ -0,0 +1 @@
+This command shows each one and what to do next:

data/lib/principles/views/prompts/report-the-completed-audit/commit-only-what-the-audit-changed.md

@@ -0,0 +1,2 @@
+Commit %{files}, and nothing else staged, with the command that ends this line, after replacing its default `-m`
+message as `commit_message_to_replace` says. Commit with: %{command}

data/lib/principles/views/prompts/report-the-completed-audit/replace-the-default-commit-message.md

@@ -0,0 +1,4 @@
+The `-m` message in `commit_with`, "%{subject}", is a default: replace it with a subject in your project's own
+convention, such as a ticket prefix, before running it, since a commit hook may refuse the default. For a message with
+a body or trailer, write it to a file and put `-F <file>` in place of `-m` and its subject; a file needs no shell
+quoting, and a relative path to it resolves from the project, which the command changes into first.

data/lib/principles/views/prompts/report-the-completed-audit/what-completion-means.md

@@ -0,0 +1,2 @@
+Completion records assessment coverage, not certification. Fixed is the agent's judgement plus a
+checked change; delivery is credited only as the agent reported it.

data/lib/principles/views/prompts/set-principles-up/entry-file-passage.md

@@ -0,0 +1,3 @@
+## %{heading}
+
+Where `principles` is installed, run `principles list-member-problems --short` at each session start, after a compaction and after each commit that edits a mapped file, and act on what it reports.

data/lib/principles/views/prompts/set-principles-up/name-the-step-each-member-lacks.md

@@ -0,0 +1,15 @@
+These places are mapped as keeping the principles held, each with the role its member gives it:
+
+%{members}
+
+A place keeps them held only through what triggers it: a hook, a timer or a reader. With the user, name which of
+the keeping steps each one lacks: running `principles list-member-problems --short` at session start, after a
+compaction and after each commit that edits a mapped file, and acting on what it reports. The members listed in
+members_in_entry_files are the ones in an entry file. This tool writes none of the project's guidance.
+
+Where a step is missing, the passage is one way to add it, at %{estimated_tokens} estimated tokens in every session
+that loads the entry file it goes in.
+
+Once the passage is placed, map it: %{command}
+
+To map another place that runs a missing step, giving as STEP the step it runs and as TRIGGER what starts it: %{any_place}

data/lib/principles/views/prompts/set-principles-up/place-the-passage-with-the-user.md

@@ -0,0 +1,31 @@
+Show the user the passage, which suits any entry file, and agree with them where it goes: an entry file that every
+session of their agents loads. If a passage there already says all of it, map that one instead. If a member listed
+in members_in_entry_files already says it, the passage is placed and mapped: go on to next_action. This tool writes
+none of the project's guidance.
+
+The first member need not be the passage: it can be any file or setting in the project that keeps the principles
+in front of the agent, such as a timer of the project's own, or the committed setting that enables the plugin for
+the team, its enabledPlugins line. Map it with a role that names, as STEP, the step it runs and, as TRIGGER, what
+starts that step: a hook, a timer or a reader. Mapping it says only that the project names something to keep them
+held; this principle's audit judges whether it does.
+
+To map such a place: %{any_place}
+
+Where the owner enables the plugin only at user scope, the project has nothing to map for it. Say so, and name the
+two ways on: commit the project-scope enablement and map its line, or leave the "Set principles up first" line
+standing.
+
+Where only a reader enforces a step, with no hook or timer that runs it, say so in what you place.
+
+Where the project says how a teammate gets `principles`, such as an install section or a setup note, link to it in
+what you place. Say in a few words what `principles` is, so a teammate knows what the passage and any link lead to.
+Where the project says nowhere how to get it, tell the user that a teammate who reads the passage cannot act on it
+without that.
+
+Where a passage the project already has carries one of the proposed passage's steps, leave that step out and map
+that passage too, so each rule is said once, giving its file as PATH and its heading as HEADING: %{existing}
+
+Once the passage is in the file, map it: %{command}
+
+That command names the heading the passage is proposed under; where you placed it under another heading, give
+--section the heading you placed it under.

data/lib/principles/views/prompts/set-principles-up/set-up-first.md

@@ -0,0 +1,2 @@
+Set principles up first, mapping a passage, a timer or the setting that enables the plugin as what keeps them held
+between audits: %{command}

data/lib/principles/views/prompts/set-principles-up/what-the-passage-presumes.md

@@ -0,0 +1,4 @@
+The passage asks its steps only where `principles` is installed, so a teammate without `principles` is told to do
+nothing it cannot, but still loads its %{estimated_tokens} estimated tokens in every session that loads the entry
+file. Nothing runs the steps for that teammate: the plugin's session-start hook reports only in sessions where the
+plugin is enabled, and whether a teammate's sessions have it is something this tool cannot see.

data/lib/principles/views/prompts/start-a-session/act-on-the-open-findings.md

@@ -0,0 +1,5 @@
+%{findings}.%{without_waits_on}%{write_ups} %{returns} until a full audit decides %{them}.
+%{when} list %{them}, then raise in one short message any waiting on the user or no one named. Judge by
+context, such as git's user name, whether a named person is your user; if unsure, raise it. Do not raise any
+waiting on someone else, or that you can see you raised in this conversation. To see whom %{each} waits on, run
+%{command}

data/lib/principles/views/prompts/start-a-session/it-returns-after-each-clear-or-compaction-too.md

@@ -0,0 +1 @@
+This line returns after each clear or compaction too

data/lib/principles/views/prompts/start-a-session/it-returns-at-each-session-start.md

@@ -0,0 +1 @@
+This line returns at each session start

data/lib/principles/views/prompts/start-a-session/raise-them-at-the-next-pause.md

@@ -0,0 +1 @@
+At your next pause,

data/lib/principles/views/prompts/start-a-session/raise-them-before-the-first-task.md

@@ -0,0 +1 @@
+Before the user's first task,

data/lib/principles/views/prompts.rb

@@ -0,0 +1,71 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "json"
+
+module Principles
+  # What this tool prints, built from domain values at print time. views/CLAUDE.md owns the boundary.
+  module Views
+    # The text this tool prints to guide the agent, kept in views/prompts/ under a folder for the
+    # workflow step that uses it. views/CLAUDE.md owns the layout. A prompt is Markdown wrapped for
+    # reading: single line breaks join into spaces, and a blank line separates paragraphs.
+    module Prompts
+      ROOT = File.join(__dir__, "prompts").freeze #: String
+
+      # A prompt's text, with each %{name} placeholder filled from values.
+      #: (String, **String) -> String
+      def self.text(name, **values) = Prompt.read(name).wrapped.filled(values)
+
+      # A prompt printed as Markdown, such as a command's --help: its lines stay as written, and each
+      # %{name} placeholder is filled from values.
+      #: (String, **String) -> String
+      def self.markdown(name, **values) = Prompt.read(name).filled(values)
+
+      # A prompt that shows a shape by example, as JSON data.
+      #: (String) -> untyped
+      def self.data(name)
+        JSON.parse(File.read(File.join(ROOT, "#{name}.json")))
+      end
+
+      # Every prompt name, relative to ROOT and without its extension.
+      #: () -> Array[String]
+      def self.names
+        Dir.glob("**/*.{md,json}", base: ROOT).map { |path| path.sub(/\.(md|json)\z/, "") }.sort
+      end
+    end
+
+    # One packaged prompt: its name and its text as written. It lives beside Prompts, so the views' one
+    # file-reading exception stays one file; give it its own file and spec if it grows rules of its own.
+    class Prompt
+      # The prompt packaged as name.md under Prompts::ROOT.
+      #: (String) -> Prompt
+      def self.read(name) = new(name, File.read(File.join(Prompts::ROOT, "#{name}.md")).strip)
+
+      #: (String, String) -> void
+      def initialize(name, text)
+        @name = name
+        @text = text
+        freeze
+      end
+
+      # The prompt wrapped for reading: single line breaks join into spaces, and a blank line separates
+      # paragraphs.
+      #: () -> Prompt
+      def wrapped
+        Prompt.new(@name, @text.split(/\n{2,}/).map { |paragraph| paragraph.gsub(/\s*\n\s*/, " ") }.join("\n\n"))
+      end
+
+      # The text with each placeholder filled. Text with no values is left as it is, since a prompt may hold a
+      # literal %, but one holding a placeholder is refused, so it never reaches the agent unfilled (#422).
+      #: (Hash[Symbol, String]) -> String
+      def filled(values)
+        return format(@text, **values) unless values.empty?
+
+        placeholder = @text[/%\{\w+\}/]
+        raise ArgumentError, "prompt #{@name} needs a value for #{placeholder}" if placeholder
+
+        @text
+      end
+    end
+  end
+end

data/lib/principles/views/repoint_result.rb

@@ -0,0 +1,80 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "invocation"
+require_relative "prompts"
+
+module Principles
+  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
+  module Views
+    # A repoint of a principle's open findings' write-ups: its request and its result (D59).
+    class RepointResult
+      # What an accepted repoint did: the ids of the findings it repointed and of those it left where they point,
+      # and each other principle's open finding whose write-up cannot be found, with those principles (T16).
+      class Outcome
+        #: Array[String]
+        attr_reader :repointed, :unchanged
+        # Each as its principle and finding_id.
+        #: Array[Hash[String, String]]
+        attr_reader :not_found_elsewhere
+
+        #: (repointed: Array[String], unchanged: Array[String], not_found_elsewhere: Array[Hash[String, String]])
+        #|  -> void
+        def initialize(repointed:, unchanged:, not_found_elsewhere:)
+          @repointed = repointed
+          @unchanged = unchanged
+          @not_found_elsewhere = not_found_elsewhere
+          freeze
+        end
+
+        # The other principles not_found_elsewhere names, each once.
+        #: () -> Array[String]
+        def principles_elsewhere = @not_found_elsewhere.map { |finding| finding.fetch("principle") }.uniq
+      end
+
+      #: (Invocation) -> void
+      def initialize(invocation)
+        @invocation = invocation
+        freeze
+      end
+
+      # findings are the open findings, each with its recorded_at and what list-open-findings says of its write-up.
+      #: (request_id: String, principle_id: String, revision: String?, findings: Array[Hash[String, untyped]])
+      #|  -> Hash[String, untyped]
+      def request(request_id:, principle_id:, revision:, findings:)
+        repoints = findings.map do |finding|
+          { "finding_id" => finding["finding_id"], "recorded_at" => nil, "reason" => "" }
+        end
+        { "status" => "agent_judgement_required", "request_id" => request_id, "phase" => "repointing",
+          "context" => { "principle_id" => principle_id, "findings" => findings,
+                         "question" => Prompts.text("repoint-write-ups/point-each-moved-write-up-at-its-new-place") },
+          "response_template" => { "request_id" => request_id, "basis" => { "revision" => revision },
+                                   "repoints" => repoints },
+          "answer_with" => @invocation.submit_answer(request_id) }
+      end
+
+      # The repoints were accepted, as outcome says, and file holds them.
+      #: (principle_id: String, file: String, outcome: Outcome) -> Hash[String, untyped]
+      def repointed(principle_id:, file:, outcome:)
+        { "status" => "write_ups_repointed", "principle_id" => principle_id, "repointed" => outcome.repointed,
+          "unchanged" => outcome.unchanged, "other_write_ups_not_found" => outcome.not_found_elsewhere,
+          "files_to_commit" => [file],
+          "next_action" => "Commit #{file}. After committing, this names no write-up of #{principle_id} it cannot " \
+                           "find: #{@invocation.in_project("list-open-findings", principle_id, usage: "--short")}" \
+                           "#{elsewhere(outcome.principles_elsewhere)}" }
+      end
+
+      private
+
+      # The request that repoints each other principle's write-ups, one per line, or nothing when there is none.
+      #: (Array[String]) -> String
+      def elsewhere(principle_ids)
+        return "" if principle_ids.empty?
+
+        commands = principle_ids.map { |id| "#{@invocation.in_project("start-audit", id, usage: "--write-ups")}\n" }
+        "\nWrite-ups of other principles cannot be found either, listed under other_write_ups_not_found. " \
+          "Check each, and repoint it with its own request:\n#{commands.join}"
+      end
+    end
+  end
+end

data/lib/principles/views/request_part.rb

@@ -0,0 +1,26 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Principles
+  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
+  module Views
+    # One part of a judgement request beyond its members, such as the prior findings to decide (D35) or the members
+    # to check against the activation (#355): what the agent reads of it, its list and the instruction for it, and
+    # the slots it adds to the answer's template, which the request builds in where each belongs (D60).
+    class RequestPart
+      # What the agent reads of this part: its list, then the instruction for deciding it.
+      #: Hash[String, untyped]
+      attr_reader :shown
+      # The slots this part adds to the answer's template.
+      #: Hash[String, untyped]
+      attr_reader :slots
+
+      #: (shown: Hash[String, untyped], slots: Hash[String, untyped]) -> void
+      def initialize(shown:, slots:)
+        @shown = shown
+        @slots = slots
+        freeze
+      end
+    end
+  end
+end

data/lib/principles/views/request_parts.rb

@@ -0,0 +1,26 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "request_part"
+
+module Principles
+  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
+  module Views
+    # A judgement request's parts beyond its members, in the order the agent reads them (D60).
+    class RequestParts
+      #: (Array[RequestPart]) -> void
+      def initialize(parts)
+        @parts = parts
+        freeze
+      end
+
+      # entries, with what each part shows added after them, in order.
+      #: (Hash[String, untyped]) -> Hash[String, untyped]
+      def shown_after(entries) = @parts.reduce(entries) { |all, part| all.merge(part.shown) }
+
+      # template, with each part's slots added after its own entries, in order.
+      #: (Hash[String, untyped]) -> Hash[String, untyped]
+      def slotted_after(template) = @parts.reduce(template) { |all, part| all.merge(part.slots) }
+    end
+  end
+end

data/lib/principles/views/shell_word.rb

@@ -0,0 +1,29 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Principles
+  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
+  module Views
+    # One word of a printed command, as a shell reads it: as it is when it holds only characters no shell treats
+    # specially, else in single quotes, inside which a shell expands nothing. Ids, paths and headings come from
+    # project files anyone may have written (#227).
+    class ShellWord
+      # A word every common shell reads as it is: no quote, space, $, `, glob or redirection, and no = or #,
+      # which zsh can expand.
+      PLAIN = %r{\A[\w./:@%+,-]+\z}
+
+      #: (String) -> void
+      def initialize(value)
+        @value = value
+        freeze
+      end
+
+      #: () -> String
+      def to_s
+        return @value if PLAIN.match?(@value)
+
+        "'#{@value.gsub("'") { "'\\''" }}'"
+      end
+    end
+  end
+end

data/lib/principles/views/visible_text.rb

@@ -0,0 +1,26 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Principles
+  # What this tool prints, from plain values a controller hands it. views/CLAUDE.md owns the boundary.
+  module Views
+    # Text from a project file or an agent's answer, printed outside JSON with each control, format and separator
+    # character written as \uXXXX, as JSON output shows it, so a tab cannot split a field and an invisible character
+    # cannot hide (#227). cli.rb escapes printed JSON without control characters, since JSON already escapes them
+    # inside strings and its own newlines must stay; so the two are not one rule to fold together.
+    class VisibleText
+      #: (String) -> void
+      def initialize(text)
+        @text = text
+        freeze
+      end
+
+      #: () -> String
+      def to_s
+        @text.gsub(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/) do |character|
+          character.encode("UTF-16BE").unpack("n*").map { |unit| format("\\u%04x", unit) }.join
+        end
+      end
+    end
+  end
+end