carson 3.19.0 → 3.21.0

data/lib/carson/config.rb

@@ -1,3 +1,4 @@
+# Loads and validates Carson configuration from global config and environment overrides.
 require "json"
 
 module Carson
@@ -85,8 +86,8 @@ module Carson
 			parsed = JSON.parse( raw )
 			raise ConfigError, "global config must be a JSON object at #{path}" unless parsed.is_a?( Hash )
 			parsed
-		rescue JSON::ParserError => e
-			raise ConfigError, "invalid global config JSON at #{path} (#{e.message})"
+		rescue JSON::ParserError => exception
+			raise ConfigError, "invalid global config JSON at #{path} (#{exception.message})"
 		end
 
 		def self.global_config_path( repo_root: )
@@ -212,7 +213,7 @@ module Carson
 			@audit_advisory_check_names = fetch_optional_string_array( hash: audit_hash, key: "advisory_check_names" )
 
 			govern_hash = fetch_hash( hash: data, key: "govern" )
-			@govern_repos = fetch_optional_string_array( hash: govern_hash, key: "repos" ).map { |p| safe_expand_path( p ) }
+			@govern_repos = fetch_optional_string_array( hash: govern_hash, key: "repos" ).map { |path| safe_expand_path( path ) }
 			@govern_auto_merge = fetch_optional_boolean( hash: govern_hash, key: "auto_merge", default: true, key_path: "govern.auto_merge" )
 			@govern_merge_method = fetch_string( hash: govern_hash, key: "merge_method" ).downcase
 			govern_agent_hash = fetch_hash( hash: govern_hash, key: "agent" )

data/lib/carson/runtime/audit.rb

@@ -11,7 +11,7 @@ module Carson
 				return fingerprint_status unless fingerprint_status.nil?
 				unless head_exists?
 					if json_output
-						out.puts JSON.pretty_generate( { command: "audit", status: "skipped", reason: "no commits yet", exit_code: EXIT_OK } )
+						output.puts JSON.pretty_generate( { command: "audit", status: "skipped", reason: "no commits yet", exit_code: EXIT_OK } )
 					else
 						puts_line "No commits yet — audit skipped for initial commit."
 					end
@@ -69,24 +69,24 @@ module Carson
 				audit_state = "attention" if audit_state == "ok" && !%w[ok skipped].include?( monitor_report.fetch( :status ) )
 				if monitor_report.fetch( :status ) == "attention"
 					checks = monitor_report.fetch( :checks )
-					fail_n = checks.fetch( :failing_count )
-					pend_n = checks.fetch( :pending_count )
+					failing_count = checks.fetch( :failing_count )
+					pending_count = checks.fetch( :pending_count )
 					total = checks.fetch( :required_total )
 					fail_names = checks.fetch( :failing ).map { it.fetch( :name ) }.join( ", " )
-					if fail_n.positive? && pend_n.positive?
-						audit_concise_problems << "Checks: #{fail_n} failing (#{fail_names}), #{pend_n} pending of #{total} required."
-					elsif fail_n.positive?
-						audit_concise_problems << "Checks: #{fail_n} of #{total} failing (#{fail_names})."
-					elsif pend_n.positive?
-						audit_concise_problems << "Checks: pending (#{total - pend_n} of #{total} complete)."
+					if failing_count.positive? && pending_count.positive?
+						audit_concise_problems << "Checks: #{failing_count} failing (#{fail_names}), #{pending_count} pending of #{total} required."
+					elsif failing_count.positive?
+						audit_concise_problems << "Checks: #{failing_count} of #{total} failing (#{fail_names})."
+					elsif pending_count.positive?
+						audit_concise_problems << "Checks: pending (#{total - pending_count} of #{total} complete)."
 					end
 				end
 				puts_verbose ""
 				puts_verbose "[Default Branch CI Baseline (gh)]"
 				default_branch_baseline = default_branch_ci_baseline_report
 				audit_state = "attention" if audit_state == "ok" && !%w[ok skipped].include?( default_branch_baseline.fetch( :status ) )
-				baseline_st = default_branch_baseline.fetch( :status )
-				if baseline_st == "block"
+				baseline_status = default_branch_baseline.fetch( :status )
+				if baseline_status == "block"
 					parts = []
 					if default_branch_baseline.fetch( :failing_count ).positive?
 						names = default_branch_baseline.fetch( :failing ).map { it.fetch( :name ) }.join( ", " )
@@ -98,7 +98,7 @@ module Carson
 					end
 					parts << "no check-runs for active workflows" if default_branch_baseline.fetch( :no_check_evidence )
 					audit_concise_problems << "Baseline (#{default_branch_baseline.fetch( :default_branch, config.main_branch )}): #{parts.join( ', ' )} — fix before merge."
-				elsif baseline_st == "attention"
+				elsif baseline_status == "attention"
 					parts = []
 					if default_branch_baseline.fetch( :advisory_failing_count ).positive?
 						names = default_branch_baseline.fetch( :advisory_failing ).map { it.fetch( :name ) }.join( ", " )
@@ -143,7 +143,7 @@ module Carson
 						problems: audit_concise_problems,
 						exit_code: exit_code
 					}
-					out.puts JSON.pretty_generate( result )
+					output.puts JSON.pretty_generate( result )
 				else
 					puts_verbose ""
 					puts_verbose "[Audit Result]"
@@ -182,8 +182,8 @@ module Carson
 					end
 
 					begin
-						rt = build_scoped_runtime( repo_path: repo_path )
-						status = rt.audit!
+						scoped_runtime = build_scoped_runtime( repo_path: repo_path )
+						status = scoped_runtime.audit!
 						case status
 						when EXIT_OK
 							puts_line "#{repo_name}: ok" unless verbose?
@@ -197,9 +197,9 @@ module Carson
 							record_batch_skip( command: "audit", repo_path: repo_path, reason: "audit failed" )
 							failed += 1
 						end
-					rescue StandardError => e
-						puts_line "#{repo_name}: FAIL (#{e.message})"
-						record_batch_skip( command: "audit", repo_path: repo_path, reason: e.message )
+					rescue StandardError => exception
+						puts_line "#{repo_name}: FAIL (#{exception.message})"
+						record_batch_skip( command: "audit", repo_path: repo_path, reason: exception.message )
 						failed += 1
 					end
 				end
@@ -212,20 +212,20 @@ module Carson
 		private
 			def pr_and_check_report
 				report = {
-				generated_at: Time.now.utc.iso8601,
-				branch: current_branch,
-				status: "ok",
-				skip_reason: nil,
-				pr: nil,
-				checks: {
-				status: "unknown",
-				skip_reason: nil,
-				required_total: 0,
-				failing_count: 0,
-				pending_count: 0,
-				failing: [],
-				pending: []
-				}
+					generated_at: Time.now.utc.iso8601,
+					branch: current_branch,
+					status: "ok",
+					skip_reason: nil,
+					pr: nil,
+					checks: {
+						status: "unknown",
+						skip_reason: nil,
+						required_total: 0,
+						failing_count: 0,
+						pending_count: 0,
+						failing: [],
+						pending: []
+					}
 				}
 				unless gh_available?
 					report[ :status ] = "skipped"
@@ -243,11 +243,11 @@ module Carson
 				end
 				pr_data = JSON.parse( pr_stdout )
 				report[ :pr ] = {
-				number: pr_data[ "number" ],
-				title: pr_data[ "title" ].to_s,
-				url: pr_data[ "url" ].to_s,
-				state: pr_data[ "state" ].to_s,
-				review_decision: blank_to( value: pr_data[ "reviewDecision" ], default: "NONE" )
+					number: pr_data[ "number" ],
+					title: pr_data[ "title" ].to_s,
+					url: pr_data[ "url" ].to_s,
+					state: pr_data[ "state" ].to_s,
+					review_decision: blank_to( value: pr_data[ "reviewDecision" ], default: "NONE" )
 				}
 				puts_verbose "pr: ##{report.dig( :pr, :number )} #{report.dig( :pr, :title )}"
 				puts_verbose "url: #{report.dig( :pr, :url )}"
@@ -277,9 +277,9 @@ module Carson
 				report.dig( :checks, :pending ).each { |entry| puts_verbose "check_pending: #{entry.fetch( :workflow )} / #{entry.fetch( :name )} #{entry.fetch( :link )}".strip }
 				report[ :status ] = "attention" if report.dig( :checks, :failing_count ).positive? || report.dig( :checks, :pending_count ).positive?
 				report
-				rescue JSON::ParserError => e
+				rescue JSON::ParserError => exception
 					report[ :status ] = "skipped"
-					report[ :skip_reason ] = "invalid gh JSON response (#{e.message})"
+					report[ :skip_reason ] = "invalid gh JSON response (#{exception.message})"
 					puts_verbose "SKIP: #{report.fetch( :skip_reason )}"
 					report
 				end
@@ -287,22 +287,22 @@ module Carson
 			# Evaluates default-branch CI health so stale workflow drift blocks before merge.
 			def default_branch_ci_baseline_report
 				report = {
-				status: "ok",
-				skip_reason: nil,
-				repository: nil,
-				default_branch: nil,
-				head_sha: nil,
-				workflows_total: 0,
-				check_runs_total: 0,
-				failing_count: 0,
-				pending_count: 0,
-				advisory_failing_count: 0,
-				advisory_pending_count: 0,
-				no_check_evidence: false,
-				failing: [],
-				pending: [],
-				advisory_failing: [],
-				advisory_pending: []
+					status: "ok",
+					skip_reason: nil,
+					repository: nil,
+					default_branch: nil,
+					head_sha: nil,
+					workflows_total: 0,
+					check_runs_total: 0,
+					failing_count: 0,
+					pending_count: 0,
+					advisory_failing_count: 0,
+					advisory_pending_count: 0,
+					no_check_evidence: false,
+					failing: [],
+					pending: [],
+					advisory_failing: [],
+					advisory_pending: []
 				}
 				unless gh_available?
 					report[ :status ] = "skipped"
@@ -313,30 +313,30 @@ module Carson
 				owner, repo = repository_coordinates
 				report[ :repository ] = "#{owner}/#{repo}"
 				repository_data = gh_json_payload!(
-				"api", "repos/#{owner}/#{repo}",
-				"--method", "GET",
-				fallback: "unable to read repository metadata for #{owner}/#{repo}"
+					"api", "repos/#{owner}/#{repo}",
+					"--method", "GET",
+					fallback: "unable to read repository metadata for #{owner}/#{repo}"
 				)
 				default_branch = blank_to( value: repository_data[ "default_branch" ], default: config.main_branch )
 				report[ :default_branch ] = default_branch
 				branch_data = gh_json_payload!(
-				"api", "repos/#{owner}/#{repo}/branches/#{CGI.escape( default_branch )}",
-				"--method", "GET",
-				fallback: "unable to read default branch #{default_branch}"
+					"api", "repos/#{owner}/#{repo}/branches/#{CGI.escape( default_branch )}",
+					"--method", "GET",
+					fallback: "unable to read default branch #{default_branch}"
 				)
 				head_sha = branch_data.dig( "commit", "sha" ).to_s.strip
 				raise "default branch #{default_branch} has no commit SHA" if head_sha.empty?
 				report[ :head_sha ] = head_sha
 				workflow_entries = default_branch_workflow_entries(
-				owner: owner,
-				repo: repo,
-				default_branch: default_branch
+					owner: owner,
+					repo: repo,
+					default_branch: default_branch
 				)
 				report[ :workflows_total ] = workflow_entries.count
 				check_runs_payload = gh_json_payload!(
-				"api", "repos/#{owner}/#{repo}/commits/#{head_sha}/check-runs",
-				"--method", "GET",
-				fallback: "unable to read check-runs for #{default_branch}@#{head_sha}"
+					"api", "repos/#{owner}/#{repo}/commits/#{head_sha}/check-runs",
+					"--method", "GET",
+					fallback: "unable to read check-runs for #{default_branch}@#{head_sha}"
 				)
 				check_runs = Array( check_runs_payload[ "check_runs" ] )
 				failing, pending = partition_default_branch_check_runs( check_runs: check_runs )
@@ -374,14 +374,14 @@ module Carson
 					puts_verbose "ACTION: default branch has workflow files but no check-runs; align workflow triggers and branch protection check names."
 				end
 				report
-			rescue JSON::ParserError => e
+			rescue JSON::ParserError => exception
 				report[ :status ] = "skipped"
-				report[ :skip_reason ] = "invalid gh JSON response (#{e.message})"
+				report[ :skip_reason ] = "invalid gh JSON response (#{exception.message})"
 				puts_verbose "baseline: SKIP (#{report.fetch( :skip_reason )})"
 				report
-			rescue StandardError => e
+			rescue StandardError => exception
 				report[ :status ] = "skipped"
-				report[ :skip_reason ] = e.message
+				report[ :skip_reason ] = exception.message
 				puts_verbose "baseline: SKIP (#{report.fetch( :skip_reason )})"
 				report
 			end
@@ -399,15 +399,15 @@ module Carson
 			# Reads workflow files from default branch; missing workflow directory is valid and returns none.
 			def default_branch_workflow_entries( owner:, repo:, default_branch: )
 				stdout_text, stderr_text, success, = gh_run(
-				"api", "repos/#{owner}/#{repo}/contents/.github/workflows",
-				"--method", "GET",
-				"-f", "ref=#{default_branch}"
+					"api", "repos/#{owner}/#{repo}/contents/.github/workflows",
+					"--method", "GET",
+					"-f", "ref=#{default_branch}"
 				)
 				unless success
 					error_text = gh_error_text(
-					stdout_text: stdout_text,
-					stderr_text: stderr_text,
-					fallback: "unable to read workflow files for #{default_branch}"
+						stdout_text: stdout_text,
+						stderr_text: stderr_text,
+						fallback: "unable to read workflow files for #{default_branch}"
 					)
 					return [] if error_text.match?( /\b404\b/ )
 					raise error_text
@@ -443,7 +443,7 @@ module Carson
 			end
 
 			# Returns true when a required-check entry is in a non-passing, non-pending state.
-			# Cancelled, errored, timed-out, and any unknown bucket all count as failing.
+			# Cancelled, errored, timed-output, and any unknown bucket all count as failing.
 			def check_entry_failing?( entry: )
 				!%w[pass pending].include?( entry[ "bucket" ].to_s )
 			end
@@ -474,10 +474,10 @@ module Carson
 						blank_to( value: entry[ "status" ], default: "UNKNOWN" )
 					end
 					{
-					workflow: blank_to( value: entry.dig( "app", "name" ), default: "workflow" ),
-					name: blank_to( value: entry[ "name" ], default: "check" ),
-					state: state.upcase,
-					link: entry[ "html_url" ].to_s
+						workflow: blank_to( value: entry.dig( "app", "name" ), default: "workflow" ),
+						name: blank_to( value: entry[ "name" ], default: "check" ),
+						state: state.upcase,
+						link: entry[ "html_url" ].to_s
 					}
 				end
 			end
@@ -487,8 +487,8 @@ module Carson
 				markdown_path, json_path = write_pr_monitor_report( report: report )
 				puts_verbose "report_markdown: #{markdown_path}"
 				puts_verbose "report_json: #{json_path}"
-			rescue StandardError => e
-				puts_verbose "report_write: SKIP (#{e.message})"
+			rescue StandardError => exception
+				puts_verbose "report_write: SKIP (#{exception.message})"
 			end
 
 			# Persists report in both machine-readable JSON and human-readable Markdown.

data/lib/carson/runtime/deliver.rb

@@ -90,7 +90,7 @@ module Carson
 				result[ :exit_code ] = exit_code
 
 				if json_output
-					out.puts JSON.pretty_generate( result )
+					output.puts JSON.pretty_generate( result )
 				else
 					print_deliver_human( result: result )
 				end
@@ -136,8 +136,11 @@ module Carson
 			end
 
 			# Pushes the branch to the remote with tracking.
+			# Sets CARSON_PUSH=1 so the pre-push hook knows this is a Carson-managed push.
 			def push_branch!( branch:, remote:, result: )
-				_, push_stderr, push_success, = git_run( "push", "-u", remote, branch )
+				_, push_stderr, push_success, = with_env_var( "CARSON_PUSH", "1" ) do
+					git_run( "push", "-u", remote, branch )
+				end
 				unless push_success
 					error_text = push_stderr.to_s.strip
 					error_text = "push failed" if error_text.empty?
@@ -210,27 +213,27 @@ module Carson
 
 			# Generates a default PR title from the branch name.
 			def default_pr_title( branch: )
-				branch.tr( "-", " " ).gsub( "/", ": " ).sub( /\A\w/ ) { |c| c.upcase }
+				branch.tr( "-", " " ).gsub( "/", ": " ).sub( /\A\w/ ) { it.upcase }
 			end
 
 			# Checks CI status on a PR. Returns :pass, :fail, :pending, or :none.
-# Uses the `bucket` field (pass/fail/pending) from `gh pr checks --json`.
-def check_pr_ci( number: )
-	stdout, _, success, = gh_run(
-		"pr", "checks", number.to_s,
-		"--json", "name,bucket"
-	)
-	return :none unless success
-
-	checks = JSON.parse( stdout ) rescue []
-	return :none if checks.empty?
-
-	buckets = checks.map { |c| c[ "bucket" ].to_s.downcase }
-	return :fail if buckets.include?( "fail" )
-	return :pending if buckets.include?( "pending" )
-
-	:pass
-end
+			# Uses the `bucket` field (pass/fail/pending) from `gh pr checks --json`.
+			def check_pr_ci( number: )
+				stdout, _, success, = gh_run(
+					"pr", "checks", number.to_s,
+					"--json", "name,bucket"
+				)
+				return :none unless success
+
+				checks = JSON.parse( stdout ) rescue []
+				return :none if checks.empty?
+
+				buckets = checks.map { it[ "bucket" ].to_s.downcase }
+				return :fail if buckets.include?( "fail" )
+				return :pending if buckets.include?( "pending" )
+
+				:pass
+			end
 
 			# Checks review decision on a PR. Returns :approved, :changes_requested, :review_required, or :none.
 			def check_pr_review( number: )
@@ -253,7 +256,7 @@ end
 			# Merges the PR using the configured merge method.
 			# Deliberately omits --delete-branch: gh tries to switch the local
 			# checkout to main afterwards, which fails inside a worktree where
-			# main is already checked out. Branch cleanup deferred to `carson prune`.
+			# main is already checked output. Branch cleanup deferred to `carson prune`.
 			def merge_pr!( number:, result: )
 				method = config.govern_merge_method
 				result[ :merge_method ] = method
@@ -277,7 +280,7 @@ end
 			# Syncs main after a successful merge.
 			# Pulls into the main worktree directly — does not attempt checkout,
 			# because checkout would fail when running inside a feature worktree
-			# (main is already checked out in the main tree).
+			# (main is already checked output in the main tree).
 			def sync_after_merge!( remote:, main:, result: )
 				main_root = main_worktree_root
 				_, pull_stderr, pull_success, = Open3.capture3(
@@ -298,8 +301,8 @@ end
 			def compute_post_merge_next_step!( result: )
 				main_root = main_worktree_root
 				cwd = realpath_safe( Dir.pwd )
-				current_wt = worktree_list.select { |wt| wt.fetch( :path ) != realpath_safe( main_root ) }
-					.find { |wt| cwd == wt.fetch( :path ) || cwd.start_with?( File.join( wt.fetch( :path ), "" ) ) }
+				current_wt = worktree_list.select { it.fetch( :path ) != realpath_safe( main_root ) }
+					.find { cwd == it.fetch( :path ) || cwd.start_with?( File.join( it.fetch( :path ), "" ) ) }
 
 				if current_wt
 					wt_name = File.basename( current_wt.fetch( :path ) )

data/lib/carson/runtime/govern.rb

@@ -55,8 +55,8 @@ module Carson
 				end
 
 				EXIT_OK
-			rescue StandardError => e
-				puts_line "ERROR: govern failed — #{e.message}"
+			rescue StandardError => exception
+				puts_line "ERROR: govern failed — #{exception.message}"
 				EXIT_ERROR
 			end
 
@@ -69,8 +69,8 @@ module Carson
 					puts_line "── cycle #{cycle_count} at #{Time.now.utc.strftime( "%Y-%m-%d %H:%M:%S UTC" )} ──"
 					begin
 						govern_cycle!( dry_run: dry_run, json_output: json_output )
-					rescue StandardError => e
-						puts_line "ERROR: cycle #{cycle_count} failed — #{e.message}"
+					rescue StandardError => exception
+						puts_line "ERROR: cycle #{cycle_count} failed — #{exception.message}"
 					end
 					puts_line "sleeping #{loop_seconds}s until next cycle…"
 					sleep loop_seconds
@@ -145,8 +145,8 @@ module Carson
 					return nil
 				end
 				JSON.parse( stdout_text )
-			rescue JSON::ParserError => e
-				puts_line "gh pr list returned invalid JSON: #{e.message}"
+			rescue JSON::ParserError => exception
+				puts_line "gh pr list returned invalid JSON: #{exception.message}"
 				nil
 			end
 
@@ -208,10 +208,10 @@ module Carson
 				checks = Array( pr[ "statusCheckRollup" ] )
 				return :green if checks.empty?
 
-				has_failure = checks.any? { |c| check_state_failing?( state: c[ "state" ].to_s ) || check_conclusion_failing?( conclusion: c[ "conclusion" ].to_s ) }
+				has_failure = checks.any? { check_state_failing?( state: it[ "state" ].to_s ) || check_conclusion_failing?( conclusion: it[ "conclusion" ].to_s ) }
 				return :red if has_failure
 
-				has_pending = checks.any? { |c| check_state_pending?( state: c[ "state" ].to_s ) }
+				has_pending = checks.any? { check_state_pending?( state: it[ "state" ].to_s ) }
 				return :pending if has_pending
 
 				:green
@@ -345,13 +345,13 @@ module Carson
 
 			# Runs sync + prune in the given repo after a successful merge.
 			def housekeep_repo!( repo_path: )
-				rt = if repo_path == self.repo_root
+				scoped_runtime = if repo_path == self.repo_root
 					self
 				else
-					Runtime.new( repo_root: repo_path, tool_root: tool_root, out: out, err: err )
+					Runtime.new( repo_root: repo_path, tool_root: tool_root, output: output, error: error )
 				end
-				sync_status = rt.sync!
-				rt.prune! if sync_status == EXIT_OK
+				sync_status = scoped_runtime.sync!
+				scoped_runtime.prune! if sync_status == EXIT_OK
 			end
 
 			# Selects which agent provider to use based on config and availability.
@@ -410,18 +410,18 @@ module Carson
 
 			# Evidence gathering — builds structured context Hash for agent work orders.
 			def evidence( pr:, repo_path:, objective: )
-				ctx = { title: pr.fetch( "title", "" ) }
+				context = { title: pr.fetch( "title", "" ) }
 				case objective
 				when "fix_ci"
-					ctx.merge!( ci_evidence( pr: pr, repo_path: repo_path ) )
+					context.merge!( ci_evidence( pr: pr, repo_path: repo_path ) )
 				when "address_review"
-					ctx.merge!( review_evidence( pr: pr, repo_path: repo_path ) )
+					context.merge!( review_evidence( pr: pr, repo_path: repo_path ) )
 				end
 				prior = prior_attempt( pr: pr, repo_path: repo_path )
-				ctx[ :prior_attempt ] = prior if prior
-				ctx
-			rescue StandardError => e
-				puts_line "    evidence gathering failed: #{e.message}"
+				context[ :prior_attempt ] = prior if prior
+				context
+			rescue StandardError => exception
+				puts_line "    evidence gathering failed: #{exception.message}"
 				{ title: pr.fetch( "title", "" ) }
 			end
 
@@ -452,8 +452,8 @@ module Carson
 				return { ci_run_url: run_url } unless log_status.success?
 
 				{ ci_logs: truncate_log( text: log_stdout ), ci_run_url: run_url }
-			rescue StandardError => e
-				puts_line "    ci_evidence failed: #{e.message}"
+			rescue StandardError => exception
+				puts_line "    ci_evidence failed: #{exception.message}"
 				{}
 			end
 
@@ -464,13 +464,13 @@ module Carson
 			end
 
 			def review_evidence( pr:, repo_path: )
-				rt = scoped_runtime( repo_path: repo_path )
-				owner, repo = rt.send( :repository_coordinates )
+				scoped_runtime = scoped_runtime( repo_path: repo_path )
+				owner, repo = scoped_runtime.send( :repository_coordinates )
 				pr_number = pr[ "number" ]
-				details = rt.send( :pull_request_details, owner: owner, repo: repo, pr_number: pr_number )
+				details = scoped_runtime.send( :pull_request_details, owner: owner, repo: repo, pr_number: pr_number )
 				pr_author = details.dig( :author, :login ).to_s
-				threads = rt.send( :unresolved_thread_entries, details: details )
-				top_level = rt.send( :actionable_top_level_items, details: details, pr_author: pr_author )
+				threads = scoped_runtime.send( :unresolved_thread_entries, details: details )
+				top_level = scoped_runtime.send( :actionable_top_level_items, details: details, pr_author: pr_author )
 
 				findings = []
 				threads.each do |entry|
@@ -483,14 +483,14 @@ module Carson
 				end
 
 				{ review_findings: findings }
-			rescue StandardError => e
-				puts_line "    review_evidence failed: #{e.message}"
+			rescue StandardError => exception
+				puts_line "    review_evidence failed: #{exception.message}"
 				{}
 			end
 
 			def scoped_runtime( repo_path: )
 				return self if repo_path == self.repo_root
-				Runtime.new( repo_root: repo_path, tool_root: tool_root, out: out, err: err )
+				Runtime.new( repo_root: repo_path, tool_root: tool_root, output: output, error: error )
 			end
 
 			def prior_attempt( pr:, repo_path: )

data/lib/carson/runtime/housekeep.rb

@@ -64,9 +64,9 @@ module Carson
 				return unless gh_available?
 
 				main_root = main_worktree_root
-				worktree_list.each do |wt|
-					path = wt.fetch( :path )
-					branch = wt.fetch( :branch, nil )
+				worktree_list.each do |worktree|
+					path = worktree.fetch( :path )
+					branch = worktree.fetch( :branch, nil )
 					next if path == main_root
 					next unless branch
 					next if cwd_inside_worktree?( worktree_path: path )
@@ -121,26 +121,26 @@ module Carson
 					return { name: repo_name, path: repo_path, status: "error", error: "path not found" }
 				end
 
-				buf = verbose? ? out : StringIO.new
-				err_buf = verbose? ? err : StringIO.new
-				rt = Runtime.new( repo_root: repo_path, tool_root: tool_root, out: buf, err: err_buf, verbose: verbose? )
+				buffer = verbose? ? output : StringIO.new
+				error_buffer = verbose? ? error : StringIO.new
+				scoped_runtime = Runtime.new( repo_root: repo_path, tool_root: tool_root, output: buffer, error: error_buffer, verbose: verbose? )
 
-				sync_status = rt.sync!
+				sync_status = scoped_runtime.sync!
 				if sync_status == EXIT_OK
-					rt.reap_dead_worktrees!
-					prune_status = rt.prune!
+					scoped_runtime.reap_dead_worktrees!
+					prune_status = scoped_runtime.prune!
 				end
 
 				ok = sync_status == EXIT_OK && prune_status == EXIT_OK
 				unless verbose? || silent
-					summary = strip_badge( buf.string.lines.last.to_s.strip )
+					summary = strip_badge( buffer.string.lines.last.to_s.strip )
 					puts_line "#{repo_name}: #{summary.empty? ? 'OK' : summary}"
 				end
 
 				{ name: repo_name, path: repo_path, status: ok ? "ok" : "error" }
-			rescue StandardError => e
-				puts_line "#{repo_name}: FAIL (#{e.message})" unless silent
-				{ name: repo_name, path: repo_path, status: "error", error: e.message }
+			rescue StandardError => exception
+				puts_line "#{repo_name}: FAIL (#{exception.message})" unless silent
+				{ name: repo_name, path: repo_path, status: "error", error: exception.message }
 			end
 
 			# Strips the Carson badge prefix from a message to avoid double-badging.
@@ -156,7 +156,7 @@ module Carson
 				return expanded if repos.include?( expanded )
 
 				downcased = File.basename( target ).downcase
-				repos.find { |r| File.basename( r ).downcase == downcased }
+				repos.find { |repo_path| File.basename( repo_path ).downcase == downcased }
 			end
 
 			# Unified output — JSON or human-readable.
@@ -164,7 +164,7 @@ module Carson
 				result[ :exit_code ] = exit_code
 
 				if json_output
-					out.puts JSON.pretty_generate( result )
+					output.puts JSON.pretty_generate( result )
 				else
 					if results && ( succeeded || failed )
 						total = ( succeeded || 0 ) + ( failed || 0 )

data/lib/carson/runtime/local/hooks.rb

@@ -1,3 +1,4 @@
+# Installs, validates, and reports on managed git hooks for governed repositories.
 module Carson
 	class Runtime
 		module Local
@@ -30,11 +31,30 @@ module Carson
 				end
 				git_system!( "config", "core.hooksPath", hooks_dir )
 				File.write( File.join( hooks_dir, "workflow_style" ), config.workflow_style )
+				install_command_guard!
 				puts_verbose "configured_hooks_path: #{hooks_dir}"
 				puts_line "Hooks installed (#{config.managed_hooks.count} hooks)."
 				EXIT_OK
 			end
 
+			# Installs the command guard hook to a stable (non-versioned) path.
+			# Claude Code's PreToolUse hook references this path — it must not change across upgrades.
+			def install_command_guard!
+				source = hook_template_path( hook_name: "command-guard" )
+				return unless File.file?( source )
+
+				target = command_guard_path
+				FileUtils.mkdir_p( File.dirname( target ) )
+				FileUtils.cp( source, target )
+				FileUtils.chmod( 0o755, target )
+				puts_verbose "command_guard: #{target}"
+			end
+
+			# Stable path for the command guard script — not versioned so external references survive upgrades.
+			def command_guard_path
+				File.expand_path( File.join( config.hooks_path, "command-guard" ) )
+			end
+
 			# Canonical hook template location inside Carson repository.
 			def hook_template_path( hook_name: )
 				File.join( tool_root, "hooks", hook_name )