carson 3.21.1 → 3.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e487779056ecbcf22d7aca1527c557051cd2ce94b31e030a515ffedcb8bbce5
-  data.tar.gz: 9cc271426a2c241d855f9a11d7b583e1bb0db2a8041e2972e8bdb3b7df4b55a7
+  metadata.gz: e75b6729cf0c977beb1ace5da390f41ae20d80208d7470c97b145b76e44cb3ad
+  data.tar.gz: 24d85c37e66498731b9d980b39017a4d73c06c93acd1dd8018e74b33e951d4df
 SHA512:
-  metadata.gz: 1e9085ad4e193f0b0c09b5ea890bbbc708194c0ccaf9b5dea96e4daafa5b074f08790ac994d44fbcee3767641eb519cc97d4b05ae65bc29532a2c695a752807c
-  data.tar.gz: 2bc2779bde9dabc17a79c2e0668f370a8f8aecd9ee41bbb56c51ebedf394d1546e029f611a7ffc2072e496a4d01ade6e390157ca4b4468bdf220a1ac4bb99393
+  metadata.gz: df4ff4c103415e7ff448ee5c8d7bbd60b4259afa15f522d840519b420e0202dc8cb7e86af7d27df0174c8df963eb57cf13fd578678e3c960b669f94e81089d6b
+  data.tar.gz: fcc758b8416931f303dbd72bcabac9f703b844c79b1dd37eec4572b43abe455bca81ca0f8f9871c09a2ee27f086f70c3e977b78b5c078d6820d8f8d770fb74c2

data/RELEASE.md

@@ -5,6 +5,21 @@ Release-note scope rule:
 - `RELEASE.md` records only version deltas, breaking changes, and migration actions.
 - Operational usage guides live in `MANUAL.md` and `API.md`.
 
+## 3.22.0
+
+### What changed
+
+- **Command-guard auto-install at CLI startup** — Carson now installs the command-guard hook automatically when any CLI command runs, removing the need for a manual `carson refresh` after install. The guard is installed once and skipped on subsequent invocations.
+- **Stale worktree sweep before portfolio safety check** — `refresh --all` now sweeps stale worktrees before checking repo safety, preventing false "active worktree" skips for worktrees whose branches have already been merged.
+- **Nested config path fix for merge method** — `govern.merge.method` is now read from the correct nested config path instead of the top-level key, fixing repos where the merge method setting was silently ignored.
+- **Deliver proceeds when no CI checks configured** — `deliver --merge` no longer blocks on repos with no CI checks. Previously it waited indefinitely for checks that would never arrive.
+- **Rebase-merge orphan branch pruning** — `prune` now detects branches absorbed into main via rebase merge (tip commit reachable from main) and cleans them up, not just squash-merged branches.
+- **Pluralisation fix** — corrected "branchs" → "branches" in prune and status output.
+
+### UX improvement
+
+- Carson is now fully self-configuring: installing the gem and running any command sets up all safety guards automatically. Batch operations on portfolios no longer false-skip repos with stale worktrees. Repos using rebase merge keep their branch list clean without manual intervention.
+
 ## 3.21.1
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-3.21.1
+3.22.0

data/lib/carson/cli.rb

@@ -4,6 +4,8 @@ require "optparse"
 module Carson
 	class CLI
 		def self.start( arguments:, repo_root:, tool_root:, output:, error: )
+			ensure_global_artefacts!( tool_root: tool_root )
+
 			parsed = parse_args( arguments: arguments, output: output, error: error )
 			command = parsed.fetch( :command )
 			return Runtime::EXIT_OK if command == :help
@@ -685,6 +687,27 @@ module Carson
 			{ command: :invalid }
 		end
 
+		# --- global artefacts ---
+
+		# Ensures global (non-repo) artefacts are installed at CLI startup.
+		# The command-guard lives at a stable path (~/.carson/hooks/command-guard)
+		# referenced by Claude Code's PreToolUse hook. It must exist regardless of
+		# whether `carson refresh` has been run in any governed repo.
+		def self.ensure_global_artefacts!( tool_root: )
+			source = File.join( tool_root, "hooks", "command-guard" )
+			return unless File.file?( source )
+
+			hooks_base = File.expand_path( "~/.carson/hooks" )
+			target = File.join( hooks_base, "command-guard" )
+			return if File.file?( target ) && FileUtils.identical?( source, target )
+
+			FileUtils.mkdir_p( hooks_base )
+			FileUtils.cp( source, target )
+			FileUtils.chmod( 0o755, target )
+		rescue StandardError
+			# Best-effort — do not block any command if this fails.
+		end
+
 		# --- dispatch ---
 
 		def self.dispatch( parsed:, runtime: )

data/lib/carson/config.rb

@@ -66,7 +66,9 @@ module Carson
 				"govern" => {
 					"repos" => [],
 					"auto_merge" => true,
-					"merge_method" => "squash",
+					"merge" => {
+						"method" => "squash"
+					},
 					"agent" => {
 						"provider" => "auto",
 						"codex" => {},
@@ -154,7 +156,10 @@ module Carson
 			govern_auto_merge = ENV.fetch( "CARSON_GOVERN_AUTO_MERGE", "" ).to_s.strip
 			govern[ "auto_merge" ] = ( govern_auto_merge == "true" ) unless govern_auto_merge.empty?
 			govern_method = ENV.fetch( "CARSON_GOVERN_MERGE_METHOD", "" ).to_s.strip
-			govern[ "merge_method" ] = govern_method unless govern_method.empty?
+			unless govern_method.empty?
+				govern[ "merge" ] ||= {}
+				govern[ "merge" ][ "method" ] = govern_method
+			end
 			agent = fetch_hash_section( data: govern, key: "agent" )
 			govern_provider = ENV.fetch( "CARSON_GOVERN_AGENT_PROVIDER", "" ).to_s.strip
 			agent[ "provider" ] = govern_provider unless govern_provider.empty?
@@ -215,7 +220,8 @@ module Carson
 			govern_hash = fetch_hash( hash: data, key: "govern" )
 			@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_merge_hash = fetch_hash( hash: govern_hash, key: "merge" )
+			@govern_merge_method = fetch_string( hash: govern_merge_hash, key: "method" ).downcase
 			govern_agent_hash = fetch_hash( hash: govern_hash, key: "agent" )
 			@govern_agent_provider = fetch_string( hash: govern_agent_hash, key: "provider" ).downcase
 			dispatch_path = govern_hash.fetch( "dispatch_state_path" ).to_s

data/lib/carson/runtime/audit.rb

@@ -115,12 +115,12 @@ module Carson
 					puts_verbose "[Canonical Templates]"
 					puts_verbose "HINT: canonical templates not configured — run carson setup to enable."
 				end
-					write_and_print_pr_monitor_report(
-						report: monitor_report.merge(
-							default_branch_baseline: default_branch_baseline,
-							audit_status: audit_state
-						)
+				write_and_print_pr_monitor_report(
+					report: monitor_report.merge(
+						default_branch_baseline: default_branch_baseline,
+						audit_status: audit_state
 					)
+				)
 				exit_code = audit_state == "block" ? EXIT_BLOCK : EXIT_OK
 
 				if json_output
@@ -581,7 +581,6 @@ module Carson
 				lines.join( "\n" )
 			end
 
-			# True when there are no staged/unstaged/untracked file changes.
 		end
 
 		include Audit

data/lib/carson/runtime/deliver.rb

@@ -1,7 +1,7 @@
 # PR delivery lifecycle — push, create PR, and optionally merge.
 # Collapses the 8-step manual PR flow into one or two commands.
 # `carson deliver` pushes and creates the PR.
-# `carson deliver --merge` also merges if CI is green.
+# `carson deliver --merge` also merges if CI passes or no checks are configured.
 # `carson deliver --json` outputs structured result for agent consumption.
 module Carson
 	class Runtime
@@ -46,17 +46,14 @@ module Carson
 				result[ :ci ] = ci_status.to_s
 
 				case ci_status
-				when :pass
-					# Continue to review gate.
+				when :pass, :none
+					# Continue to review gate. :none means no checks configured — nothing to wait for.
 				when :pending
 					result[ :recovery ] = "gh pr checks #{pr_number} --watch && carson deliver --merge"
 					return deliver_finish( result: result, exit_code: EXIT_OK, json_output: json_output )
 				when :fail
 					result[ :recovery ] = "gh pr checks #{pr_number} — fix failures, push, then `carson deliver --merge`"
 					return deliver_finish( result: result, exit_code: EXIT_BLOCK, json_output: json_output )
-				else
-					result[ :recovery ] = "gh pr checks #{pr_number}"
-					return deliver_finish( result: result, exit_code: EXIT_OK, json_output: json_output )
 				end
 
 				# Step 4: check review gate — block if changes are requested.
@@ -117,15 +114,14 @@ module Carson
 					case ci
 					when "pass"
 						puts_line "CI: pass"
+					when "none"
+						puts_line "CI: none — no checks configured, proceeding."
 					when "pending"
 						puts_line "CI: pending — merge when checks complete."
 						puts_line "  Recovery: #{result[ :recovery ]}" if result[ :recovery ]
 					when "fail"
 						puts_line "CI: failing — fix before merging."
 						puts_line "  Recovery: #{result[ :recovery ]}" if result[ :recovery ]
-					else
-						puts_line "CI: #{ci} — check manually."
-						puts_line "  Recovery: #{result[ :recovery ]}" if result[ :recovery ]
 					end
 				end
 

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

@@ -78,9 +78,9 @@ module Carson
 					message = if deleted_count > 0 && skipped_count > 0
 						"Pruned #{deleted_count}, skipped #{skipped_count} (--verbose for details)."
 					elsif deleted_count > 0
-						"Pruned #{deleted_count} stale branch#{plural_suffix( count: deleted_count )}."
+						"Pruned #{deleted_count} stale #{ deleted_count == 1 ? 'branch' : 'branches' }."
 					else
-						"Skipped #{skipped_count} branch#{plural_suffix( count: skipped_count )} (--verbose for details)."
+						"Skipped #{skipped_count} #{ skipped_count == 1 ? 'branch' : 'branches' } (--verbose for details)."
 					end
 					puts_line message
 				end
@@ -347,7 +347,7 @@ module Carson
 				counters
 			end
 
-			# Checks a single orphan branch for merged PR evidence and force-deletes if confirmed.
+			# Checks a single orphan branch for merged PR evidence or absorbed content, then force-deletes if confirmed.
 			def prune_orphan_branch_entry( branch: )
 				tip_sha_text, tip_sha_error, tip_sha_success, = git_run( "rev-parse", "--verify", branch.to_s )
 				unless tip_sha_success
@@ -363,6 +363,17 @@ module Carson
 				end
 
 				merged_pr, error = merged_pr_for_branch( branch: branch, branch_tip_sha: branch_tip_sha )
+
+				# Fallback: branch content is already on main (rebase merges rewrite SHAs).
+				if merged_pr.nil? && branch_absorbed_into_main?( branch: branch )
+					merged_pr = {
+						number: nil,
+						url: "absorbed into #{config.main_branch}",
+						merged_at: Time.now.utc.iso8601,
+						head_sha: branch_tip_sha
+					}
+				end
+
 				if merged_pr.nil?
 					reason = error.to_s.strip
 					reason = "no merged PR evidence for branch tip into #{config.main_branch}" if reason.empty?
@@ -374,7 +385,7 @@ module Carson
 				if force_success
 					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" }
+					return { action: :deleted, branch: branch, upstream: "", type: "orphan", reason: "content absorbed into #{config.main_branch}" }
 				end
 
 				force_error_text = normalise_branch_delete_error( error_text: force_stderr )

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

@@ -362,7 +362,7 @@ module Carson
 						# Content-aware check: after squash/rebase merge, commit SHAs differ
 						# but the tree content may be identical to main. Compare content,
 						# not SHAs — if the diff is empty, the work is already on main.
-						diff_out, _, diff_ok, = Open3.capture3( "git", "diff", "--quiet", config.main_branch, branch, chdir: worktree_path )
+						_, _, diff_ok, = Open3.capture3( "git", "diff", "--quiet", config.main_branch, branch, chdir: worktree_path )
 						unless diff_ok.success?
 							return { error: "branch has not been pushed to #{remote}",
 								recovery: "git -C #{worktree_path} push -u #{remote} #{branch}, or use --force to override" }

data/lib/carson/runtime/status.rb

@@ -276,7 +276,7 @@ module Carson
 				if stale && stale.fetch( :count ) > 0
 					count = stale.fetch( :count )
 					puts_line ""
-					puts_line "#{count} stale branch#{plural_suffix( count: count )} ready for pruning."
+					puts_line "#{count} stale #{ count == 1 ? 'branch' : 'branches' } ready for pruning."
 				end
 
 				# Governance

data/lib/carson/runtime.rb

@@ -306,8 +306,10 @@ module Carson
 
 			reasons = []
 
-			# Active worktrees beyond the main working tree.
+			# Sweep stale worktrees (merged branches) before counting active ones
+			# so only genuinely active worktrees block the operation.
 			scoped_runtime = build_scoped_runtime( repo_path: repo_path )
+			scoped_runtime.sweep_stale_worktrees!
 			worktrees = scoped_runtime.send( :worktree_list )
 			main_root = scoped_runtime.send( :realpath_safe, repo_path )
 			active = worktrees.reject { |worktree| worktree.fetch( :path ) == main_root }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 3.21.1
+  version: 3.22.0
 platform: ruby
 authors:
 - Hailei Wang