carson 3.20.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
@@ -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
@@ -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
@@ -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
@@ -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?
@@ -253,7 +256,7 @@ module Carson
 			# 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 @@ module Carson
 			# 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(

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
 
@@ -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 )

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

@@ -164,12 +164,12 @@ module Carson
 					end
 
 					begin
-						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? )
-						status = rt.prune!
+						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? )
+						status = scoped_runtime.prune!
 						unless verbose?
-							summary = buf.string.lines.last.to_s.strip
+							summary = buffer.string.lines.last.to_s.strip
 							puts_line "#{repo_name}: #{summary.empty? ? 'OK' : summary}"
 						end
 						if status == EXIT_ERROR
@@ -179,9 +179,9 @@ module Carson
 							clear_batch_success( command: "prune", repo_path: repo_path )
 							succeeded += 1
 						end
-					rescue StandardError => e
-						puts_line "#{repo_name}: FAIL (#{e.message})"
-						record_batch_skip( command: "prune", repo_path: repo_path, reason: e.message )
+					rescue StandardError => exception
+						puts_line "#{repo_name}: FAIL (#{exception.message})"
+						record_batch_skip( command: "prune", repo_path: repo_path, reason: exception.message )
 						failed += 1
 					end
 				end
@@ -294,7 +294,7 @@ module Carson
 			def onboard_run_audit!
 				audit_error = nil
 				audit_status = with_captured_output { audit! }
-			rescue StandardError => e
+			rescue StandardError => exception
 				audit_error = e
 				audit_status = EXIT_OK
 			ensure
@@ -339,17 +339,17 @@ module Carson
 			# Refreshes a single governed repository using a scoped Runtime.
 			def refresh_single_repo( repo_path:, repo_name: )
 				if verbose?
-					rt = Runtime.new( repo_root: repo_path, tool_root: tool_root, out: out, err: err, verbose: true )
+					scoped_runtime = Runtime.new( repo_root: repo_path, tool_root: tool_root, output: output, error: error, verbose: true )
 				else
-					rt = Runtime.new( repo_root: repo_path, tool_root: tool_root, out: StringIO.new, err: StringIO.new )
+					scoped_runtime = Runtime.new( repo_root: repo_path, tool_root: tool_root, output: StringIO.new, error: StringIO.new )
 				end
-				status = rt.refresh!
+				status = scoped_runtime.refresh!
 				label = refresh_status_label( status: status )
-				sync_suffix = refresh_sync_suffix( result: rt.template_sync_result )
+				sync_suffix = refresh_sync_suffix( result: scoped_runtime.template_sync_result )
 				puts_line "#{repo_name}: #{label}#{sync_suffix}"
 				status
-			rescue StandardError => e
-				puts_line "#{repo_name}: FAIL (#{e.message})"
+			rescue StandardError => exception
+				puts_line "#{repo_name}: FAIL (#{exception.message})"
 				EXIT_ERROR
 			end
 
@@ -376,8 +376,8 @@ module Carson
 				git_system!( "config", "--unset", "core.hooksPath" )
 				puts_verbose "hooks_path_unset: core.hooksPath"
 				EXIT_OK
-			rescue StandardError => e
-				puts_line "ERROR: unable to update core.hooksPath (#{e.message})"
+			rescue StandardError => exception
+				puts_line "ERROR: unable to update core.hooksPath (#{exception.message})"
 				EXIT_ERROR
 			end
 

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

@@ -8,7 +8,7 @@ module Carson
 				fingerprint_status = block_if_outsider_fingerprints!
 				unless fingerprint_status.nil?
 					if json_output
-						out.puts JSON.pretty_generate( {
+						output.puts JSON.pretty_generate( {
 							command: "prune", status: "block",
 							error: "Carson-owned artefacts detected in host repository",
 							recovery: "remove Carson-owned files (.carson.yml, bin/carson, .tools/carson) then retry",
@@ -51,7 +51,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_prune_human( counters: counters )
 				end
@@ -116,7 +116,7 @@ module Carson
 			end
 
 			def prune_skip_stale_branch( type:, branch:, upstream: )
-				reason = { protected: "protected branch", current: "current branch", cwd_worktree: "checked out in CWD worktree" }.fetch( type, type.to_s )
+				reason = { protected: "protected branch", current: "current branch", cwd_worktree: "checked output in CWD worktree" }.fetch( type, type.to_s )
 				status = { protected: "skip_protected_branch", current: "skip_current_branch", cwd_worktree: "skip_cwd_worktree_branch" }.fetch( type, "skip_#{type}" )
 				puts_verbose "#{status}: #{branch} (upstream=#{upstream})"
 				{ action: :skipped, branch: branch, upstream: upstream, type: "stale", reason: reason }
@@ -135,7 +135,7 @@ module Carson
 			end
 
 			def prune_safe_delete_success( branch:, upstream:, stdout_text: )
-				out.print stdout_text if verbose? && !stdout_text.empty?
+				output.print stdout_text if verbose? && !stdout_text.empty?
 				puts_verbose "deleted_local_branch: #{branch} (upstream=#{upstream})"
 				{ action: :deleted, branch: branch, upstream: upstream, type: "stale", reason: "upstream gone" }
 			end
@@ -154,7 +154,7 @@ module Carson
 			end
 
 			def prune_force_delete_success( branch:, upstream:, merged_pr:, force_stdout: )
-				out.print force_stdout if verbose? && !force_stdout.empty?
+				output.print force_stdout if verbose? && !force_stdout.empty?
 				puts_verbose "deleted_local_branch_force: #{branch} (upstream=#{upstream}) merged_pr=#{merged_pr.fetch( :url )}"
 				{ action: :deleted, branch: branch, upstream: upstream, type: "stale", reason: "force deleted with PR evidence" }
 			end
@@ -195,9 +195,9 @@ module Carson
 				error_text.to_s.downcase.include?( "used by worktree" )
 			end
 
-			# Returns the worktree path for a branch, or nil if not checked out in any worktree.
+			# Returns the worktree path for a branch, or nil if not checked output in any worktree.
 			def worktree_path_for_branch( branch: )
-				entry = worktree_list.find { |wt| wt.fetch( :branch, nil ) == branch }
+				entry = worktree_list.find { |worktree| worktree.fetch( :branch, nil ) == branch }
 				entry&.fetch( :path, nil )
 			end
 
@@ -307,7 +307,7 @@ module Carson
 					return { action: :skipped, branch: branch, upstream: upstream, type: "absorbed", reason: error_text }
 				end
 
-				out.print force_stdout if verbose? && !force_stdout.empty?
+				output.print force_stdout if verbose? && !force_stdout.empty?
 
 				remote_branch = upstream.sub( "#{config.git_remote}/", "" )
 				git_run( "push", config.git_remote, "--delete", remote_branch )
@@ -372,7 +372,7 @@ module Carson
 
 				force_stdout, force_stderr, force_success = force_delete_local_branch( branch: branch )
 				if force_success
-					out.print force_stdout if verbose? && !force_stdout.empty?
+					output.print force_stdout if verbose? && !force_stdout.empty?
 					puts_verbose "deleted_orphan_branch: #{branch} merged_pr=#{merged_pr.fetch( :url )}"
 					return { action: :deleted, branch: branch, upstream: "", type: "orphan", reason: "merged PR evidence found" }
 				end
@@ -486,10 +486,10 @@ module Carson
 				return [ nil, "no merged PR evidence for branch tip #{branch_tip_sha} into #{config.main_branch}" ] if latest.nil?
 
 				[ latest, nil ]
-			rescue JSON::ParserError => e
-				[ nil, "invalid gh JSON response (#{e.message})" ]
-			rescue StandardError => e
-				[ nil, e.message ]
+			rescue JSON::ParserError => exception
+				[ nil, "invalid gh JSON response (#{exception.message})" ]
+			rescue StandardError => exception
+				[ nil, exception.message ]
 			end
 		end
 	end

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

@@ -66,8 +66,8 @@ module Carson
 					end
 
 					begin
-						rt = build_scoped_runtime( repo_path: repo_path )
-						status = rt.sync!
+						scoped_runtime = build_scoped_runtime( repo_path: repo_path )
+						status = scoped_runtime.sync!
 						if status == EXIT_OK
 							puts_line "#{repo_name}: ok" unless verbose?
 							clear_batch_success( command: "sync", repo_path: repo_path )
@@ -77,9 +77,9 @@ module Carson
 							record_batch_skip( command: "sync", repo_path: repo_path, reason: "sync failed" )
 							failed += 1
 						end
-					rescue StandardError => e
-						puts_line "#{repo_name}: FAIL (#{e.message})"
-						record_batch_skip( command: "sync", repo_path: repo_path, reason: e.message )
+					rescue StandardError => exception
+						puts_line "#{repo_name}: FAIL (#{exception.message})"
+						record_batch_skip( command: "sync", repo_path: repo_path, reason: exception.message )
 						failed += 1
 					end
 				end
@@ -106,7 +106,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_sync_human( result: result )
 				end