carson 3.22.0 → 3.22.1

data/lib/carson/runtime/govern.rb

@@ -56,7 +56,7 @@ module Carson
 
 				EXIT_OK
 			rescue StandardError => exception
-				puts_line "ERROR: govern failed — #{exception.message}"
+				puts_line "Govern did not complete: #{exception.message}"
 				EXIT_ERROR
 			end
 
@@ -70,7 +70,7 @@ module Carson
 					begin
 						govern_cycle!( dry_run: dry_run, json_output: json_output )
 					rescue StandardError => exception
-						puts_line "ERROR: cycle #{cycle_count} failed — #{exception.message}"
+						puts_line "Cycle #{cycle_count} did not complete: #{exception.message}"
 					end
 					puts_line "sleeping #{loop_seconds}s until next cycle…"
 					sleep loop_seconds
@@ -88,7 +88,7 @@ module Carson
 				config.govern_repos.map do |path|
 					expanded = File.expand_path( path )
 					unless Dir.exist?( expanded )
-						puts_line "WARN: governed repo path does not exist: #{expanded}"
+						puts_line "Skipping #{expanded} — path not found"
 						next nil
 					end
 					expanded
@@ -107,14 +107,14 @@ module Carson
 
 				unless Dir.exist?( repo_path )
 					repo_report[ :error ] = "path does not exist"
-					puts_line "ERROR: #{repo_path} does not exist"
+					puts_line "#{repo_path}: path not found, skipping"
 					return repo_report
 				end
 
 				prs = list_open_prs( repo_path: repo_path )
 				if prs.nil?
 					repo_report[ :error ] = "failed to list open PRs"
-					puts_line "ERROR: failed to list open PRs for #{repo_path}"
+					puts_line "#{File.basename(repo_path)}: unable to list open PRs"
 					return repo_report
 				end
 
@@ -196,8 +196,12 @@ module Carson
 				if review_decision == "CHANGES_REQUESTED"
 					return [ TRIAGE_REVIEW_BLOCKED, "changes requested by reviewer" ]
 				end
+				if review_decision == "REVIEW_REQUIRED"
+					return [ TRIAGE_REVIEW_BLOCKED, "review required" ]
+				end
 
 				review_status, review_detail = check_review_gate_status( pr: pr, repo_path: repo_path )
+				return [ TRIAGE_NEEDS_ATTENTION, review_detail ] if review_status == :error
 				return [ TRIAGE_REVIEW_BLOCKED, review_detail ] unless review_status == :pass
 
 				[ TRIAGE_READY, "all gates pass" ]
@@ -231,17 +235,25 @@ module Carson
 
 			# Checks review gate status. Returns [:pass/:fail, detail].
 			def check_review_gate_status( pr:, repo_path: )
-				review_decision = pr[ "reviewDecision" ].to_s.upcase
-				case review_decision
-				when "APPROVED"
-					[ :pass, "approved" ]
-				when "CHANGES_REQUESTED"
-					[ :fail, "changes requested" ]
-				when "REVIEW_REQUIRED"
-					[ :fail, "review required" ]
-				else
-					[ :pass, "no review policy or approved" ]
-				end
+				repo_runtime = scoped_runtime( repo_path: repo_path )
+				owner, repo = repo_runtime.send( :repository_coordinates )
+				report = repo_runtime.send(
+					:review_gate_report_for_pr,
+					owner: owner,
+					repo: repo,
+					pr_number: pr.fetch( "number" ),
+					branch_name: pr.fetch( "headRefName" ).to_s,
+					pr_summary: {
+						number: pr.fetch( "number" ),
+						title: pr.fetch( "title" ).to_s,
+						url: pr.fetch( "url" ).to_s,
+						state: "OPEN"
+					}
+				)
+				result = repo_runtime.send( :review_gate_result, report: report )
+				[ result.fetch( :status ), result.fetch( :detail ) ]
+			rescue StandardError => exception
+				[ :error, "review gate check failed: #{exception.message}" ]
 			end
 
 			# Maps classification to action.
@@ -296,7 +308,7 @@ module Carson
 					housekeep_repo!( repo_path: repo_path )
 				else
 					error_text = stderr_text.to_s.strip
-					puts_line "    merge failed: #{error_text}"
+					puts_line "    merge did not succeed: #{error_text}"
 				end
 			end
 

data/lib/carson/runtime/housekeep.rb

@@ -10,29 +10,52 @@ module Carson
 	class Runtime
 		module Housekeep
 			# Serves the current repo: sync + prune.
-			def housekeep!( json_output: false )
+			def housekeep!( json_output: false, dry_run: false )
+				return housekeep_one_dry_run if dry_run
+
 				housekeep_one( repo_path: repo_root, json_output: json_output )
 			end
 
 			# Resolves a target name to a governed repo, then serves it.
-			def housekeep_target!( target:, json_output: false )
+			def housekeep_target!( target:, json_output: false, dry_run: false )
 				repo_path = resolve_governed_repo( target: target )
 				unless repo_path
 					result = { command: "housekeep", status: "error", error: "Not a governed repository: #{target}", recovery: "Run carson repos to see governed repositories." }
 					return housekeep_finish( result: result, exit_code: EXIT_ERROR, json_output: json_output )
 				end
 
+				if dry_run
+					scoped = Runtime.new( repo_root: repo_path, tool_root: tool_root, output: output, error: error, verbose: verbose? )
+					return scoped.housekeep_one_dry_run
+				end
+
 				housekeep_one( repo_path: repo_path, json_output: json_output )
 			end
 
 			# Knocks each governed repo's gate in turn.
-			def housekeep_all!( json_output: false )
+			def housekeep_all!( json_output: false, dry_run: false )
 				repos = config.govern_repos
 				if repos.empty?
 					result = { command: "housekeep", status: "error", error: "No governed repositories configured.", recovery: "Run carson onboard in each repo to register." }
 					return housekeep_finish( result: result, exit_code: EXIT_ERROR, json_output: json_output )
 				end
 
+				if dry_run
+					repos.each_with_index do |repo_path, idx|
+						puts_line "" if idx > 0
+						unless Dir.exist?( repo_path )
+							puts_line "#{File.basename( repo_path )}: SKIP (path not found)"
+							next
+						end
+						scoped = Runtime.new( repo_root: repo_path, tool_root: tool_root, output: output, error: error, verbose: verbose? )
+						scoped.housekeep_one_dry_run
+					end
+					total = repos.size
+					puts_line ""
+					puts_line "#{total} repo#{plural_suffix( count: total )} surveyed. Run without --dry-run to apply."
+					return EXIT_OK
+				end
+
 				results = []
 				repos.each do |repo_path|
 					entry = housekeep_one_entry( repo_path: repo_path, silent: json_output )
@@ -50,55 +73,166 @@ module Carson
 				housekeep_finish( result: result, exit_code: failed.zero? ? EXIT_OK : EXIT_ERROR, json_output: json_output, results: results, succeeded: succeeded, failed: failed )
 			end
 
-			# Removes dead worktrees — those whose content is on main or with merged PR evidence.
+			# Prints a dry-run plan for this repo without making any changes.
+			# Calls reap_dead_worktrees_plan and prune_plan on self (already scoped to the repo).
+			def housekeep_one_dry_run
+				repo_name = File.basename( repo_root )
+				worktree_plan = reap_dead_worktrees_plan
+				branch_plan = prune_plan( dry_run: true )
+				print_housekeep_dry_run( repo_name: repo_name, worktree_plan: worktree_plan, branch_plan: branch_plan )
+				EXIT_OK
+			end
+
+			# Returns a plan array describing what reap_dead_worktrees! would do for each
+			# non-main worktree, without executing any mutations.
+			# Each item: { name:, branch:, action: :reap|:skip, reason: }
+			def reap_dead_worktrees_plan
+				main_root = main_worktree_root
+				items = []
+
+				agent_prefixes = Worktree::AGENT_DIRS.filter_map do |dir|
+					full = File.join( main_root, dir, "worktrees" )
+					File.join( realpath_safe( full ), "" ) if Dir.exist?( full )
+				end
+
+				worktree_list.each do |worktree|
+					next if worktree.path == main_root
+					next unless worktree.branch
+
+					item = { name: File.basename( worktree.path ), branch: worktree.branch }
+
+					if worktree.holds_cwd?
+						items << item.merge( action: :skip, reason: "held by current shell" )
+						next
+					end
+
+					if worktree.held_by_other_process?
+						items << item.merge( action: :skip, reason: "held by another process" )
+						next
+					end
+
+					# Missing directory — would be reaped by worktree prune + branch delete.
+					unless Dir.exist?( worktree.path )
+						items << item.merge( action: :reap, reason: "directory missing (destroyed externally)" )
+						next
+					end
+
+					# Layer 1: agent-owned + content absorbed into main (no gh needed).
+					if agent_prefixes.any? { |prefix| worktree.path.start_with?( prefix ) } &&
+							branch_absorbed_into_main?( branch: worktree.branch )
+						items << item.merge( action: :reap, reason: "content absorbed into main" )
+						next
+					end
+
+					# Layers 2 + 3: PR evidence — requires gh CLI.
+					unless gh_available?
+						items << item.merge( action: :skip, reason: "gh CLI not available for PR check" )
+						next
+					end
+
+					tip_sha = begin
+						git_capture!( "rev-parse", "--verify", worktree.branch ).strip
+					rescue StandardError
+						nil
+					end
+
+					unless tip_sha
+						items << item.merge( action: :skip, reason: "cannot read branch tip SHA" )
+						next
+					end
+
+					merged_pr, = merged_pr_for_branch( branch: worktree.branch, branch_tip_sha: tip_sha )
+					if merged_pr
+						items << item.merge( action: :reap, reason: "merged #{pr_short_ref( merged_pr[ :url ] )}" )
+						next
+					end
+
+					if branch_has_open_pr?( branch: worktree.branch )
+						items << item.merge( action: :skip, reason: "open PR exists" )
+						next
+					end
+
+					abandoned_pr, = abandoned_pr_for_branch( branch: worktree.branch, branch_tip_sha: tip_sha )
+					if abandoned_pr
+						items << item.merge( action: :reap, reason: "closed abandoned #{pr_short_ref( abandoned_pr[ :url ] )}" )
+						next
+					end
+
+					items << item.merge( action: :skip, reason: "no evidence to reap" )
+				end
+
+				items
+			end
+
+			# Removes dead worktrees — those whose content is on main, with merged PR evidence,
+			# or with closed-unmerged PR evidence and no open PR.
 			# Unblocks prune for the branches they hold.
-			# Two-layer dead check:
+			# Three-layer dead check:
 			#   1. Content-absorbed: delegates to sweep_stale_worktrees! (shared, no gh needed).
 			#   2. Merged PR evidence: covers rebase/squash where main has since evolved
 			#      the same files (requires gh).
+			#   3. Abandoned PR evidence: closed-but-unmerged PR on the exact branch tip,
+			#      but only when no open PR still exists for the branch.
 			def reap_dead_worktrees!
 				# Layer 1: sweep agent-owned worktrees whose content is on main.
 				sweep_stale_worktrees!
 
-				# Layer 2: merged PR evidence for remaining worktrees.
+				# Layers 2 and 3: PR evidence for remaining worktrees.
 				return unless gh_available?
 
 				main_root = main_worktree_root
 				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 )
+					next if worktree.path == main_root
+					next unless worktree.branch
+					next if worktree.holds_cwd?
+					next if worktree.held_by_other_process?
 
 					# Missing directory: worktree was destroyed externally.
 					# Prune the stale entry and delete the branch immediately.
-					unless Dir.exist?( path )
+					unless Dir.exist?( worktree.path )
 						git_run( "worktree", "prune" )
-						puts_verbose "reaped stale worktree entry: #{File.basename( path )} (branch: #{branch})"
-						if !config.protected_branches.include?( branch )
-							git_run( "branch", "-D", branch )
-							puts_verbose "deleted branch: #{branch}"
+						puts_verbose "reaped stale worktree entry: #{File.basename( worktree.path )} (branch: #{worktree.branch})"
+						if !config.protected_branches.include?( worktree.branch )
+							git_run( "branch", "-D", worktree.branch )
+							puts_verbose "deleted branch: #{worktree.branch}"
 						end
 						next
 					end
 
-					tip_sha = git_capture!( "rev-parse", "--verify", branch ).strip rescue nil
+					tip_sha = git_capture!( "rev-parse", "--verify", worktree.branch ).strip rescue nil
 					next unless tip_sha
 
-					merged_pr, = merged_pr_for_branch( branch: branch, branch_tip_sha: tip_sha )
-					next if merged_pr.nil?
+					merged_pr, = merged_pr_for_branch( branch: worktree.branch, branch_tip_sha: tip_sha )
+					if !merged_pr.nil?
+						# Remove the worktree (no --force: refuses if dirty working tree).
+						_, _, rm_success, = git_run( "worktree", "remove", worktree.path )
+						next unless rm_success
+
+						puts_verbose "reaped dead worktree: #{File.basename( worktree.path )} (branch: #{worktree.branch})"
+
+						# Delete the local branch now that no worktree holds it.
+						if !config.protected_branches.include?( worktree.branch )
+							git_run( "branch", "-D", worktree.branch )
+							puts_verbose "deleted branch: #{worktree.branch}"
+						end
+						next
+					end
+
+					next if branch_has_open_pr?( branch: worktree.branch )
+
+					abandoned_pr, = abandoned_pr_for_branch( branch: worktree.branch, branch_tip_sha: tip_sha )
+					next if abandoned_pr.nil?
 
 					# Remove the worktree (no --force: refuses if dirty working tree).
-					_, _, rm_success, = git_run( "worktree", "remove", path )
+					_, _, rm_success, = git_run( "worktree", "remove", worktree.path )
 					next unless rm_success
 
-					puts_verbose "reaped dead worktree: #{File.basename( path )} (branch: #{branch})"
+					puts_verbose "reaped abandoned worktree: #{File.basename( worktree.path )} (branch: #{worktree.branch}, closed PR: #{abandoned_pr.fetch( :url )})"
 
 					# Delete the local branch now that no worktree holds it.
-					if !config.protected_branches.include?( branch )
-						git_run( "branch", "-D", branch )
-						puts_verbose "deleted branch: #{branch}"
+					if !config.protected_branches.include?( worktree.branch )
+						git_run( "branch", "-D", worktree.branch )
+						puts_verbose "deleted branch: #{worktree.branch}"
 					end
 				end
 			end
@@ -139,7 +273,7 @@ module Carson
 
 				{ name: repo_name, path: repo_path, status: ok ? "ok" : "error" }
 			rescue StandardError => exception
-				puts_line "#{repo_name}: FAIL (#{exception.message})" unless silent
+				puts_line "#{repo_name}: did not complete (#{exception.message})" unless silent
 				{ name: repo_name, path: repo_path, status: "error", error: exception.message }
 			end
 
@@ -178,6 +312,78 @@ module Carson
 
 				exit_code
 			end
+
+			# Formats and prints the dry-run plan for one repo.
+			def print_housekeep_dry_run( repo_name:, worktree_plan:, branch_plan: )
+				stale    = branch_plan.fetch( :stale, [] )
+				orphan   = branch_plan.fetch( :orphan, [] )
+				absorbed = branch_plan.fetch( :absorbed, [] )
+
+				all_items = worktree_plan + stale + orphan + absorbed
+				would_apply = all_items.count { |i| i[ :action ] == :reap || i[ :action ] == :delete }
+				would_skip  = all_items.count { |i| i[ :action ] == :skip }
+
+				# Column widths for aligned output.
+				name_width = [ ( worktree_plan + stale + orphan + absorbed ).map { |i| i[ :name ].to_s.length + i[ :branch ].to_s.length }.max || 0, 28 ].min + 2
+				reason_width = 34
+
+				puts_line "Dry run — #{repo_name}"
+				note = gh_available? ? nil : " (gh CLI not available — PR evidence skipped)"
+				puts_line "  Note: branch staleness reflects last sync#{note}."
+				puts_line ""
+
+				puts_line "  Worktrees:"
+				if worktree_plan.empty?
+					puts_line "    none"
+				else
+					worktree_plan.each do |item|
+						label = "#{item[ :name ]} (#{item[ :branch ]})"
+						action_str = item[ :action ] == :reap ? "→ would reap" : "→ skip"
+						puts_line "    #{label.ljust( name_width )}  #{item[ :reason ].ljust( reason_width )}  #{action_str}"
+					end
+				end
+
+				puts_line ""
+				puts_line "  Stale branches (upstream gone):"
+				if stale.empty?
+					puts_line "    none"
+				else
+					stale.each { |item| print_branch_plan_item( item: item, name_width: name_width, reason_width: reason_width ) }
+				end
+
+				puts_line ""
+				puts_line "  Orphan branches (no upstream tracking):"
+				if orphan.empty?
+					puts_line "    none"
+				else
+					orphan.each { |item| print_branch_plan_item( item: item, name_width: name_width, reason_width: reason_width ) }
+				end
+
+				puts_line ""
+				puts_line "  Absorbed branches (content already on main):"
+				if absorbed.empty?
+					puts_line "    none"
+				else
+					absorbed.each { |item| print_branch_plan_item( item: item, name_width: name_width, reason_width: reason_width ) }
+				end
+
+				puts_line ""
+				puts_line "  #{would_apply} would be applied, #{would_skip} skipped."
+				puts_line "  Run without --dry-run to apply." if would_apply > 0
+			end
+
+			# Prints one branch plan item with aligned columns.
+			def print_branch_plan_item( item:, name_width:, reason_width: )
+				action_str = item[ :action ] == :delete ? "→ would delete" : "→ skip"
+				puts_line "    #{item[ :branch ].ljust( name_width )}  #{item[ :reason ].ljust( reason_width )}  #{action_str}"
+			end
+
+			# Extracts a short PR reference (e.g. "PR #123") from a GitHub URL.
+			def pr_short_ref( url )
+				return "PR" if url.nil? || url.empty?
+				m = url.match( /\/pull\/(\d+)$/ )
+				m ? "PR ##{m[1]}" : "PR"
+			end
 		end
 
 		include Housekeep

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

@@ -12,7 +12,7 @@ module Carson
 				return fingerprint_status unless fingerprint_status.nil?
 
 				unless inside_git_work_tree?
-					puts_line "ERROR: #{repo_root} is not a git repository."
+					puts_line "#{repo_root} is not a git repository."
 					return EXIT_ERROR
 				end
 
@@ -38,7 +38,7 @@ module Carson
 				return fingerprint_status unless fingerprint_status.nil?
 
 				unless inside_git_work_tree?
-					puts_line "ERROR: #{repo_root} is not a git repository."
+					puts_line "#{repo_root} is not a git repository."
 					return EXIT_ERROR
 				end
 
@@ -49,16 +49,17 @@ module Carson
 					return hook_status unless hook_status == EXIT_OK
 
 					drift_count = template_results.count { it.fetch( :status ) != "ok" }
+					stale_count = template_superseded_present.count
 					template_status = template_apply!
 					return template_status unless template_status == EXIT_OK
 
-					@template_sync_result = template_propagate!( drift_count: drift_count )
+					@template_sync_result = template_propagate!( drift_count: drift_count + stale_count )
 
 					audit_status = audit!
 					if audit_status == EXIT_OK
 						puts_line "OK: Carson refresh completed for #{repo_root}."
 					elsif audit_status == EXIT_BLOCK
-						puts_line "BLOCK: Carson refresh completed with policy blocks; resolve and rerun carson audit."
+						puts_line "Refresh complete — some checks need attention. Run carson audit for details."
 					end
 					return audit_status
 				end
@@ -69,15 +70,17 @@ module Carson
 				puts_line "Hooks installed (#{config.managed_hooks.count} hooks)."
 
 				template_drift_count = template_results.count { it.fetch( :status ) != "ok" }
+				stale_count = template_superseded_present.count
 				template_status = with_captured_output { template_apply! }
 				return template_status unless template_status == EXIT_OK
-				if template_drift_count.positive?
-					puts_line "Templates applied (#{template_drift_count} updated)."
+				total_drift = template_drift_count + stale_count
+				if total_drift.positive?
+					puts_line "Templates applied (#{template_drift_count} updated, #{stale_count} removed)."
 				else
 					puts_line "Templates in sync."
 				end
 
-				@template_sync_result = template_propagate!( drift_count: template_drift_count )
+				@template_sync_result = template_propagate!( drift_count: total_drift )
 
 				audit_status = audit!
 				puts_line "Refresh complete."
@@ -109,7 +112,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: "refresh", repo_path: repo_path, reason: "path not found" )
 						failed += 1
 						next
@@ -157,7 +160,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: "prune", repo_path: repo_path, reason: "path not found" )
 						failed += 1
 						next
@@ -180,7 +183,7 @@ module Carson
 							succeeded += 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: "prune", repo_path: repo_path, reason: exception.message )
 						failed += 1
 					end
@@ -196,7 +199,7 @@ module Carson
 				puts_verbose ""
 				puts_verbose "[Offboard]"
 				unless inside_git_work_tree?
-					puts_line "ERROR: #{repo_root} is not a git repository."
+					puts_line "#{repo_root} is not a git repository."
 					return EXIT_ERROR
 				end
 				if self.in.respond_to?( :tty? ) && self.in.tty?
@@ -266,15 +269,12 @@ module Carson
 				auto_register_govern!
 
 				puts_line ""
-				puts_line "Your repository is set up. Carson has placed files in your"
-				puts_line "project's .github/ directory — pull request templates,"
-				puts_line "guidelines for AI coding assistants, and any canonical"
-				puts_line "rules you've configured. Once pushed to GitHub, they'll"
-				puts_line "ensure every pull request follows a consistent standard"
-				puts_line "and all checks run automatically."
-				puts_line ""
-				puts_line "Before your first push, have a look through .github/ to"
-				puts_line "make sure everything is to your liking."
+				puts_line "Your repository is set up. If you have configured"
+				puts_line "lint.canonical, Carson has placed your canonical"
+				puts_line "policy files in the project's .github/ directory."
+				puts_line "Once pushed to GitHub, they'll ensure every pull"
+				puts_line "request follows a consistent standard and all"
+				puts_line "checks run automatically."
 				puts_line ""
 				puts_line "To adjust any setting: carson setup"
 
@@ -322,7 +322,7 @@ module Carson
 				if git_remote_exists?( remote_name: config.git_remote )
 					puts_verbose "remote_ok: #{config.git_remote}"
 				else
-					puts_line "WARN: remote '#{config.git_remote}' not found; run carson setup to configure."
+					puts_line "Remote '#{config.git_remote}' not found — run carson setup to configure."
 				end
 			end
 
@@ -349,7 +349,7 @@ module Carson
 				puts_line "#{repo_name}: #{label}#{sync_suffix}"
 				status
 			rescue StandardError => exception
-				puts_line "#{repo_name}: FAIL (#{exception.message})"
+				puts_line "#{repo_name}: could not complete (#{exception.message})"
 				EXIT_ERROR
 			end
 
@@ -357,7 +357,7 @@ module Carson
 				case status
 				when EXIT_OK then "OK"
 				when EXIT_BLOCK then "BLOCK"
-				else "FAIL"
+				else "incomplete"
 				end
 			end
 
@@ -377,7 +377,7 @@ module Carson
 				puts_verbose "hooks_path_unset: core.hooksPath"
 				EXIT_OK
 			rescue StandardError => exception
-				puts_line "ERROR: unable to update core.hooksPath (#{exception.message})"
+				puts_line "Could not update core.hooksPath: #{exception.message}"
 				EXIT_ERROR
 			end