carson 3.22.0 → 3.23.0

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

@@ -4,6 +4,68 @@
 module Carson
 	class Runtime
 		module Local
+			# Returns a plan hash describing what prune! would do, without executing any mutations.
+			# Does NOT fetch — branch staleness reflects whatever the last fetch left behind.
+			# Returns: { stale: [...], orphan: [...], absorbed: [...] }
+			# Each item: { branch:, action: :delete|:skip, reason:, type: }
+			def prune_plan( dry_run: true ) # rubocop:disable Lint/UnusedMethodArgument
+				active_branch = current_branch
+				cwd_branch = cwd_worktree_branch
+
+				stale = stale_local_branches.map do |entry|
+					branch   = entry.fetch( :branch )
+					upstream = entry.fetch( :upstream )
+					if config.protected_branches.include?( branch )
+						{ action: :skip, branch: branch, upstream: upstream, name: branch, type: "stale", reason: "protected branch" }
+					elsif branch == active_branch
+						{ action: :skip, branch: branch, upstream: upstream, name: branch, type: "stale", reason: "current branch" }
+					elsif cwd_branch && branch == cwd_branch
+						{ action: :skip, branch: branch, upstream: upstream, name: branch, type: "stale", reason: "checked out in CWD worktree" }
+					else
+						{ action: :delete, branch: branch, upstream: upstream, name: branch, type: "stale", reason: "upstream gone" }
+					end
+				end
+
+				orphan = orphan_local_branches( active_branch: active_branch, cwd_branch: cwd_branch ).map do |branch|
+					if gh_available?
+						tip_sha = begin
+							git_capture!( "rev-parse", "--verify", branch ).strip
+						rescue StandardError
+							nil
+						end
+
+						if tip_sha
+							merged_pr, = merged_pr_for_branch( branch: branch, branch_tip_sha: tip_sha )
+							if merged_pr.nil? && branch_absorbed_into_main?( branch: branch )
+								merged_pr = { url: "absorbed into #{config.main_branch}" }
+							end
+
+							if merged_pr
+								{ action: :delete, branch: branch, upstream: "", name: branch, type: "orphan", reason: "merged — #{merged_pr[ :url ]}" }
+							else
+								{ action: :skip, branch: branch, upstream: "", name: branch, type: "orphan", reason: "no merged PR evidence" }
+							end
+						else
+							{ action: :skip, branch: branch, upstream: "", name: branch, type: "orphan", reason: "cannot read branch tip SHA" }
+						end
+					else
+						{ action: :skip, branch: branch, upstream: "", name: branch, type: "orphan", reason: "gh CLI not available" }
+					end
+				end
+
+				absorbed = absorbed_local_branches( active_branch: active_branch, cwd_branch: cwd_branch ).map do |entry|
+					branch   = entry.fetch( :branch )
+					upstream = entry.fetch( :upstream )
+					if gh_available? && branch_has_open_pr?( branch: branch )
+						{ action: :skip, branch: branch, upstream: upstream, name: branch, type: "absorbed", reason: "open PR exists" }
+					else
+						{ action: :delete, branch: branch, upstream: upstream, name: branch, type: "absorbed", reason: "content already on main" }
+					end
+				end
+
+				{ stale: stale, orphan: orphan, absorbed: absorbed }
+			end
+
 			def prune!( json_output: false )
 				fingerprint_status = block_if_outsider_fingerprints!
 				unless fingerprint_status.nil?
@@ -197,8 +259,8 @@ module Carson
 
 			# 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 { |worktree| worktree.fetch( :branch, nil ) == branch }
-				entry&.fetch( :path, nil )
+				entry = worktree_list.find { |worktree| worktree.branch == branch }
+				entry&.path
 			end
 
 			# Detects local branches whose upstream tracking is marked [gone] after fetch --prune.
@@ -216,7 +278,7 @@ module Carson
 
 			# Detects local branches with no upstream tracking ref — candidates for orphan pruning.
 			def orphan_local_branches( active_branch:, cwd_branch: nil )
-				git_capture!( "for-each-ref", "--format=%(refname:short)\t%(upstream:short)", "refs/heads" ).lines.filter_map do |line|
+				git_capture!( "for-each-ref", "--format=%(refname:short)\t%(upstream:short)", "refs/heads" ).lines.map do |line|
 					branch, upstream = line.strip.split( "\t", 2 )
 					branch = branch.to_s.strip
 					upstream = upstream.to_s.strip
@@ -228,14 +290,14 @@ module Carson
 					next if branch == TEMPLATE_SYNC_BRANCH
 
 					branch
-				end
+				end.compact
 			end
 
 			# Detects local branches whose upstream still exists but whose content is already on main.
 			# Two-step evidence: (1) find the merge-base, (2) verify every file the branch changed
 			# relative to the merge-base has identical content on main.
 			def absorbed_local_branches( active_branch:, cwd_branch: nil )
-				git_capture!( "for-each-ref", "--format=%(refname:short)\t%(upstream:short)\t%(upstream:track)", "refs/heads" ).lines.filter_map do |line|
+				git_capture!( "for-each-ref", "--format=%(refname:short)\t%(upstream:short)\t%(upstream:track)", "refs/heads" ).lines.map do |line|
 					branch, upstream, track = line.strip.split( "\t", 3 )
 					branch = branch.to_s.strip
 					upstream = upstream.to_s.strip
@@ -251,7 +313,7 @@ module Carson
 					next unless branch_absorbed_into_main?( branch: branch )
 
 					{ branch: branch, upstream: upstream }
-				end
+				end.compact
 			end
 
 			# Returns true when the branch has no unique content relative to main.
@@ -433,6 +495,32 @@ module Carson
 
 			# Finds merged PR evidence for the exact local branch tip.
 			def merged_pr_for_branch( branch:, branch_tip_sha: )
+				closed_prs, error = closed_prs_for_branch( branch: branch, branch_tip_sha: branch_tip_sha )
+				return [ nil, error ] unless error.nil?
+
+				latest = Array( closed_prs )
+					.select { |entry| !entry[ :merged_at ].nil? }
+					.max_by { |entry| entry.fetch( :merged_at ) }
+				return [ nil, "no merged PR evidence for branch tip #{branch_tip_sha} into #{config.main_branch}" ] if latest.nil?
+
+				[ latest, nil ]
+			end
+
+			# Finds closed-but-unmerged PR evidence for the exact local branch tip.
+			def abandoned_pr_for_branch( branch:, branch_tip_sha: )
+				closed_prs, error = closed_prs_for_branch( branch: branch, branch_tip_sha: branch_tip_sha )
+				return [ nil, error ] unless error.nil?
+
+				latest = Array( closed_prs )
+					.select { |entry| entry[ :merged_at ].nil? && !entry[ :closed_at ].nil? }
+					.max_by { |entry| entry.fetch( :closed_at ) }
+				return [ nil, "no abandoned PR evidence for branch tip #{branch_tip_sha} into #{config.main_branch}" ] if latest.nil?
+
+				[ latest, nil ]
+			end
+
+			# Queries all closed PRs for the branch tip, regardless of merge state.
+			def closed_prs_for_branch( branch:, branch_tip_sha: )
 				owner, repo = repository_coordinates
 				results = []
 				page = 1
@@ -450,7 +538,7 @@ module Carson
 						"-f", "page=#{page}"
 					)
 					unless success
-						error_text = gh_error_text( stdout_text: stdout_text, stderr_text: stderr_text, fallback: "unable to query merged PR evidence for branch #{branch}" )
+						error_text = gh_error_text( stdout_text: stdout_text, stderr_text: stderr_text, fallback: "unable to query closed PR evidence for branch #{branch}" )
 						return [ nil, error_text ]
 					end
 					page_nodes = Array( JSON.parse( stdout_text ) )
@@ -461,42 +549,39 @@ module Carson
 						next unless entry.dig( "base", "ref" ).to_s == config.main_branch
 						next unless entry.dig( "head", "sha" ).to_s == branch_tip_sha
 
-						merged_at = parse_time_or_nil( text: entry[ "merged_at" ] )
-						next if merged_at.nil?
-
 						results << {
 							number: entry[ "number" ],
 							url: entry[ "html_url" ].to_s,
-							merged_at: merged_at.utc.iso8601,
+							merged_at: parse_time_or_nil( text: entry[ "merged_at" ] )&.utc&.iso8601,
+							closed_at: parse_time_or_nil( text: entry[ "closed_at" ] )&.utc&.iso8601,
 							head_sha: entry.dig( "head", "sha" ).to_s
 						}
+					end
+
+					if page >= max_pages
+						probe_stdout_text, probe_stderr_text, probe_success, = gh_run(
+							"api", "repos/#{owner}/#{repo}/pulls",
+							"--method", "GET",
+							"-f", "state=closed",
+							"-f", "base=#{config.main_branch}",
+							"-f", "head=#{owner}:#{branch}",
+							"-f", "sort=updated",
+							"-f", "direction=desc",
+							"-f", "per_page=100",
+							"-f", "page=#{page + 1}"
+						)
+						unless probe_success
+							error_text = gh_error_text( stdout_text: probe_stdout_text, stderr_text: probe_stderr_text, fallback: "unable to verify closed PR pagination limit for branch #{branch}" )
+							return [ nil, error_text ]
 						end
-						if page >= max_pages
-							probe_stdout_text, probe_stderr_text, probe_success, = gh_run(
-								"api", "repos/#{owner}/#{repo}/pulls",
-								"--method", "GET",
-								"-f", "state=closed",
-								"-f", "base=#{config.main_branch}",
-								"-f", "head=#{owner}:#{branch}",
-								"-f", "sort=updated",
-								"-f", "direction=desc",
-								"-f", "per_page=100",
-								"-f", "page=#{page + 1}"
-							)
-							unless probe_success
-								error_text = gh_error_text( stdout_text: probe_stdout_text, stderr_text: probe_stderr_text, fallback: "unable to verify merged PR pagination limit for branch #{branch}" )
-								return [ nil, error_text ]
-							end
-							probe_nodes = Array( JSON.parse( probe_stdout_text ) )
-							return [ nil, "merged PR lookup exceeded pagination safety limit (#{max_pages} pages) for branch #{branch}" ] unless probe_nodes.empty?
-							break
-						end
-						page += 1
+						probe_nodes = Array( JSON.parse( probe_stdout_text ) )
+						return [ nil, "closed PR lookup exceeded pagination safety limit (#{max_pages} pages) for branch #{branch}" ] unless probe_nodes.empty?
+						break
 					end
-				latest = results.max_by { |item| item.fetch( :merged_at ) }
-				return [ nil, "no merged PR evidence for branch tip #{branch_tip_sha} into #{config.main_branch}" ] if latest.nil?
+					page += 1
+				end
 
-				[ latest, nil ]
+				[ results, nil ]
 			rescue JSON::ParserError => exception
 				[ nil, "invalid gh JSON response (#{exception.message})" ]
 			rescue StandardError => exception

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

@@ -9,7 +9,7 @@ module Carson
 
 				unless working_tree_clean?
 					return sync_finish(
-						result: { command: "sync", status: "block", error: "working tree is dirty", recovery: "git add -A && git commit, then carson sync" },
+						result: sync_dirty_result,
 						exit_code: EXIT_BLOCK, json_output: json_output
 					)
 				end
@@ -59,7 +59,7 @@ module Carson
 				repos.each do |repo_path|
 					repo_name = File.basename( repo_path )
 					unless Dir.exist?( repo_path )
-						puts_line "#{repo_name}: FAIL (path not found)"
+						puts_line "#{repo_name}: not found"
 						record_batch_skip( command: "sync", repo_path: repo_path, reason: "path not found" )
 						failed += 1
 						next
@@ -73,12 +73,12 @@ module Carson
 							clear_batch_success( command: "sync", repo_path: repo_path )
 							synced += 1
 						else
-							puts_line "#{repo_name}: FAIL" unless verbose?
+							puts_line "#{repo_name}: could not sync" unless verbose?
 							record_batch_skip( command: "sync", repo_path: repo_path, reason: "sync failed" )
 							failed += 1
 						end
 					rescue StandardError => exception
-						puts_line "#{repo_name}: FAIL (#{exception.message})"
+						puts_line "#{repo_name}: could not sync (#{exception.message})"
 						record_batch_skip( command: "sync", repo_path: repo_path, reason: exception.message )
 						failed += 1
 					end
@@ -117,8 +117,8 @@ module Carson
 			# Human-readable output for sync results.
 			def print_sync_human( result: )
 				if result[ :error ]
-					puts_line "BLOCK: #{result[ :error ]}."
-					puts_line "  Recovery: #{result[ :recovery ]}" if result[ :recovery ]
+					puts_line "#{result[ :error ]}."
+					puts_line "  → #{result[ :recovery ]}" if result[ :recovery ]
 					return
 				end
 
@@ -144,6 +144,28 @@ module Carson
 				git_capture!( "status", "--porcelain" ).strip.empty?
 			end
 
+			def sync_dirty_result
+				if main_worktree_context?
+					{
+						command: "sync",
+						status: "block",
+						error: "main working tree has uncommitted changes",
+						recovery: "create a worktree first: carson worktree create <name>; then move or discard the accidental main-tree changes before retrying carson sync"
+					}
+				else
+					{
+						command: "sync",
+						status: "block",
+						error: "working tree is dirty",
+						recovery: "git add -A && git commit, then carson sync"
+					}
+				end
+			end
+
+			def main_worktree_context?
+				realpath_safe( repo_root ) == realpath_safe( main_worktree_root )
+			end
+
 			def inside_git_work_tree?
 				stdout_text, = git_capture_soft( "rev-parse", "--is-inside-work-tree" )
 				stdout_text.to_s.strip == "true"
@@ -162,7 +184,7 @@ module Carson
 				violations = outsider_fingerprint_violations
 				return nil if violations.empty?
 
-				violations.each { |entry| puts_line "BLOCK: #{entry}" }
+				violations.each { |entry| puts_line entry }
 				EXIT_BLOCK
 			end
 

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

@@ -6,8 +6,17 @@ module Carson
 
 			SUPERSEDED = [
 				".github/carson-instructions.md",
+				".github/biome.json",
+				".github/erb-lint.yml",
+				".github/rubocop.yml",
+				".github/ruff.toml",
 				".github/workflows/carson-lint.yml",
-				".github/.mega-linter.yml"
+				".github/.mega-linter.yml",
+			".github/carson.md",
+			".github/copilot-instructions.md",
+			".github/CLAUDE.md",
+			".github/AGENTS.md",
+			".github/pull_request_template.md"
 			].freeze
 
 			# Read-only template drift check; returns block when managed files are output of sync.
@@ -19,8 +28,8 @@ module Carson
 				puts_verbose "[Template Sync Check]"
 				results = template_results
 				stale = template_superseded_present
-				drift_count = results.count { it.fetch( :status ) == "drift" }
-				error_count = results.count { it.fetch( :status ) == "error" }
+				drift_count = results.count { |entry| entry.fetch( :status ) == "drift" }
+				error_count = results.count { |entry| entry.fetch( :status ) == "error" }
 				stale_count = stale.count
 				results.each do |entry|
 					puts_verbose "template_file: #{entry.fetch( :file )} status=#{entry.fetch( :status )} reason=#{entry.fetch( :reason )}"
@@ -33,7 +42,7 @@ module Carson
 						summary_parts << "#{drift_count} of #{results.count} drifted" if drift_count.positive?
 						summary_parts << "#{stale_count} stale" if stale_count.positive?
 						puts_line "Templates: #{summary_parts.join( ", " )}"
-						results.select { it.fetch( :status ) == "drift" }.each { |entry| puts_line "  #{entry.fetch( :file )}" }
+						results.select { |entry| entry.fetch( :status ) == "drift" }.each { |entry| puts_line "  #{entry.fetch( :file )}" }
 						stale.each { |file| puts_line "  #{file} — superseded" }
 					else
 						puts_line "Templates: #{results.count} files in sync"
@@ -62,7 +71,7 @@ module Carson
 				repos.each do |repo_path|
 					repo_name = File.basename( repo_path )
 					unless Dir.exist?( repo_path )
-						puts_line "#{repo_name}: FAIL (path not found)"
+						puts_line "#{repo_name}: not found"
 						record_batch_skip( command: "template_check", repo_path: repo_path, reason: "path not found" )
 						failed += 1
 						next
@@ -80,7 +89,7 @@ module Carson
 							drifted += 1
 						end
 					rescue StandardError => exception
-						puts_line "#{repo_name}: FAIL (#{exception.message})"
+						puts_line "#{repo_name}: could not complete (#{exception.message})"
 						record_batch_skip( command: "template_check", repo_path: repo_path, reason: exception.message )
 						failed += 1
 					end
@@ -128,7 +137,7 @@ module Carson
 					removed += 1
 				end
 
-				error_count = results.count { it.fetch( :status ) == "error" }
+				error_count = results.count { |entry| entry.fetch( :status ) == "error" }
 				puts_verbose "template_apply_summary: updated=#{applied} removed=#{removed} error=#{error_count}"
 				unless verbose?
 					if applied.positive? || removed.positive?
@@ -312,7 +321,7 @@ module Carson
 
 			def template_superseded_present_in( root: )
 				SUPERSEDED.select do |file|
-					File.file?( File.join( root, file ) )
+					File.file?( File.join( root, file ) ) && !config.template_managed_files.include?( file )
 				end
 			end
 
@@ -323,7 +332,7 @@ module Carson
 			def template_superseded_present
 				SUPERSEDED.select do |file|
 					file_path = resolve_repo_path!( relative_path: file, label: "superseded file #{file}" )
-					File.file?( file_path )
+					File.file?( file_path ) && !config.template_managed_files.include?( file )
 				end
 			end
 
@@ -352,10 +361,19 @@ module Carson
 			def template_source_path( managed_file: )
 				relative_within_github = managed_file.delete_prefix( ".github/" )
 
-				canonical = config.template_canonical
+				canonical = config.lint_canonical
 				if canonical && !canonical.empty?
-					canonical_path = File.join( canonical, relative_within_github )
-					return canonical_path if File.file?( canonical_path )
+					canonical_candidates = [
+						File.join( canonical, relative_within_github ),
+						File.join( canonical, ".github", relative_within_github )
+					]
+					if relative_within_github.start_with?( "linters/" ) && relative_within_github.count( "/" ) == 1
+						canonical_candidates << File.join( canonical, relative_within_github.delete_prefix( "linters/" ) )
+					end
+
+					canonical_candidates.each do |canonical_path|
+						return canonical_path if File.file?( canonical_path )
+					end
 				end
 
 				template_path = File.join( github_templates_dir, relative_within_github )