carson 3.20.0 → 3.21.0

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

@@ -1,3 +1,4 @@
+# Detects template drift, applies canonical files, and propagates changes via PR.
 module Carson
 	class Runtime
 		module Local
@@ -9,7 +10,7 @@ module Carson
 				".github/.mega-linter.yml"
 			].freeze
 
-			# Read-only template drift check; returns block when managed files are out of sync.
+			# Read-only template drift check; returns block when managed files are output of sync.
 			def template_check!
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
@@ -68,8 +69,8 @@ module Carson
 					end
 
 					begin
-						rt = build_scoped_runtime( repo_path: repo_path )
-						status = rt.template_check!
+						scoped_runtime = build_scoped_runtime( repo_path: repo_path )
+						status = scoped_runtime.template_check!
 						if status == EXIT_OK
 							puts_line "#{repo_name}: in sync" unless verbose?
 							clear_batch_success( command: "template_check", repo_path: repo_path )
@@ -78,9 +79,9 @@ module Carson
 							puts_line "#{repo_name}: DRIFT" unless verbose?
 							drifted += 1
 						end
-					rescue StandardError => e
-						puts_line "#{repo_name}: FAIL (#{e.message})"
-						record_batch_skip( command: "template_check", repo_path: repo_path, reason: e.message )
+					rescue StandardError => exception
+						puts_line "#{repo_name}: FAIL (#{exception.message})"
+						record_batch_skip( command: "template_check", repo_path: repo_path, reason: exception.message )
 						failed += 1
 					end
 				end
@@ -171,9 +172,9 @@ module Carson
 					result = template_propagate_deliver!( worktree_dir: worktree_dir )
 					template_propagate_report!( result: result )
 					result
-				rescue StandardError => e
-					puts_verbose "template_propagate: error (#{e.message})"
-					{ status: :error, reason: e.message }
+				rescue StandardError => exception
+					puts_verbose "template_propagate: error (#{exception.message})"
+					{ status: :error, reason: exception.message }
 				ensure
 					template_propagate_cleanup!( worktree_dir: worktree_dir ) if worktree_dir
 				end
@@ -181,12 +182,12 @@ module Carson
 
 			def template_propagate_create_worktree!
 				worktree_dir = File.join( Dir.tmpdir, "carson-template-sync-#{Process.pid}-#{Time.now.to_i}" )
-				wt_git = Adapters::Git.new( repo_root: worktree_dir )
+				worktree_git = Adapters::Git.new( repo_root: worktree_dir )
 
 				git_system!( "fetch", config.git_remote, config.main_branch )
 				git_system!( "worktree", "add", "--detach", worktree_dir, "#{config.git_remote}/#{config.main_branch}" )
-				wt_git.run( "checkout", "-B", TEMPLATE_SYNC_BRANCH )
-				wt_git.run( "config", "core.hooksPath", "/dev/null" )
+				worktree_git.run( "checkout", "-B", TEMPLATE_SYNC_BRANCH )
+				worktree_git.run( "config", "core.hooksPath", "/dev/null" )
 				puts_verbose "template_propagate: worktree created at #{worktree_dir}"
 				worktree_dir
 			end
@@ -211,13 +212,13 @@ module Carson
 			end
 
 			def template_propagate_commit!( worktree_dir: )
-				wt_git = Adapters::Git.new( repo_root: worktree_dir )
-				wt_git.run( "add", "--all" )
+				worktree_git = Adapters::Git.new( repo_root: worktree_dir )
+				worktree_git.run( "add", "--all" )
 
-				_, _, no_diff, = wt_git.run( "diff", "--cached", "--quiet" )
+				_, _, no_diff, = worktree_git.run( "diff", "--cached", "--quiet" )
 				return false if no_diff
 
-				wt_git.run( "commit", "-m", "chore: sync Carson #{Carson::VERSION} managed templates" )
+				worktree_git.run( "commit", "-m", "chore: sync Carson #{Carson::VERSION} managed templates" )
 				puts_verbose "template_propagate: committed"
 				true
 			end
@@ -231,8 +232,8 @@ module Carson
 			end
 
 			def template_propagate_deliver_trunk!( worktree_dir: )
-				wt_git = Adapters::Git.new( repo_root: worktree_dir )
-				stdout_text, stderr_text, success, = wt_git.run( "push", config.git_remote, "HEAD:refs/heads/#{config.main_branch}" )
+				worktree_git = Adapters::Git.new( repo_root: worktree_dir )
+				stdout_text, stderr_text, success, = worktree_git.run( "push", config.git_remote, "HEAD:refs/heads/#{config.main_branch}" )
 				unless success
 					error_text = stderr_text.to_s.strip
 					error_text = "push to #{config.main_branch} failed" if error_text.empty?
@@ -243,8 +244,8 @@ module Carson
 			end
 
 			def template_propagate_deliver_branch!( worktree_dir: )
-				wt_git = Adapters::Git.new( repo_root: worktree_dir )
-				stdout_text, stderr_text, success, = wt_git.run( "push", "--force-with-lease", config.git_remote, "#{TEMPLATE_SYNC_BRANCH}:#{TEMPLATE_SYNC_BRANCH}" )
+				worktree_git = Adapters::Git.new( repo_root: worktree_dir )
+				stdout_text, stderr_text, success, = worktree_git.run( "push", "--force-with-lease", config.git_remote, "#{TEMPLATE_SYNC_BRANCH}:#{TEMPLATE_SYNC_BRANCH}" )
 				unless success
 					error_text = stderr_text.to_s.strip
 					error_text = "push #{TEMPLATE_SYNC_BRANCH} failed" if error_text.empty?
@@ -296,8 +297,8 @@ module Carson
 				git_run( "worktree", "remove", "--force", worktree_dir ) unless safe_success
 				git_run( "branch", "-D", TEMPLATE_SYNC_BRANCH )
 				puts_verbose "template_propagate: worktree and local branch cleaned up"
-			rescue StandardError => e
-				puts_verbose "template_propagate: cleanup warning (#{e.message})"
+			rescue StandardError => exception
+				puts_verbose "template_propagate: cleanup warning (#{exception.message})"
 			end
 
 			def template_propagate_report!( result: )
@@ -381,14 +382,14 @@ module Carson
 			def managed_dirty_paths
 				template_paths = config.template_managed_files + SUPERSEDED
 				linters_glob   = Dir.glob( File.join( repo_root, ".github/linters/**/*" ) )
-					.select { |p| File.file?( p ) }
-					.map { |p| p.delete_prefix( "#{repo_root}/" ) }
+					.select { |path| File.file?( path ) }
+					.map { |path| path.delete_prefix( "#{repo_root}/" ) }
 				candidates = ( template_paths + linters_glob ).uniq
 				return [] if candidates.empty?
 
 				stdout_text, = git_capture_soft( "status", "--porcelain", "--", *candidates )
 				stdout_text.to_s.lines
-					.map { |l| l[ 3.. ].strip }
+					.map { |line| line[ 3.. ].strip }
 					.reject( &:empty? )
 			end
 		end

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

@@ -15,11 +15,11 @@ module Carson
 			# Uses main_worktree_root so this works even when called from inside a worktree.
 			def worktree_create!( name:, json_output: false )
 				worktrees_dir = File.join( main_worktree_root, ".claude", "worktrees" )
-				wt_path = File.join( worktrees_dir, name )
+				worktree_path = File.join( worktrees_dir, name )
 
-				if Dir.exist?( wt_path )
+				if Dir.exist?( worktree_path )
 					return worktree_finish(
-						result: { command: "worktree create", status: "error", name: name, path: wt_path,
+						result: { command: "worktree create", status: "error", name: name, path: worktree_path,
 							error: "worktree already exists: #{name}",
 							recovery: "carson worktree remove #{name}, then retry" },
 						exit_code: EXIT_ERROR, json_output: json_output
@@ -42,9 +42,9 @@ module Carson
 
 				# Create the worktree with a new branch based on the main branch.
 				FileUtils.mkdir_p( worktrees_dir )
-				_, wt_stderr, wt_success, = git_run( "worktree", "add", wt_path, "-b", name, base )
-				unless wt_success
-					error_text = wt_stderr.to_s.strip
+				_, worktree_stderr, worktree_success, = git_run( "worktree", "add", worktree_path, "-b", name, base )
+				unless worktree_success
+					error_text = worktree_stderr.to_s.strip
 					error_text = "unable to create worktree" if error_text.empty?
 					return worktree_finish(
 						result: { command: "worktree create", status: "error", name: name,
@@ -54,7 +54,7 @@ module Carson
 				end
 
 				worktree_finish(
-					result: { command: "worktree create", status: "ok", name: name, path: wt_path, branch: name },
+					result: { command: "worktree create", status: "ok", name: name, path: worktree_path, branch: name },
 					exit_code: EXIT_OK, json_output: json_output
 				)
 			end
@@ -66,7 +66,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: "worktree remove", status: "block",
 							error: "Carson-owned artefacts detected in host repository",
 							recovery: "remove Carson-owned files (.carson.yml, bin/carson, .tools/carson) then retry",
@@ -202,9 +202,9 @@ module Carson
 				end
 				return if agent_prefixes.empty?
 
-				worktrees.each do |wt|
-					path = wt.fetch( :path )
-					branch = wt.fetch( :branch, nil )
+				worktrees.each do |worktree|
+					path = worktree.fetch( :path )
+					branch = worktree.fetch( :branch, nil )
 					next unless branch
 					next unless agent_prefixes.any? { |prefix| path.start_with?( prefix ) }
 					next if cwd_inside_worktree?( worktree_path: path )
@@ -270,7 +270,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_worktree_human( result: result )
 				end
@@ -310,9 +310,9 @@ module Carson
 			# Uses realpath on both sides to handle symlink differences (e.g. /tmp vs /private/tmp).
 			def cwd_inside_worktree?( worktree_path: )
 				cwd = realpath_safe( Dir.pwd )
-				wt = realpath_safe( worktree_path )
-				normalised_wt = File.join( wt, "" )
-				cwd == wt || cwd.start_with?( normalised_wt )
+				worktree = realpath_safe( worktree_path )
+				normalised_wt = File.join( worktree, "" )
+				cwd == worktree || cwd.start_with?( normalised_wt )
 			rescue StandardError
 				false
 			end
@@ -378,7 +378,7 @@ module Carson
 				nil
 			end
 
-			# Returns the branch checked out in the worktree that contains the process CWD,
+			# Returns the branch checked output in the worktree that contains the process CWD,
 			# or nil if CWD is not inside any worktree. Used by prune to proactively
 			# protect the CWD worktree's branch from deletion.
 			# Matches the longest (most specific) path because worktree directories
@@ -387,12 +387,12 @@ module Carson
 				cwd = realpath_safe( Dir.pwd )
 				best_branch = nil
 				best_length = -1
-				worktree_list.each do |wt|
-					wt_path = wt.fetch( :path )
-					normalised = File.join( wt_path, "" )
-					if ( cwd == wt_path || cwd.start_with?( normalised ) ) && wt_path.length > best_length
-						best_branch = wt.fetch( :branch, nil )
-						best_length = wt_path.length
+				worktree_list.each do |worktree|
+					worktree_path = worktree.fetch( :path )
+					normalised = File.join( worktree_path, "" )
+					if ( cwd == worktree_path || cwd.start_with?( normalised ) ) && worktree_path.length > best_length
+						best_branch = worktree.fetch( :branch, nil )
+						best_length = worktree_path.length
 					end
 				end
 				best_branch
@@ -426,7 +426,7 @@ module Carson
 				existing = File.exist?( exclude_path ) ? File.read( exclude_path ) : ""
 				return if existing.lines.any? { |line| line.strip == ".claude/" }
 
-				File.open( exclude_path, "a" ) { |f| f.puts ".claude/" }
+				File.open( exclude_path, "a" ) { |file| file.puts ".claude/" }
 			rescue StandardError
 				# Best-effort — do not block worktree creation if exclude fails.
 			end
@@ -451,14 +451,14 @@ module Carson
 			# Compares using realpath to handle symlink differences.
 			def worktree_registered?( path: )
 				canonical = realpath_safe( path )
-				worktree_list.any? { |wt| wt.fetch( :path ) == canonical }
+				worktree_list.any? { |worktree| worktree.fetch( :path ) == canonical }
 			end
 
-			# Returns the branch name checked out in a worktree, or nil.
+			# Returns the branch name checked output in a worktree, or nil.
 			# Compares using realpath to handle symlink differences.
 			def worktree_branch( path: )
 				canonical = realpath_safe( path )
-				entry = worktree_list.find { |wt| wt.fetch( :path ) == canonical }
+				entry = worktree_list.find { |worktree| worktree.fetch( :path ) == canonical }
 				entry&.fetch( :branch, nil )
 			end
 

data/lib/carson/runtime/local.rb

@@ -1,3 +1,4 @@
+# Aggregates local repository operation modules (sync, prune, hooks, worktree, template).
 require_relative "local/sync"
 require_relative "local/prune"
 require_relative "local/template"

data/lib/carson/runtime/repos.rb

@@ -9,7 +9,7 @@ module Carson
 				repos = config.govern_repos
 
 				if json_output
-					out.puts JSON.pretty_generate( { command: "repos", repos: repos } )
+					output.puts JSON.pretty_generate( { command: "repos", repos: repos } )
 				else
 					if repos.empty?
 						puts_line "No governed repositories."

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

@@ -176,8 +176,8 @@ module Carson
 					)
 					puts_verbose "review_gate_report_markdown: #{markdown_path}"
 					puts_verbose "review_gate_report_json: #{json_path}"
-				rescue StandardError => e
-					puts_verbose "review_gate_report_write: SKIP (#{e.message})"
+				rescue StandardError => exception
+					puts_verbose "review_gate_report_write: SKIP (#{exception.message})"
 				end
 
 				# Human-readable review gate report for merge-readiness evidence.

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

@@ -208,8 +208,8 @@ module Carson
 					)
 					puts_verbose "review_sweep_report_markdown: #{markdown_path}"
 					puts_verbose "review_sweep_report_json: #{json_path}"
-				rescue StandardError => e
-					puts_verbose "review_sweep_report_write: SKIP (#{e.message})"
+				rescue StandardError => exception
+					puts_verbose "review_sweep_report_write: SKIP (#{exception.message})"
 				end
 
 				# Human-readable scheduled sweep report.

data/lib/carson/runtime/review.rb

@@ -1,3 +1,4 @@
+# Implements the review gate (merge readiness) and sweep (late activity scan) workflows.
 require_relative "review/query_text"
 require_relative "review/data_access"
 require_relative "review/gate_support"
@@ -6,6 +7,7 @@ require_relative "review/utility"
 
 module Carson
 	class Runtime
+		# PR review gate and sweep workflow.
 		module Review
 			include QueryText
 			include DataAccess
@@ -123,11 +125,11 @@ module Carson
 				end
 				block_reasons.each { |reason| puts_line "BLOCK: #{reason}" }
 				EXIT_BLOCK
-			rescue JSON::ParserError => e
-				puts_line "ERROR: invalid gh JSON response (#{e.message})."
+			rescue JSON::ParserError => exception
+				puts_line "ERROR: invalid gh JSON response (#{exception.message})."
 				EXIT_ERROR
-			rescue StandardError => e
-				puts_line "ERROR: #{e.message}"
+			rescue StandardError => exception
+				puts_line "ERROR: #{exception.message}"
 				EXIT_ERROR
 			end
 
@@ -176,11 +178,11 @@ module Carson
 				end
 				puts_line "BLOCK: actionable late review activity detected."
 				EXIT_BLOCK
-			rescue JSON::ParserError => e
-				puts_line "ERROR: invalid gh JSON response (#{e.message})."
+			rescue JSON::ParserError => exception
+				puts_line "ERROR: invalid gh JSON response (#{exception.message})."
 				EXIT_ERROR
-			rescue StandardError => e
-				puts_line "ERROR: #{e.message}"
+			rescue StandardError => exception
+				puts_line "ERROR: #{exception.message}"
 				EXIT_ERROR
 			end
 		end

data/lib/carson/runtime/setup.rb

@@ -1,8 +1,10 @@
+# Handles first-time setup, onboard, offboard, refresh, and config persistence.
 require "set"
 require "uri"
 
 module Carson
 	class Runtime
+		# First-time setup, onboard, offboard, and refresh operations.
 		module Setup
 			WELL_KNOWN_REMOTES = %w[origin github upstream].freeze
 
@@ -173,8 +175,8 @@ module Carson
 				options.each_with_index do |option, index|
 					puts_line "  #{index + 1}) #{option.fetch( :label )}"
 				end
-				out.print "#{BADGE} Choice [#{default + 1}]: "
-				out.flush
+				output.print "#{BADGE} Choice [#{default + 1}]: "
+				output.flush
 				raw = self.in.gets
 				return options[ default ].fetch( :value ) if raw.nil?
 
@@ -190,8 +192,8 @@ module Carson
 			end
 
 			def prompt_custom_value( label: )
-				out.print "#{BADGE} #{label}: "
-				out.flush
+				output.print "#{BADGE} #{label}: "
+				output.flush
 				raw = self.in.gets
 				return nil if raw.nil?
 
@@ -383,8 +385,8 @@ module Carson
 			# Reusable Y/n prompt following existing prompt_choice conventions.
 			def prompt_yes_no( default: true )
 				hint = default ? "Y/n" : "y/N"
-				out.print "#{BADGE} [#{hint}]: "
-				out.flush
+				output.print "#{BADGE} [#{hint}]: "
+				output.flush
 				raw = self.in.gets
 				return default if raw.nil?
 

data/lib/carson/runtime/status.rb

@@ -9,7 +9,7 @@ module Carson
 				data = gather_status
 
 				if json_output
-					out.puts JSON.pretty_generate( data )
+					output.puts JSON.pretty_generate( data )
 				else
 					print_status( data: data )
 				end
@@ -35,14 +35,14 @@ module Carson
 							next
 						end
 						begin
-							rt = build_scoped_runtime( repo_path: repo_path )
-							data = rt.send( :gather_status )
+							scoped_runtime = build_scoped_runtime( repo_path: repo_path )
+							data = scoped_runtime.send( :gather_status )
 							results << { name: repo_name, status: "ok" }.merge( data )
-						rescue StandardError => e
-							results << { name: repo_name, status: "error", error: e.message }
+						rescue StandardError => exception
+							results << { name: repo_name, status: "error", error: exception.message }
 						end
 					end
-					out.puts JSON.pretty_generate( { command: "status", repos: results } )
+					output.puts JSON.pretty_generate( { command: "status", repos: results } )
 					return EXIT_OK
 				end
 
@@ -58,8 +58,8 @@ module Carson
 					end
 
 					begin
-						rt = build_scoped_runtime( repo_path: repo_path )
-						data = rt.send( :gather_status )
+						scoped_runtime = build_scoped_runtime( repo_path: repo_path )
+						data = scoped_runtime.send( :gather_status )
 						branch = data.fetch( :branch )
 						dirty = branch.fetch( :dirty ) ? " (dirty)" : ""
 						worktrees = data.fetch( :worktrees )
@@ -72,9 +72,9 @@ module Carson
 
 						# Show pending operations for this repo.
 						repo_pending = status_pending_for_repo( all_pending: all_pending, repo_path: repo_path )
-						repo_pending.each { |desc| puts_line "  pending: #{desc}" }
-					rescue StandardError => e
-						puts_line "#{repo_name}: FAIL (#{e.message})"
+						repo_pending.each { |description| puts_line "  pending: #{description}" }
+					rescue StandardError => exception
+						puts_line "#{repo_name}: FAIL (#{exception.message})"
 					end
 				end
 
@@ -159,14 +159,14 @@ module Carson
 			def gather_worktree_info
 				entries = worktree_list
 
-				# Filter out the main worktree (the repository root itself).
+				# Filter output the main worktree (the repository root itself).
 				# Use realpath for comparison — git returns canonical paths that may differ from repo_root.
 				canonical_root = realpath_safe( repo_root )
-				entries.reject { it.fetch( :path ) == canonical_root }.map do |wt|
+				entries.reject { it.fetch( :path ) == canonical_root }.map do |worktree|
 					{
-						path: wt.fetch( :path ),
-						name: File.basename( wt.fetch( :path ) ),
-						branch: wt.fetch( :branch, nil )
+						path: worktree.fetch( :path ),
+						name: File.basename( worktree.fetch( :path ) ),
+						branch: worktree.fetch( :branch, nil )
 					}
 				end
 			end
@@ -222,7 +222,7 @@ module Carson
 				stdout, _, success, = git_run( "branch", "-vv" )
 				return { count: 0 } unless success
 
-				gone_branches = stdout.lines.select { |l| l.include?( ": gone]" ) }
+				gone_branches = stdout.lines.select { |line| line.include?( ": gone]" ) }
 				{ count: gone_branches.size }
 			end
 
@@ -252,9 +252,9 @@ module Carson
 				if worktrees.any?
 					puts_line ""
 					puts_line "Worktrees:"
-					worktrees.each do |wt|
-						branch_label = wt.fetch( :branch ) || "(detached)"
-						puts_line "  #{wt.fetch( :name )}  #{branch_label}"
+					worktrees.each do |worktree|
+						branch_label = worktree.fetch( :branch ) || "(detached)"
+						puts_line "  #{worktree.fetch( :name )}  #{branch_label}"
 					end
 				end
 

data/lib/carson/runtime.rb

@@ -23,11 +23,11 @@ module Carson
 		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:, in_stream: $stdin, verbose: false )
+		def initialize( repo_root:, tool_root:, output:, error:, in_stream: $stdin, verbose: false )
 			@repo_root = repo_root
 			@tool_root = tool_root
-			@out = out
-			@err = err
+			@output = output
+			@error = error
 			@in = in_stream
 			@verbose = verbose
 			@config = Config.load( repo_root: repo_root )
@@ -40,7 +40,7 @@ module Carson
 
 	private
 
-		attr_reader :repo_root, :tool_root, :out, :err, :in, :config, :git_adapter, :github_adapter
+		attr_reader :repo_root, :tool_root, :output, :error, :in, :config, :git_adapter, :github_adapter
 
 		# Returns true when full diagnostic output is enabled via --verbose.
 		def verbose?
@@ -55,12 +55,12 @@ module Carson
 		# Runs a block with all output captured (suppressed from the user).
 		# Returns the block's return value; output is silently discarded.
 		def with_captured_output
-			saved_out, saved_err = @out, @err
-			@out = StringIO.new
-			@err = StringIO.new
+			saved_output, saved_error = @output, @error
+			@output = StringIO.new
+			@error = StringIO.new
 			yield
 		ensure
-			@out, @err = saved_out, saved_err
+			@output, @error = saved_output, saved_error
 		end
 
 		# Returns true when the repository has at least one commit (HEAD exists).
@@ -95,9 +95,9 @@ module Carson
 		# Prefixes non-empty lines with the Carson badge (⧓).
 		def puts_line( message )
 			if message.to_s.strip.empty?
-				out.puts ""
+				output.puts ""
 			else
-				out.puts "#{BADGE} #{message}"
+				output.puts "#{BADGE} #{message}"
 			end
 		end
 
@@ -160,6 +160,20 @@ module Carson
 			text.empty? ? default : text
 		end
 
+		# Temporarily sets an environment variable for the duration of the block.
+		# Restores the previous value (or deletes the key) when the block completes.
+		def with_env_var( key, value )
+			previous = ENV.key?( key ) ? ENV.fetch( key ) : nil
+			ENV[ key ] = value
+			yield
+		ensure
+			if previous.nil?
+				ENV.delete( key )
+			else
+				ENV[ key ] = previous
+			end
+		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( " | " )
@@ -182,8 +196,8 @@ module Carson
 		# 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?
+			output.print stdout_text unless stdout_text.empty?
+			error.print stderr_text unless stderr_text.empty?
 			raise "git #{args.join( ' ' )} failed" unless success
 		end
 
@@ -191,7 +205,7 @@ module Carson
 		def git_capture!( *args )
 			stdout_text, stderr_text, success, = git_run( *args )
 			unless success
-				err.print stderr_text unless stderr_text.empty?
+				error.print stderr_text unless stderr_text.empty?
 				raise "git #{args.join( ' ' )} failed"
 			end
 			stdout_text
@@ -234,9 +248,9 @@ module Carson
 		def save_batch_pending( data )
 			path = batch_pending_path
 			FileUtils.mkdir_p( File.dirname( path ) )
-			tmp = "#{path}.tmp"
-			File.write( tmp, JSON.pretty_generate( data ) )
-			File.rename( tmp, path )
+			temporary_path = "#{path}.tmp"
+			File.write( temporary_path, JSON.pretty_generate( data ) )
+			File.rename( temporary_path, path )
 		end
 
 		# Adds or updates an entry in the pending log, incrementing attempts.
@@ -293,10 +307,10 @@ module Carson
 			reasons = []
 
 			# Active worktrees beyond the main working tree.
-			rt = build_scoped_runtime( repo_path: repo_path )
-			worktrees = rt.send( :worktree_list )
-			main_root = rt.send( :realpath_safe, repo_path )
-			active = worktrees.reject { |wt| wt.fetch( :path ) == main_root }
+			scoped_runtime = build_scoped_runtime( repo_path: repo_path )
+			worktrees = scoped_runtime.send( :worktree_list )
+			main_root = scoped_runtime.send( :realpath_safe, repo_path )
+			active = worktrees.reject { |worktree| worktree.fetch( :path ) == main_root }
 			if active.any?
 				reasons << "#{active.count} active worktree#{active.count == 1 ? '' : 's'}"
 			end
@@ -308,15 +322,15 @@ module Carson
 			end
 
 			{ safe: reasons.empty?, reasons: reasons }
-		rescue StandardError => e
-			{ safe: false, reasons: [ e.message ] }
+		rescue StandardError => exception
+			{ safe: false, reasons: [ exception.message ] }
 		end
 
 		# Creates a scoped Runtime for a governed repo with captured output.
 		def build_scoped_runtime( repo_path: )
-			buf = verbose? ? out : StringIO.new
-			err_buf = verbose? ? err : StringIO.new
-			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
+			Runtime.new( repo_root: repo_path, tool_root: tool_root, output: buffer, error: error_buffer, verbose: verbose? )
 		end
 	end
 end

data/lib/carson/version.rb

@@ -1,3 +1,4 @@
+# Reads the VERSION file and exposes it as Carson::VERSION.
 module Carson
 	version_path = File.expand_path( "../../VERSION", __dir__ )
 	VERSION = File.file?( version_path ) ? File.read( version_path ).strip : "0.0.0"

data/lib/carson.rb

@@ -1,3 +1,4 @@
+# Loads all Carson modules and defines the top-level namespace.
 require_relative "carson/version"
 
 module Carson

data/templates/.github/carson.md

@@ -2,12 +2,14 @@
 
 This repository is governed by [Carson](https://github.com/wanghailei/carson), an autonomous governance runtime. Carson lives on the maintainer's workstation, not inside this repository.
 
-## What Carson Does Not Do
-
-Carson has no `commit`, `push`, or `pr` commands. Use `git` and `gh` for those. Carson audits and governs; you execute.
-
 ## Commands
 
+**Delivery:**
+```bash
+carson deliver         # push branch, create PR
+carson deliver --merge # push, create PR, merge if CI green and review clear
+```
+
 **Before committing:**
 ```bash
 carson audit           # full governance check — run before every commit
@@ -24,6 +26,7 @@ carson review gate     # block until actionable review findings are resolved
 ```bash
 carson sync            # fast-forward local main from remote
 carson prune           # remove stale branches (safer than git branch -d on squash repos)
+carson housekeep       # sync + prune + sweep stale worktrees
 ```
 
 ## Exit Codes