principles 0.0.1

data/lib/principles/views/workflow_diagram.rb

@@ -0,0 +1,77 @@
+# 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
+    # The docs page that draws every command's steps as one Mermaid flowchart (ticket 001 D15): a subgraph
+    # per command, this tool's steps as boxes, the agent's as rounded shapes, and a dashed edge where the agent
+    # hands over to the command it answers with. It is generated, and a spec fails when the committed copy is
+    # stale, so the drawing cannot drift from the steps --help prints.
+    class WorkflowDiagram
+      # One step, keyed by an id that is safe in Mermaid.
+      class Node
+        #: String
+        attr_reader :key
+        #: String
+        attr_reader :label
+        #: bool
+        attr_reader :agent
+
+        #: (key: String, label: String, agent: bool) -> void
+        def initialize(key:, label:, agent:)
+          @key = key
+          @label = label
+          @agent = agent
+          freeze
+        end
+
+        #: () -> String
+        def to_s
+          agent ? "#{key}([\"#{label}\"])" : "#{key}[\"#{label}\"]"
+        end
+      end
+
+      # Where one step leads: a branch's condition, if any, and whether the agent hands over to another command.
+      class Edge
+        #: (from: String, to: String, ?label: String?, ?handover: bool) -> void
+        def initialize(from:, to:, label: nil, handover: false)
+          @from = from
+          @to = to
+          @label = label
+          @handover = handover
+          freeze
+        end
+
+        #: () -> String
+        def to_s
+          "#{@from} #{@handover ? "-.->" : "-->"}#{"|\"#{@label}\"|" if @label} #{@to}"
+        end
+      end
+
+      INTRODUCTION = <<~MARKDOWN
+        # principles command workflow diagram
+
+        Generated from `lib/principles/data/command-steps.json` by `bundle exec rake diagram`; do not edit it by hand.
+        Each box is a step the principles command runs and each rounded shape is the agent's. A dashed arrow is the
+        agent running the command it answers with. Each command's `--help` prints the same steps in words.
+      MARKDOWN
+
+      #: (commands: Array[[String, Array[Node]]], edges: Array[Edge]) -> void
+      def initialize(commands:, edges:)
+        @commands = commands
+        @edges = edges
+        freeze
+      end
+
+      #: () -> String
+      def to_s
+        subgraphs = @commands.each_with_index.map do |(usage, nodes), index|
+          ["  subgraph c#{index}[\"#{usage}\"]", *nodes.map { |node| "    #{node}" }, "  end"]
+        end
+        lines = ["flowchart TD", *subgraphs.flatten, *@edges.map { |edge| "  #{edge}" }]
+        "#{INTRODUCTION}\n```mermaid\n#{lines.join("\n")}\n```\n"
+      end
+    end
+  end
+end

data/lib/principles.rb

@@ -0,0 +1,5 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "principles/version"
+require_relative "principles/cli"

metadata

@@ -0,0 +1,326 @@
+--- !ruby/object:Gem::Specification
+name: principles
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Sidu Ponnappa
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Principles helps teams keep an agent's operating guidance consistent as their harness evolves.
+  Name a principle and map the instruction passages, rules, skills, agents, hooks and checks that carry it.
+  The principles CLI reports changed or broken members and guides the agent through assessing the whole set,
+  fixing problems or recording open findings, and keeping the map and audit history in version control.
+
+  The CLI tracks state and validates references deterministically; the consuming agent supplies the judgement.
+  It calls no model and never edits the project's guidance. Structured results provide the next command,
+  evidence requirements and repairs. Context-loading information helps the agent assess unnecessary guidance.
+  The gem provides a host-independent command-line runtime for Ruby 3.4.x with no runtime gem dependencies.
+executables:
+- principles
+extensions: []
+extra_rdoc_files: []
+files:
+- exe/principles
+- lib/principles.rb
+- lib/principles/after_commit_hook_options.rb
+- lib/principles/cli.rb
+- lib/principles/command_line.rb
+- lib/principles/command_routes.rb
+- lib/principles/controllers/acknowledgement.rb
+- lib/principles/controllers/answer.rb
+- lib/principles/controllers/audit.rb
+- lib/principles/controllers/audit_completion.rb
+- lib/principles/controllers/command.rb
+- lib/principles/controllers/correction.rb
+- lib/principles/controllers/help.rb
+- lib/principles/controllers/inventory.rb
+- lib/principles/controllers/mapping.rb
+- lib/principles/controllers/member_entries.rb
+- lib/principles/controllers/members_a_commit_changed.rb
+- lib/principles/controllers/members_to_assess.rb
+- lib/principles/controllers/meta_principle_setup.rb
+- lib/principles/controllers/repoint.rb
+- lib/principles/controllers/running_tool.rb
+- lib/principles/data/audit_files.rb
+- lib/principles/data/bounded_file.rb
+- lib/principles/data/candidate_files_found.rb
+- lib/principles/data/command-steps.json
+- lib/principles/data/command_steps_file.rb
+- lib/principles/data/expected_type.rb
+- lib/principles/data/ignored_by_git.rb
+- lib/principles/data/json_text.rb
+- lib/principles/data/known_fields.rb
+- lib/principles/data/linked_path.rb
+- lib/principles/data/map_files.rb
+- lib/principles/data/principle_id.rb
+- lib/principles/data/principles_subfolder.rb
+- lib/principles/data/project_files.rb
+- lib/principles/data/repository.rb
+- lib/principles/data/running_version.rb
+- lib/principles/data/schema_check.rb
+- lib/principles/data/schemas/acknowledgement-answer.schema.json
+- lib/principles/data/schemas/answer-guide.schema.json
+- lib/principles/data/schemas/assessment-answer.schema.json
+- lib/principles/data/schemas/audit-record.schema.json
+- lib/principles/data/schemas/command-steps.schema.json
+- lib/principles/data/schemas/correction-answer-guide.schema.json
+- lib/principles/data/schemas/correction-answer.schema.json
+- lib/principles/data/schemas/member-map.schema.json
+- lib/principles/data/schemas/repointing-answer.schema.json
+- lib/principles/error.rb
+- lib/principles/invocation_options.rb
+- lib/principles/models/accepted_loading.rb
+- lib/principles/models/acknowledgement.rb
+- lib/principles/models/activation.rb
+- lib/principles/models/agent_loads.rb
+- lib/principles/models/answer_fields.rb
+- lib/principles/models/answer_place.rb
+- lib/principles/models/answer_text.rb
+- lib/principles/models/answered_time.rb
+- lib/principles/models/assessment_answer.rb
+- lib/principles/models/assessment_basis.rb
+- lib/principles/models/assessment_report.rb
+- lib/principles/models/audit.rb
+- lib/principles/models/audit_record.rb
+- lib/principles/models/audit_records.rb
+- lib/principles/models/audit_start.rb
+- lib/principles/models/audited_member_lines.rb
+- lib/principles/models/candidate_files.rb
+- lib/principles/models/candidate_inventory.rb
+- lib/principles/models/candidate_listing.rb
+- lib/principles/models/carried_assessments.rb
+- lib/principles/models/check_since_last_audit.rb
+- lib/principles/models/cited_files.rb
+- lib/principles/models/command_steps.rb
+- lib/principles/models/commits_brought_in.rb
+- lib/principles/models/commits_since_base.rb
+- lib/principles/models/correction_answer.rb
+- lib/principles/models/correction_basis.rb
+- lib/principles/models/dated_line.rb
+- lib/principles/models/decided_prior_findings.rb
+- lib/principles/models/declared_map_changes.rb
+- lib/principles/models/disposition.rb
+- lib/principles/models/entry_file.rb
+- lib/principles/models/entry_files.rb
+- lib/principles/models/evidence_item.rb
+- lib/principles/models/evidence_lines_since.rb
+- lib/principles/models/evidence_replacements.rb
+- lib/principles/models/finding_write_ups.rb
+- lib/principles/models/findings_left_open.rb
+- lib/principles/models/first_raised_claim.rb
+- lib/principles/models/frontmatter_fields.rb
+- lib/principles/models/hook_commands.rb
+- lib/principles/models/ignored_candidates.rb
+- lib/principles/models/json_digest.rb
+- lib/principles/models/json_path_query.rb
+- lib/principles/models/json_path_selectors.rb
+- lib/principles/models/json_path_string.rb
+- lib/principles/models/kept_prior_finding.rb
+- lib/principles/models/last_completed_revision.rb
+- lib/principles/models/line_span.rb
+- lib/principles/models/loaded_files.rb
+- lib/principles/models/loading_decision.rb
+- lib/principles/models/loading_facts.rb
+- lib/principles/models/loads_to_check.rb
+- lib/principles/models/locate_refusal.rb
+- lib/principles/models/located_text.rb
+- lib/principles/models/locator.rb
+- lib/principles/models/map_members.rb
+- lib/principles/models/markdown_file.rb
+- lib/principles/models/member.rb
+- lib/principles/models/member_assessments.rb
+- lib/principles/models/member_elsewhere.rb
+- lib/principles/models/member_file.rb
+- lib/principles/models/member_grounds.rb
+- lib/principles/models/member_history.rb
+- lib/principles/models/member_lines.rb
+- lib/principles/models/member_loads.rb
+- lib/principles/models/member_map.rb
+- lib/principles/models/member_map_history.rb
+- lib/principles/models/member_maps.rb
+- lib/principles/models/member_moves.rb
+- lib/principles/models/member_problems.rb
+- lib/principles/models/member_sighting.rb
+- lib/principles/models/member_snapshots.rb
+- lib/principles/models/member_state.rb
+- lib/principles/models/members_elsewhere.rb
+- lib/principles/models/members_sharing_lines.rb
+- lib/principles/models/meta_principle.rb
+- lib/principles/models/missing_files.rb
+- lib/principles/models/misspelt_member_id.rb
+- lib/principles/models/open_finding.rb
+- lib/principles/models/open_findings_elsewhere.rb
+- lib/principles/models/other_principles.rb
+- lib/principles/models/placement.rb
+- lib/principles/models/plain_text_file.rb
+- lib/principles/models/principles_folder_move.rb
+- lib/principles/models/principles_package.rb
+- lib/principles/models/prior_finding_decision.rb
+- lib/principles/models/prior_finding_outcomes.rb
+- lib/principles/models/prior_findings.rb
+- lib/principles/models/problem_report.rb
+- lib/principles/models/project.rb
+- lib/principles/models/project_history.rb
+- lib/principles/models/record_judged_against.rb
+- lib/principles/models/recorded_entry.rb
+- lib/principles/models/recorded_finding.rb
+- lib/principles/models/recorded_findings.rb
+- lib/principles/models/recorded_members.rb
+- lib/principles/models/repoint.rb
+- lib/principles/models/reported_check.rb
+- lib/principles/models/request_id.rb
+- lib/principles/models/runs_from.rb
+- lib/principles/models/skill_loads.rb
+- lib/principles/models/still_holds_restatement.rb
+- lib/principles/models/text_size.rb
+- lib/principles/models/uncommitted_outside_the_map.rb
+- lib/principles/models/waits_on.rb
+- lib/principles/models/write_up_opening.rb
+- lib/principles/models/write_up_pointer.rb
+- lib/principles/models/write_up_repoint.rb
+- lib/principles/prose_list.rb
+- lib/principles/supported_ruby.rb
+- lib/principles/version.rb
+- lib/principles/views/acknowledged_since_last_audit.rb
+- lib/principles/views/acknowledgement_result.rb
+- lib/principles/views/activation_in_hand.rb
+- lib/principles/views/assessment_request.rb
+- lib/principles/views/audit_changes.rb
+- lib/principles/views/audit_commit.rb
+- lib/principles/views/audit_result.rb
+- lib/principles/views/candidate_files_result.rb
+- lib/principles/views/check_result_template.rb
+- lib/principles/views/diff_since_last_audit.rb
+- lib/principles/views/findings_result.rb
+- lib/principles/views/help.rb
+- lib/principles/views/invocation.rb
+- lib/principles/views/landed_since_base.rb
+- lib/principles/views/lines_shared_with_member.rb
+- lib/principles/views/loads_to_check_result.rb
+- lib/principles/views/map_result.rb
+- lib/principles/views/member_change_since_baseline.rb
+- lib/principles/views/member_repairs.rb
+- lib/principles/views/members_a_commit_changed.rb
+- lib/principles/views/members_with_no_baseline.rb
+- lib/principles/views/meta_principle_passage.rb
+- lib/principles/views/meta_principle_result.rb
+- lib/principles/views/open_findings_elsewhere_result.rb
+- lib/principles/views/open_findings_line.rb
+- lib/principles/views/other_principles_unjudged_result.rb
+- lib/principles/views/outside_the_map_result.rb
+- lib/principles/views/package_since_last_audit_result.rb
+- lib/principles/views/principle_read_result.rb
+- lib/principles/views/principle_with_changed_members.rb
+- lib/principles/views/principles_with_no_completed_audit.rb
+- lib/principles/views/printed_principle.rb
+- lib/principles/views/prior_finding_decisions_result.rb
+- lib/principles/views/prior_findings_result.rb
+- lib/principles/views/problem_lines.rb
+- lib/principles/views/problem_result.rb
+- lib/principles/views/prompts.rb
+- lib/principles/views/prompts/acknowledge-a-change/say-whether-the-change-keeps-the-meaning.md
+- lib/principles/views/prompts/answer-any-judgement-request/what-a-self-audit-cannot-show.md
+- lib/principles/views/prompts/assess-every-member/answer-guide.json
+- lib/principles/views/prompts/assess-every-member/assess-each-member-and-the-set.md
+- lib/principles/views/prompts/assess-every-member/check-roles-other-principles-give-these-lines.md
+- lib/principles/views/prompts/assess-every-member/decide-each-member-loading.md
+- lib/principles/views/prompts/assess-every-member/decide-each-prior-finding.md
+- lib/principles/views/prompts/assess-every-member/give-problem-evidence-at-still-holds.md
+- lib/principles/views/prompts/assess-every-member/give-the-evidence-a-prior-finding-lacks.md
+- lib/principles/views/prompts/assess-every-member/have-a-changed-check-reviewed-before-running-it.md
+- lib/principles/views/prompts/assess-every-member/have-a-new-check-reviewed-before-running-it.md
+- lib/principles/views/prompts/assess-every-member/have-hidden-characters-in-a-check-explained.md
+- lib/principles/views/prompts/assess-every-member/judge-acknowledged-edits-together.md
+- lib/principles/views/prompts/assess-every-member/judge-the-keeping-against-the-other-principles.md
+- lib/principles/views/prompts/assess-every-member/judge-the-keeping-under-the-release-since-the-last-audit.md
+- lib/principles/views/prompts/assess-every-member/judge-the-set-with-carried-assessments.md
+- lib/principles/views/prompts/assess-every-member/keep-the-last-review-basis-unless-you-give-a-new-one.md
+- lib/principles/views/prompts/assess-every-member/name-another-principles-open-finding-rather-than-raise-it.md
+- lib/principles/views/prompts/assess-every-member/read-whether-each-prior-finding-s-evidence-changed.md
+- lib/principles/views/prompts/assess-every-member/run-a-named-check-at-every-full-audit.md
+- lib/principles/views/prompts/assess-every-member/run-the-check-then-report-it.md
+- lib/principles/views/prompts/assess-every-member/run-the-reviewed-check-and-say-what-its-review-rested-on.md
+- lib/principles/views/prompts/assess-every-member/uncommitted-files-outside-the-map.md
+- lib/principles/views/prompts/assess-every-member/why-each-member-is-judged-again.md
+- lib/principles/views/prompts/dispose-of-each-finding/answer-guide.json
+- lib/principles/views/prompts/dispose-of-each-finding/fix-or-record-each-finding.md
+- lib/principles/views/prompts/find-a-principle-to-map/ask-the-owner-before-mapping.md
+- lib/principles/views/prompts/find-a-principle-to-map/choose-one-principle.md
+- lib/principles/views/prompts/find-a-principle-to-map/owner-ask-ignored-folders.md
+- lib/principles/views/prompts/find-a-principle-to-map/owner-ask-ignored.md
+- lib/principles/views/prompts/find-a-principle-to-map/owner-ask-possibly-test-data.md
+- lib/principles/views/prompts/find-a-principle-to-map/owner-ask-untracked.md
+- lib/principles/views/prompts/find-a-principle-to-map/what-each-command-writes.md
+- lib/principles/views/prompts/find-a-principle-to-map/where-the-inventory-looks.md
+- lib/principles/views/prompts/learn-what-a-command-does/add-member.md
+- lib/principles/views/prompts/learn-what-a-command-does/change-activation.md
+- lib/principles/views/prompts/learn-what-a-command-does/change-description.md
+- lib/principles/views/prompts/learn-what-a-command-does/change-member-check.md
+- lib/principles/views/prompts/learn-what-a-command-does/change-member-role.md
+- lib/principles/views/prompts/learn-what-a-command-does/create-principle.md
+- lib/principles/views/prompts/learn-what-a-command-does/every-command-and-how-they-chain.md
+- lib/principles/views/prompts/learn-what-a-command-does/list-candidate-files.md
+- lib/principles/views/prompts/learn-what-a-command-does/list-member-problems.md
+- lib/principles/views/prompts/learn-what-a-command-does/list-open-findings.md
+- lib/principles/views/prompts/learn-what-a-command-does/list-principles.md
+- lib/principles/views/prompts/learn-what-a-command-does/move-member.md
+- lib/principles/views/prompts/learn-what-a-command-does/remove-member-check.md
+- lib/principles/views/prompts/learn-what-a-command-does/remove-member.md
+- lib/principles/views/prompts/learn-what-a-command-does/show-answer-check.md
+- lib/principles/views/prompts/learn-what-a-command-does/show-audit.md
+- lib/principles/views/prompts/learn-what-a-command-does/show-meta-principle-passage.md
+- lib/principles/views/prompts/learn-what-a-command-does/show-principle.md
+- lib/principles/views/prompts/learn-what-a-command-does/start-audit.md
+- lib/principles/views/prompts/learn-what-a-command-does/submit-answer.md
+- lib/principles/views/prompts/repoint-write-ups/point-each-moved-write-up-at-its-new-place.md
+- lib/principles/views/prompts/report-after-a-commit/it-refused-after-the-commits-touched-the-maps.md
+- lib/principles/views/prompts/report-after-a-commit/others-are-still-listed.md
+- lib/principles/views/prompts/report-after-a-commit/the-commits-changed-these-members.md
+- lib/principles/views/prompts/report-after-a-commit/this-command-shows-each-one.md
+- lib/principles/views/prompts/report-the-completed-audit/commit-only-what-the-audit-changed.md
+- lib/principles/views/prompts/report-the-completed-audit/replace-the-default-commit-message.md
+- lib/principles/views/prompts/report-the-completed-audit/what-completion-means.md
+- lib/principles/views/prompts/set-principles-up/entry-file-passage.md
+- lib/principles/views/prompts/set-principles-up/name-the-step-each-member-lacks.md
+- lib/principles/views/prompts/set-principles-up/place-the-passage-with-the-user.md
+- lib/principles/views/prompts/set-principles-up/set-up-first.md
+- lib/principles/views/prompts/set-principles-up/what-the-passage-presumes.md
+- lib/principles/views/prompts/start-a-session/act-on-the-open-findings.md
+- lib/principles/views/prompts/start-a-session/it-returns-after-each-clear-or-compaction-too.md
+- lib/principles/views/prompts/start-a-session/it-returns-at-each-session-start.md
+- lib/principles/views/prompts/start-a-session/raise-them-at-the-next-pause.md
+- lib/principles/views/prompts/start-a-session/raise-them-before-the-first-task.md
+- lib/principles/views/repoint_result.rb
+- lib/principles/views/request_part.rb
+- lib/principles/views/request_parts.rb
+- lib/principles/views/shell_word.rb
+- lib/principles/views/visible_text.rb
+- lib/principles/views/workflow_diagram.rb
+licenses: []
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.2
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '3.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Maps and audits agent guidance to catch harness drift and debt
+test_files: []