carson 1.0.0

data/lib/carson/runtime/review/sweep_support.rb

@@ -0,0 +1,252 @@
+module Carson
+	class Runtime
+		module Review
+			module SweepSupport
+			private
+
+				def sweep_findings_for_pull_request( details: )
+					pr_author = details.dig( :author, :login ).to_s
+					state = details.fetch( :state )
+					baseline_time = if [ "CLOSED", "MERGED" ].include?( state )
+						parse_time_or_nil( text: details.fetch( :merged_at ) ) || parse_time_or_nil( text: details.fetch( :closed_at ) )
+					end
+
+					findings = []
+					unresolved_thread_entries( details: details ).each do |entry|
+						thread_time = parse_time_or_nil( text: entry.fetch( :created_at ) )
+						next unless include_sweep_event?( event_time: thread_time, baseline_time: baseline_time )
+						findings << build_sweep_finding(
+							details: details,
+							kind: "unresolved_thread",
+							url: entry.fetch( :url ),
+							author: entry.fetch( :author ),
+							created_at: entry.fetch( :created_at ),
+							reason: "unresolved review thread"
+						)
+					end
+
+					Array( details.fetch( :comments ) ).each do |comment|
+						next if comment.fetch( :author ) == pr_author
+						hits = matched_risk_keywords( text: comment.fetch( :body ) )
+						next if hits.empty?
+						event_time = parse_time_or_nil( text: comment.fetch( :created_at ) )
+						next unless include_sweep_event?( event_time: event_time, baseline_time: baseline_time )
+						findings << build_sweep_finding(
+							details: details,
+							kind: "risk_issue_comment",
+							url: comment.fetch( :url ),
+							author: comment.fetch( :author ),
+							created_at: comment.fetch( :created_at ),
+							reason: "risk keywords: #{hits.join( ', ' )}"
+						)
+					end
+
+					Array( details.fetch( :reviews ) ).each do |review|
+						next if review.fetch( :author ) == pr_author
+						hits = matched_risk_keywords( text: review.fetch( :body ) )
+						next if hits.empty?
+						event_time = parse_time_or_nil( text: review.fetch( :created_at ) )
+						next unless include_sweep_event?( event_time: event_time, baseline_time: baseline_time )
+						findings << build_sweep_finding(
+							details: details,
+							kind: "risk_review",
+							url: review.fetch( :url ),
+							author: review.fetch( :author ),
+							created_at: review.fetch( :created_at ),
+							reason: "risk keywords: #{hits.join( ', ' )}"
+						)
+					end
+
+					Array( details.fetch( :review_threads ) ).flat_map { |thread| thread.fetch( :comments ) }.each do |comment|
+						next if comment.fetch( :author ) == pr_author
+						hits = matched_risk_keywords( text: comment.fetch( :body ) )
+						next if hits.empty?
+						event_time = parse_time_or_nil( text: comment.fetch( :created_at ) )
+						next unless include_sweep_event?( event_time: event_time, baseline_time: baseline_time )
+						findings << build_sweep_finding(
+							details: details,
+							kind: "risk_thread_comment",
+							url: comment.fetch( :url ),
+							author: comment.fetch( :author ),
+							created_at: comment.fetch( :created_at ),
+							reason: "risk keywords: #{hits.join( ', ' )}"
+						)
+					end
+					deduplicate_findings_by_url( items: findings )
+				end
+
+				# Inclusion guard for late-event sweep checks; closed PRs only include events after close/merge.
+				def include_sweep_event?( event_time:, baseline_time: )
+					return true if baseline_time.nil?
+					return false if event_time.nil?
+					event_time > baseline_time
+				end
+
+				# Formats one sweep finding record with PR context fields included.
+				def build_sweep_finding( details:, kind:, url:, author:, created_at:, reason: )
+					{
+						pr_number: details.fetch( :number ),
+						pr_title: details.fetch( :title ),
+						pr_url: details.fetch( :url ),
+						pr_state: details.fetch( :state ),
+						kind: kind,
+						url: url,
+						author: author,
+						created_at: created_at.to_s,
+						reason: reason
+					}
+				end
+
+				# Upserts one rolling tracking issue that captures latest sweep findings.
+				def upsert_review_sweep_tracking_issue( owner:, repo:, findings: )
+					slug = "#{owner}/#{repo}"
+					ensure_review_sweep_label( repo_slug: slug )
+					issue = find_review_sweep_issue( repo_slug: slug )
+					if findings.empty?
+						return close_review_sweep_issue_if_open( repo_slug: slug, issue: issue )
+					end
+					body = render_review_sweep_issue_body( findings: findings )
+					if issue.nil?
+						stdout_text, stderr_text, success, = gh_run(
+							"issue", "create",
+							"--repo", slug,
+							"--title", config.review_tracking_issue_title,
+							"--body", body,
+							"--label", config.review_tracking_issue_label
+						)
+						raise gh_error_text( stdout_text: stdout_text, stderr_text: stderr_text, fallback: "unable to create review sweep tracking issue" ) unless success
+						issue = find_review_sweep_issue( repo_slug: slug )
+						return issue.nil? ? { action: "create_unknown", issue: nil } : { action: "created", issue: issue }
+					end
+
+					if issue.fetch( :state ) == "CLOSED"
+						gh_system!( "issue", "reopen", issue.fetch( :number ).to_s, "--repo", slug )
+					end
+					gh_system!(
+						"issue", "edit", issue.fetch( :number ).to_s,
+						"--repo", slug,
+						"--title", config.review_tracking_issue_title,
+						"--body", body,
+						"--add-label", config.review_tracking_issue_label
+					)
+					updated_issue = find_review_sweep_issue( repo_slug: slug )
+					{ action: issue.fetch( :state ) == "CLOSED" ? "reopened_updated" : "updated", issue: updated_issue || issue }
+				end
+
+				# Creates/updates sweep tracking label so issue upsert can apply a stable filter tag.
+				def ensure_review_sweep_label( repo_slug: )
+					gh_system!(
+						"label", "create", config.review_tracking_issue_label,
+						"--repo", repo_slug,
+						"--description", "Carson review sweep tracking",
+						"--color", "B60205",
+						"--force"
+					)
+				end
+
+				# Finds rolling tracking issue by exact configured title.
+				def find_review_sweep_issue( repo_slug: )
+					stdout_text, stderr_text, success, = gh_run( "issue", "list", "--repo", repo_slug, "--state", "all", "--limit", "100", "--json", "number,title,state,url,labels" )
+					raise gh_error_text( stdout_text: stdout_text, stderr_text: stderr_text, fallback: "unable to list issues for review sweep" ) unless success
+					issues = Array( JSON.parse( stdout_text ) )
+					node = issues.find { |entry| entry[ "title" ].to_s == config.review_tracking_issue_title }
+					return nil if node.nil?
+					{
+						number: node[ "number" ],
+						title: node[ "title" ].to_s,
+						state: node[ "state" ].to_s.upcase,
+						url: node[ "url" ].to_s
+					}
+				end
+
+				# When sweep is clear, close prior tracking issue and add one clear audit comment.
+				def close_review_sweep_issue_if_open( repo_slug:, issue: )
+					return { action: "none", issue: nil } if issue.nil?
+					return { action: "none", issue: issue } unless issue.fetch( :state ) == "OPEN"
+					clear_message = "Clear: no actionable late review activity detected at #{Time.now.utc.iso8601}."
+					gh_system!( "issue", "comment", issue.fetch( :number ).to_s, "--repo", repo_slug, "--body", clear_message )
+					gh_system!( "issue", "close", issue.fetch( :number ).to_s, "--repo", repo_slug )
+					closed_issue = find_review_sweep_issue( repo_slug: repo_slug )
+					{ action: "closed", issue: closed_issue || issue }
+				end
+
+				# Markdown body used by rolling sweep issue so latest findings are always in one place.
+				def render_review_sweep_issue_body( findings: )
+					lines = []
+					lines << "# Carson review sweep findings"
+					lines << ""
+					lines << "- Generated at: #{Time.now.utc.iso8601}"
+					lines << "- Window days: #{config.review_sweep_window_days}"
+					lines << "- States: #{config.review_sweep_states.join( ', ' )}"
+					lines << "- Finding count: #{findings.count}"
+					lines << ""
+					lines << "## Findings"
+					if findings.empty?
+						lines << "- none"
+					else
+						findings.each do |item|
+							lines << "- PR ##{item.fetch( :pr_number )} (#{item.fetch( :pr_state )}) #{item.fetch( :kind )}: #{item.fetch( :reason )}"
+							lines << "  - URL: #{item.fetch( :url )}"
+							lines << "  - Author: #{item.fetch( :author )}"
+							lines << "  - Created at: #{item.fetch( :created_at )}"
+						end
+					end
+					lines.join( "\n" )
+				end
+
+				# Writes sweep artefacts for CI logs and local troubleshooting.
+				def write_review_sweep_report( report: )
+					markdown_path, json_path = write_report(
+						report: report,
+						markdown_name: REVIEW_SWEEP_REPORT_MD,
+						json_name: REVIEW_SWEEP_REPORT_JSON,
+						renderer: method( :render_review_sweep_markdown )
+					)
+					puts_line "review_sweep_report_markdown: #{markdown_path}"
+					puts_line "review_sweep_report_json: #{json_path}"
+				rescue StandardError => e
+					puts_line "review_sweep_report_write: SKIP (#{e.message})"
+				end
+
+				# Human-readable scheduled sweep report.
+				def render_review_sweep_markdown( report: )
+					lines = []
+					lines << "# Carson Review Sweep Report"
+					lines << ""
+					lines << "- Generated at: #{report.fetch( :generated_at )}"
+					lines << "- Status: #{report.fetch( :status )}"
+					lines << "- Window days: #{report.fetch( :window_days )}"
+					lines << "- States: #{Array( report.fetch( :states ) ).join( ', ' )}"
+					lines << "- Cutoff time: #{report.fetch( :cutoff_time )}"
+					lines << "- Candidate count: #{report.fetch( :candidate_count )}"
+					lines << "- Finding count: #{report.fetch( :finding_count )}"
+					tracking_issue = report[ :tracking_issue ]
+					if tracking_issue.is_a?( Hash )
+						lines << "- Tracking issue action: #{tracking_issue.fetch( :action )}"
+						if tracking_issue[ :issue ].is_a?( Hash )
+							lines << "- Tracking issue URL: #{tracking_issue.dig( :issue, :url )}"
+						end
+					end
+					lines << ""
+					lines << "## Findings"
+					if report.fetch( :findings ).empty?
+						lines << "- none"
+					else
+						report.fetch( :findings ).each do |item|
+							lines << "- PR ##{item.fetch( :pr_number )} (#{item.fetch( :pr_state )}) #{item.fetch( :kind )}: #{item.fetch( :reason )}"
+							lines << "  - URL: #{item.fetch( :url )}"
+							lines << "  - Author: #{item.fetch( :author )}"
+							lines << "  - Created at: #{item.fetch( :created_at )}"
+						end
+					end
+					lines.join( "\n" )
+				end
+
+				# Sweep state mapping treats merged PRs as closed for state-based inclusion filtering.
+				def sweep_state_for( pr_state: )
+					pr_state.to_s.upcase == "OPEN" ? "open" : "closed"
+				end
+			end
+		end
+	end
+end

data/lib/carson/runtime/review/utility.rb

@@ -0,0 +1,63 @@
+module Carson
+	class Runtime
+		module Review
+			module Utility
+			private
+
+				# Returns matching risk keywords using case-insensitive whole-word matching.
+				def matched_risk_keywords( text: )
+					text_value = text.to_s
+					config.review_risk_keywords.select do |keyword|
+						text_value.match?( /\b#{Regexp.escape( keyword )}\b/i )
+					end
+				end
+
+				# Disposition records always start with configured prefix.
+				def disposition_prefixed?( text: )
+					text.to_s.lstrip.start_with?( config.review_disposition_prefix )
+				end
+
+				# Extracts first matching disposition token from configured acknowledgement body.
+				def disposition_token( text: )
+					DISPOSITION_TOKENS.find { |token| text.to_s.match?( /\b#{token}\b/i ) }
+				end
+
+				# GitHub URL extraction for mapping disposition acknowledgements to finding URLs.
+				def extract_github_urls( text: )
+					text.to_s.scan( %r{https://github\.com/[^\s\)\]]+} ).map { |value| value.sub( /[.,;:]+$/, "" ) }.uniq
+				end
+
+				# Parse RFC3339 timestamps and return nil on blank/invalid values.
+				def parse_time_or_nil( text: )
+					value = text.to_s.strip
+					return nil if value.empty?
+					Time.parse( value )
+				rescue ArgumentError
+					nil
+				end
+
+				# Removes duplicate finding URLs while preserving first occurrence ordering.
+				def deduplicate_findings_by_url( items: )
+					seen = {}
+					Array( items ).each_with_object( [] ) do |entry, result|
+						url = entry.fetch( :url ).to_s
+						next if url.empty? || seen.key?( url )
+						seen[ url ] = true
+						result << entry
+					end
+				end
+
+				# Shared report writer for JSON plus Markdown pairs in global report output.
+				def write_report( report:, markdown_name:, json_name:, renderer: )
+					report_dir = report_dir_path
+					FileUtils.mkdir_p( report_dir )
+					markdown_path = File.join( report_dir, markdown_name )
+					json_path = File.join( report_dir, json_name )
+					File.write( json_path, JSON.pretty_generate( report ) )
+					File.write( markdown_path, renderer.call( report: report ) )
+					[ markdown_path, json_path ]
+				end
+			end
+		end
+	end
+end

data/lib/carson/runtime/review.rb

@@ -0,0 +1,182 @@
+require_relative "review/query_text"
+require_relative "review/data_access"
+require_relative "review/gate_support"
+require_relative "review/sweep_support"
+require_relative "review/utility"
+
+module Carson
+	class Runtime
+		module Review
+			include QueryText
+			include DataAccess
+			include GateSupport
+			include SweepSupport
+			include Utility
+
+			def review_gate!
+				fingerprint_status = block_if_outsider_fingerprints!
+				return fingerprint_status unless fingerprint_status.nil?
+				print_header "Review Gate"
+				unless gh_available?
+					puts_line "ERROR: gh CLI not available in PATH."
+					return EXIT_ERROR
+				end
+
+				owner, repo = repository_coordinates
+				pr_number_override = carson_pr_number_override
+				pr_summary =
+					if pr_number_override.nil?
+						current_pull_request_for_branch( branch_name: current_branch )
+					else
+						details = pull_request_details( owner: owner, repo: repo, pr_number: pr_number_override )
+						{
+							number: details.fetch( :number ),
+							title: details.fetch( :title ),
+							url: details.fetch( :url ),
+							state: details.fetch( :state )
+						}
+					end
+				if pr_summary.nil?
+					puts_line "BLOCK: no pull request found for branch #{current_branch}."
+					report = {
+						generated_at: Time.now.utc.iso8601,
+						branch: current_branch,
+						status: "block",
+						converged: false,
+						wait_seconds: config.review_wait_seconds,
+						poll_seconds: config.review_poll_seconds,
+						max_polls: config.review_max_polls,
+						block_reasons: [ "no pull request found for current branch" ],
+						pr: nil,
+						unresolved_threads: [],
+						actionable_top_level: [],
+						unacknowledged_actionable: []
+					}
+					write_review_gate_report( report: report )
+					return EXIT_BLOCK
+				end
+
+				wait_for_review_warmup
+				converged = false
+				last_snapshot = nil
+				last_signature = nil
+				poll_attempts = 0
+
+				config.review_max_polls.times do |index|
+					poll_attempts = index + 1
+					snapshot = review_gate_snapshot( owner: owner, repo: repo, pr_number: pr_summary.fetch( :number ) )
+					last_snapshot = snapshot
+					signature = review_gate_signature( snapshot: snapshot )
+					puts_line "poll_attempt: #{poll_attempts}/#{config.review_max_polls}"
+					puts_line "latest_activity: #{snapshot.fetch( :latest_activity ) || 'unknown'}"
+					puts_line "unresolved_threads: #{snapshot.fetch( :unresolved_threads ).count}"
+					puts_line "unacknowledged_actionable: #{snapshot.fetch( :unacknowledged_actionable ).count}"
+					if !last_signature.nil? && signature == last_signature
+						converged = true
+						puts_line "convergence: stable"
+						break
+					end
+					last_signature = signature
+					wait_for_review_poll if index < config.review_max_polls - 1
+				end
+
+				block_reasons = []
+				block_reasons << "review snapshot did not converge within #{config.review_max_polls} polls" unless converged
+				if last_snapshot.fetch( :unresolved_threads ).any?
+					block_reasons << "unresolved review threads remain (#{last_snapshot.fetch( :unresolved_threads ).count})"
+				end
+				if last_snapshot.fetch( :unacknowledged_actionable ).any?
+					block_reasons << "actionable top-level comments/reviews without required disposition (#{last_snapshot.fetch( :unacknowledged_actionable ).count})"
+				end
+
+				report = {
+					generated_at: Time.now.utc.iso8601,
+					branch: current_branch,
+					status: block_reasons.empty? ? "ok" : "block",
+					converged: converged,
+					wait_seconds: config.review_wait_seconds,
+					poll_seconds: config.review_poll_seconds,
+					max_polls: config.review_max_polls,
+					poll_attempts: poll_attempts,
+					block_reasons: block_reasons,
+					pr: {
+						number: pr_summary.fetch( :number ),
+						title: pr_summary.fetch( :title ),
+						url: pr_summary.fetch( :url ),
+						state: pr_summary.fetch( :state )
+					},
+					unresolved_threads: last_snapshot.fetch( :unresolved_threads ),
+					actionable_top_level: last_snapshot.fetch( :actionable_top_level ),
+					unacknowledged_actionable: last_snapshot.fetch( :unacknowledged_actionable )
+				}
+				write_review_gate_report( report: report )
+				if block_reasons.empty?
+					puts_line "OK: review gate passed."
+					return EXIT_OK
+				end
+				block_reasons.each { |reason| puts_line "BLOCK: #{reason}" }
+				EXIT_BLOCK
+			rescue JSON::ParserError => e
+				puts_line "ERROR: invalid gh JSON response (#{e.message})."
+				EXIT_ERROR
+			rescue StandardError => e
+				puts_line "ERROR: #{e.message}"
+				EXIT_ERROR
+			end
+
+			# Scheduled sweep for late actionable review activity across recent pull requests.
+			def review_sweep!
+				fingerprint_status = block_if_outsider_fingerprints!
+				return fingerprint_status unless fingerprint_status.nil?
+				print_header "Review Sweep"
+				unless gh_available?
+					puts_line "ERROR: gh CLI not available in PATH."
+					return EXIT_ERROR
+				end
+
+				owner, repo = repository_coordinates
+				cutoff_time = Time.now.utc - ( config.review_sweep_window_days * 86_400 )
+				pull_requests = recent_pull_requests_for_sweep( owner: owner, repo: repo, cutoff_time: cutoff_time )
+				puts_line "window_days: #{config.review_sweep_window_days}"
+				puts_line "candidate_prs: #{pull_requests.count}"
+				findings = []
+
+				pull_requests.each do |entry|
+					next unless config.review_sweep_states.include?( sweep_state_for( pr_state: entry.fetch( :state ) ) )
+					details = pull_request_details( owner: owner, repo: repo, pr_number: entry.fetch( :number ) )
+					findings.concat( sweep_findings_for_pull_request( details: details ) )
+				end
+
+				findings.sort_by! { |item| [ item.fetch( :pr_number ), item.fetch( :created_at ).to_s, item.fetch( :url ) ] }
+				issue_result = upsert_review_sweep_tracking_issue( owner: owner, repo: repo, findings: findings )
+				report = {
+					generated_at: Time.now.utc.iso8601,
+					status: findings.empty? ? "ok" : "block",
+					window_days: config.review_sweep_window_days,
+					states: config.review_sweep_states,
+					cutoff_time: cutoff_time.utc.iso8601,
+					candidate_count: pull_requests.count,
+					finding_count: findings.count,
+					findings: findings,
+					tracking_issue: issue_result
+				}
+				write_review_sweep_report( report: report )
+				puts_line "finding_count: #{findings.count}"
+				if findings.empty?
+					puts_line "OK: no actionable late review activity detected."
+					return EXIT_OK
+				end
+				puts_line "BLOCK: actionable late review activity detected."
+				EXIT_BLOCK
+			rescue JSON::ParserError => e
+				puts_line "ERROR: invalid gh JSON response (#{e.message})."
+				EXIT_ERROR
+			rescue StandardError => e
+				puts_line "ERROR: #{e.message}"
+				EXIT_ERROR
+			end
+		end
+
+		include Review
+	end
+end

data/lib/carson/runtime.rb

@@ -0,0 +1,182 @@
+# Carson runtime wiring and shared helper layer.
+# Centralises command-neutral concerns such as output contracts, path resolution,
+# adapter invocation, and report-location policy.
+require "fileutils"
+require "json"
+require "time"
+
+module Carson
+	class Runtime
+		# Shared exit-code contract used by all commands and CI smoke assertions.
+		EXIT_OK = 0
+		EXIT_ERROR = 1
+		EXIT_BLOCK = 2
+
+		REPORT_MD = "pr_report_latest.md".freeze
+		REPORT_JSON = "pr_report_latest.json".freeze
+		REVIEW_GATE_REPORT_MD = "review_gate_latest.md".freeze
+		REVIEW_GATE_REPORT_JSON = "review_gate_latest.json".freeze
+		REVIEW_SWEEP_REPORT_MD = "review_sweep_latest.md".freeze
+		REVIEW_SWEEP_REPORT_JSON = "review_sweep_latest.json".freeze
+		DISPOSITION_TOKENS = %w[accepted rejected deferred].freeze
+
+		# Runtime wiring for repository context, tool paths, and output streams.
+		def initialize( repo_root:, tool_root:, out:, err: )
+			@repo_root = repo_root
+			@tool_root = tool_root
+			@out = out
+			@err = err
+			@config = Config.load( repo_root: repo_root )
+			@git_adapter = Adapters::Git.new( repo_root: repo_root )
+			@github_adapter = Adapters::GitHub.new( repo_root: repo_root )
+		end
+
+	private
+
+		attr_reader :repo_root, :tool_root, :out, :err, :config, :git_adapter, :github_adapter
+
+		# Current local branch name.
+		def current_branch
+			git_capture!( "rev-parse", "--abbrev-ref", "HEAD" ).strip
+		end
+
+		# Checks local branch existence before restore attempts in ensure blocks.
+		def branch_exists?( branch_name: )
+			_, _, success, = git_run( "show-ref", "--verify", "--quiet", "refs/heads/#{branch_name}" )
+			success
+		end
+
+		# Human-readable plural suffix helper for audit messaging.
+		def plural_suffix( count: )
+			count.to_i == 1 ? "" : "s"
+		end
+
+		# Section heading printer for command output.
+		def print_header( title )
+			puts_line ""
+			puts_line "[#{title}]"
+		end
+
+		# Single output funnel to keep messaging style consistent.
+		def puts_line( message )
+			out.puts message
+		end
+
+		# Converts absolute paths into repo-relative output paths.
+		def relative_path( absolute_path )
+			absolute_path.sub( "#{repo_root}/", "" )
+		end
+
+		# Resolves a repo-relative path and blocks traversal outside repository root.
+		def resolve_repo_path!( relative_path:, label: )
+			path = File.expand_path( relative_path.to_s, repo_root )
+			repo_root_prefix = File.join( repo_root, "" )
+			raise ConfigError, "#{label} must stay within repository root" unless path.start_with?( repo_root_prefix )
+			path
+		end
+
+		# Resolves report output precedence:
+		# 1) ~/.cache/carson when HOME is an absolute path
+		# 2) TMPDIR/carson when HOME is invalid and TMPDIR is absolute
+		# 3) /tmp/carson as final safety fallback
+		def report_dir_path
+			home = ENV.fetch( "HOME", "" ).to_s
+			return File.join( home, ".cache", "carson" ) if absolute_env_path?( path: home )
+
+			tmpdir = ENV.fetch( "TMPDIR", "" ).to_s
+			return File.join( tmpdir, "carson" ) if absolute_env_path?( path: tmpdir )
+
+			"/tmp/carson"
+		rescue StandardError
+			"/tmp/carson"
+		end
+
+		# Treats empty or non-absolute environment paths as invalid.
+		def absolute_env_path?( path: )
+			text = path.to_s
+			!text.empty? && text.start_with?( "/" )
+		end
+
+		# Soft capability check for GitHub CLI presence.
+		def gh_available?
+			_, _, success, = gh_run( "--version" )
+			success
+		end
+
+		# Keeps check output fields stable even when gh returns blanks.
+		def normalise_check_entries( entries: )
+			Array( entries ).map do |entry|
+				{
+					workflow: blank_to( value: entry[ "workflow" ], default: "workflow" ),
+					name: blank_to( value: entry[ "name" ], default: "check" ),
+					state: blank_to( value: entry[ "state" ], default: "UNKNOWN" ),
+					link: entry[ "link" ].to_s
+				}
+			end
+		end
+
+		# Coalesces blank strings to explicit defaults.
+		def blank_to( value:, default: )
+			text = value.to_s.strip
+			text.empty? ? default : text
+		end
+
+		# Chooses best available error text from gh stderr/stdout.
+		def gh_error_text( stdout_text:, stderr_text:, fallback: )
+			combined = [ stderr_text.to_s.strip, stdout_text.to_s.strip ].reject( &:empty? ).join( " | " )
+			combined.empty? ? fallback : combined
+		end
+
+		# Runs gh command and raises with best available stderr/stdout details on failure.
+		def gh_system!( *args )
+			stdout_text, stderr_text, success, = gh_run( *args )
+			raise gh_error_text( stdout_text: stdout_text, stderr_text: stderr_text, fallback: "gh #{args.join( ' ' )} failed" ) unless success
+			stdout_text
+		end
+
+		# Captures gh output without raising so callers can fall back when host metadata is unavailable.
+		def gh_capture_soft( *args )
+			stdout_text, stderr_text, success, = gh_run( *args )
+			[ stdout_text, stderr_text, success ]
+		end
+
+		# Runs git command, streams outputs, and raises on non-zero exit.
+		def git_system!( *args )
+			stdout_text, stderr_text, success, = git_run( *args )
+			out.print stdout_text unless stdout_text.empty?
+			err.print stderr_text unless stderr_text.empty?
+			raise "git #{args.join( ' ' )} failed" unless success
+		end
+
+		# Captures git stdout and raises on non-zero exit.
+		def git_capture!( *args )
+			stdout_text, stderr_text, success, = git_run( *args )
+			unless success
+				err.print stderr_text unless stderr_text.empty?
+				raise "git #{args.join( ' ' )} failed"
+			end
+			stdout_text
+		end
+
+		# Captures git output without raising so caller can decide behaviour.
+		def git_capture_soft( *args )
+			stdout_text, stderr_text, success, = git_run( *args )
+			[ stdout_text, stderr_text, success ]
+		end
+
+		# Low-level git invocation wrapper.
+		def git_run( *args )
+			git_adapter.run( *args )
+		end
+
+		# Low-level gh invocation wrapper.
+		def gh_run( *args )
+			github_adapter.run( *args )
+		end
+	end
+end
+
+require_relative "runtime/local"
+require_relative "runtime/lint"
+require_relative "runtime/audit"
+require_relative "runtime/review"

data/lib/carson/version.rb

@@ -0,0 +1,4 @@
+module Carson
+	version_path = File.expand_path( "../../VERSION", __dir__ )
+	VERSION = File.file?( version_path ) ? File.read( version_path ).strip : "0.0.0"
+end

data/lib/carson.rb

@@ -0,0 +1,6 @@
+require_relative "carson/version"
+require_relative "carson/config"
+require_relative "carson/adapters/git"
+require_relative "carson/adapters/github"
+require_relative "carson/runtime"
+require_relative "carson/cli"