carson 3.19.0 → 3.21.0

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

@@ -1,3 +1,4 @@
+# GraphQL query templates for pull request review data retrieval.
 module Carson
 	class Runtime
 		module Review

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

@@ -1,3 +1,4 @@
+# Review sweep: late-event detection, tracking issue management, and sweep reporting.
 module Carson
 	class Runtime
 		module Review
@@ -59,7 +60,7 @@ module Carson
 						)
 					end
 
-					Array( details.fetch( :review_threads ) ).flat_map { |thread| thread.fetch( :comments ) }.each do |comment|
+					Array( details.fetch( :review_threads ) ).flat_map { it.fetch( :comments ) }.each do |comment|
 						next if comment.fetch( :author ) == pr_author
 						next if bot_username?( author: comment.fetch( :author ) )
 						hits = matched_risk_keywords( text: comment.fetch( :body ) )
@@ -152,7 +153,7 @@ module Carson
 					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 }
+					node = issues.find { it[ "title" ].to_s == config.review_tracking_issue_title }
 					return nil if node.nil?
 					{
 						number: node[ "number" ],
@@ -207,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/utility.rb

@@ -1,3 +1,4 @@
+# Review utilities: risk keyword matching, disposition parsing, URL extraction, and deduplication.
 module Carson
 	class Runtime
 		module Review
@@ -24,7 +25,7 @@ module Carson
 
 				# 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
+					text.to_s.scan( %r{https://github\.com/[^\s\)\]]+} ).map { it.sub( /[.,;:]+$/, "" ) }.uniq
 				end
 
 				# Parse RFC3339 timestamps and return nil on blank/invalid values.

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
 
@@ -137,7 +139,7 @@ module Carson
 					{ label: "branch — enforce PR-only merges (default)", value: "branch" },
 					{ label: "trunk — commit directly to main", value: "trunk" }
 				]
-				default_index = options.index { |o| o.fetch( :value ) == current } || 0
+				default_index = options.index { it.fetch( :value ) == current } || 0
 				prompt_choice( options: options, default: default_index )
 			end
 
@@ -151,7 +153,7 @@ module Carson
 					{ label: "rebase — linear history, individual commits", value: "rebase" },
 					{ label: "merge — merge commits", value: "merge" }
 				]
-				default_index = options.index { |o| o.fetch( :value ) == current } || 0
+				default_index = options.index { it.fetch( :value ) == current } || 0
 				prompt_choice( options: options, default: default_index )
 			end
 
@@ -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?
 
@@ -219,7 +221,7 @@ module Carson
 						others << entry
 					end
 				end
-				well_known.sort_by { |e| WELL_KNOWN_REMOTES.index( e.fetch( :name ) ) || 999 } + others.sort_by { |e| e.fetch( :name ) }
+				well_known.sort_by { WELL_KNOWN_REMOTES.index( it.fetch( :name ) ) || 999 } + others.sort_by { it.fetch( :name ) }
 			end
 
 			# Normalises a remote URL so SSH and HTTPS variants of the same host/path compare equal.
@@ -295,7 +297,7 @@ module Carson
 
 			def detect_git_remote
 				remotes = list_git_remotes
-				remote_names = remotes.map { |entry| entry.fetch( :name ) }
+				remote_names = remotes.map { it.fetch( :name ) }
 				return nil if remote_names.empty?
 
 				return config.git_remote if remote_names.include?( config.git_remote )
@@ -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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 3.19.0
+  version: 3.21.0
 platform: ruby
 authors:
 - Hailei Wang
@@ -36,6 +36,7 @@ files:
 - VERSION
 - carson.gemspec
 - exe/carson
+- hooks/command-guard
 - hooks/pre-commit
 - hooks/pre-merge-commit
 - hooks/pre-push