carson 3.22.0 → 3.22.1

data/lib/carson/cli.rb

@@ -24,7 +24,7 @@ module Carson
 			target_repo_root = parsed.fetch( :repo_root, nil )
 			target_repo_root = repo_root if target_repo_root.to_s.strip.empty?
 			unless Dir.exist?( target_repo_root )
-				error.puts "#{BADGE} ERROR: repository path does not exist: #{target_repo_root}"
+				error.puts "#{BADGE} Repository path not found: #{target_repo_root}"
 				return Runtime::EXIT_ERROR
 			end
 
@@ -32,10 +32,10 @@ module Carson
 			runtime = Runtime.new( repo_root: target_repo_root, tool_root: tool_root, output: output, error: error, verbose: verbose )
 			dispatch( parsed: parsed, runtime: runtime )
 		rescue ConfigError => exception
-			error.puts "#{BADGE} CONFIG ERROR: #{exception.message}"
+			error.puts "#{BADGE} Configuration problem: #{exception.message}"
 			Runtime::EXIT_ERROR
 		rescue StandardError => exception
-			error.puts "#{BADGE} ERROR: #{exception.message}"
+			error.puts "#{BADGE} #{exception.message}"
 			Runtime::EXIT_ERROR
 		end
 
@@ -149,7 +149,7 @@ module Carson
 				parser.on( "--main-branch NAME", "Main branch name" ) { |value| options[ "git.main_branch" ] = value }
 				parser.on( "--workflow STYLE", "Workflow style (branch or trunk)" ) { |value| options[ "workflow.style" ] = value }
 				parser.on( "--merge METHOD", "Merge method (squash, rebase, or merge)" ) { |value| options[ "govern.merge.method" ] = value }
-				parser.on( "--canonical PATH", "Canonical template directory path" ) { |value| options[ "template.canonical" ] = value }
+				parser.on( "--canonical PATH", "Canonical lint policy directory path" ) { |value| options[ "lint.canonical" ] = value }
 				parser.separator ""
 				parser.separator "Examples:"
 				parser.separator "    carson setup                            Auto-detect and write config"
@@ -165,6 +165,7 @@ module Carson
 			{ command: "setup", cli_choices: options }
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts setup_parser
 			{ command: :invalid }
 		end
 
@@ -195,6 +196,7 @@ module Carson
 			}
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts onboard_parser
 			{ command: :invalid }
 		end
 
@@ -222,6 +224,7 @@ module Carson
 			}
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts offboard_parser
 			{ command: :invalid }
 		end
 
@@ -265,6 +268,7 @@ module Carson
 			}
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts refresh_parser
 			{ command: :invalid }
 		end
 
@@ -292,6 +296,7 @@ module Carson
 			{ command: "prune", json: options[ :json ] }
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts prune_parser
 			{ command: :invalid }
 		end
 
@@ -348,6 +353,7 @@ module Carson
 			end
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts worktree_parser
 			{ command: :invalid }
 		end
 
@@ -378,6 +384,7 @@ module Carson
 			{ command: "review:#{action}" }
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts review_parser
 			{ command: :invalid }
 		end
 
@@ -436,6 +443,7 @@ module Carson
 			{ command: "template:apply", push_prep: options.fetch( :push_prep ) }
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts( apply_parser || template_parser )
 			{ command: :invalid }
 		end
 
@@ -468,6 +476,7 @@ module Carson
 			{ command: "audit", json: options[ :json ] }
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts audit_parser
 			{ command: :invalid }
 		end
 
@@ -499,6 +508,7 @@ module Carson
 			{ command: "sync", json: options[ :json ] }
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts sync_parser
 			{ command: :invalid }
 		end
 
@@ -530,6 +540,7 @@ module Carson
 			{ command: "status", json: options[ :json ] }
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts status_parser
 			{ command: :invalid }
 		end
 
@@ -568,6 +579,7 @@ module Carson
 			}
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts deliver_parser
 			{ command: :invalid }
 		end
 
@@ -596,27 +608,30 @@ module Carson
 			{ command: "repos", json: options[ :json ] }
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts repos_parser
 			{ command: :invalid }
 		end
 
 		# --- housekeep ---
 
 		def self.parse_housekeep_command( arguments:, error: )
-			options = { all: false, json: false }
+			options = { all: false, json: false, dry_run: false }
 			housekeep_parser = OptionParser.new do |parser|
-				parser.banner = "Usage: carson housekeep [REPO] [--all] [--json]"
+				parser.banner = "Usage: carson housekeep [REPO] [--all] [--dry-run] [--json]"
 				parser.separator ""
 				parser.separator "Run housekeeping: sync main, reap dead worktrees, and prune stale branches."
 				parser.separator "Defaults to the current repository."
 				parser.separator ""
 				parser.separator "Options:"
 				parser.on( "--all", "Housekeep all governed repositories" ) { options[ :all ] = true }
+				parser.on( "--dry-run", "Show what would be reaped/deleted without making changes" ) { options[ :dry_run ] = true }
 				parser.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
 				parser.separator ""
 				parser.separator "Examples:"
-				parser.separator "    carson housekeep           Housekeep the current repository"
-				parser.separator "    carson housekeep nexus     Housekeep a named governed repo"
-				parser.separator "    carson housekeep --all     Housekeep all governed repos"
+				parser.separator "    carson housekeep              Housekeep the current repository"
+				parser.separator "    carson housekeep --dry-run    Preview what housekeep would do"
+				parser.separator "    carson housekeep nexus        Housekeep a named governed repo"
+				parser.separator "    carson housekeep --all        Housekeep all governed repos"
 			end
 			housekeep_parser.parse!( arguments )
 
@@ -625,7 +640,7 @@ module Carson
 				return { command: :invalid }
 			end
 
-			return { command: "housekeep:all", json: options[ :json ] } if options[ :all ]
+			return { command: "housekeep:all", json: options[ :json ], dry_run: options[ :dry_run ] } if options[ :all ]
 
 			if arguments.length > 1
 				error.puts "#{BADGE} Too many arguments for housekeep. Use: carson housekeep [repo]"
@@ -633,11 +648,12 @@ module Carson
 			end
 
 			target = arguments.shift
-			return { command: "housekeep:target", target: target, json: options[ :json ] } if target
+			return { command: "housekeep:target", target: target, json: options[ :json ], dry_run: options[ :dry_run ] } if target
 
-			{ command: "housekeep", json: options[ :json ] }
+			{ command: "housekeep", json: options[ :json ], dry_run: options[ :dry_run ] }
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts housekeep_parser
 			{ command: :invalid }
 		end
 
@@ -660,7 +676,7 @@ module Carson
 				parser.on( "--dry-run", "Run all checks but do not merge or dispatch" ) { options[ :dry_run ] = true }
 				parser.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
 				parser.on( "--loop SECONDS", Integer, "Run continuously, sleeping SECONDS between cycles" ) do |seconds|
-					error.puts( "#{BADGE} Error: --loop must be a positive integer" ) || ( return { command: :invalid } ) if seconds < 1
+					error.puts( "#{BADGE} --loop expects a positive integer" ) || ( return { command: :invalid } ) if seconds < 1
 					options[ :loop_seconds ] = seconds
 				end
 				parser.separator ""
@@ -757,11 +773,11 @@ module Carson
 			when "repos"
 				runtime.repos!( json_output: parsed.fetch( :json, false ) )
 			when "housekeep"
-				runtime.housekeep!( json_output: parsed.fetch( :json, false ) )
+				runtime.housekeep!( json_output: parsed.fetch( :json, false ), dry_run: parsed.fetch( :dry_run, false ) )
 			when "housekeep:target"
-				runtime.housekeep_target!( target: parsed.fetch( :target ), json_output: parsed.fetch( :json, false ) )
+				runtime.housekeep_target!( target: parsed.fetch( :target ), json_output: parsed.fetch( :json, false ), dry_run: parsed.fetch( :dry_run, false ) )
 			when "housekeep:all"
-				runtime.housekeep_all!( json_output: parsed.fetch( :json, false ) )
+				runtime.housekeep_all!( json_output: parsed.fetch( :json, false ), dry_run: parsed.fetch( :dry_run, false ) )
 			when "govern"
 				runtime.govern!(
 					dry_run: parsed.fetch( :dry_run, false ),

data/lib/carson/config.rb

@@ -7,9 +7,24 @@ module Carson
 
 	# Config is built-in only for outsider mode; host repositories do not carry Carson config files.
 	class Config
+		CANONICAL_GITHUB_DIRECTORIES = %w[actions workflows ISSUE_TEMPLATE DISCUSSION_TEMPLATE linters].freeze
+		CANONICAL_GITHUB_ROOT_FILES = [
+			".mega-linter.yml",
+			"AGENTS.md",
+			"CLAUDE.md",
+			"CODEOWNERS",
+			"FUNDING.yml",
+			"carson.md",
+			"copilot-instructions.md",
+			"dependabot.yml",
+			"funding.yml",
+			"labeler.yml",
+			"pull_request_template.md"
+		].freeze
+
 		attr_accessor :git_remote
 		attr_reader :main_branch, :protected_branches, :hooks_path, :managed_hooks,
-			:template_managed_files, :template_canonical,
+			:template_managed_files, :lint_canonical, :template_canonical,
 			:review_wait_seconds, :review_poll_seconds, :review_max_polls, :review_sweep_window_days,
 			:review_sweep_states, :review_disposition, :review_risk_keywords,
 			:review_tracking_issue_title, :review_tracking_issue_label, :review_bot_usernames,
@@ -38,7 +53,10 @@ module Carson
 					"managed" => [ "pre-commit", "prepare-commit-msg", "pre-merge-commit", "pre-push" ]
 				},
 				"template" => {
-					"managed_files" => [ ".github/carson.md", ".github/copilot-instructions.md", ".github/CLAUDE.md", ".github/AGENTS.md", ".github/pull_request_template.md" ],
+					"managed_files" => [],
+					"canonical" => nil
+				},
+				"lint" => {
 					"canonical" => nil
 				},
 				"workflow" => {
@@ -194,8 +212,11 @@ module Carson
 			@hooks_path = fetch_string( hash: fetch_hash( hash: data, key: "hooks" ), key: "path" )
 			@managed_hooks = fetch_string_array( hash: fetch_hash( hash: data, key: "hooks" ), key: "managed" )
 
-			@template_managed_files = fetch_string_array( hash: fetch_hash( hash: data, key: "template" ), key: "managed_files" )
-			@template_canonical = fetch_optional_path( hash: fetch_hash( hash: data, key: "template" ), key: "canonical" )
+			template_hash = fetch_hash( hash: data, key: "template" )
+			@template_managed_files = fetch_optional_string_array( hash: template_hash, key: "managed_files" )
+			@lint_canonical = fetch_optional_path( hash: fetch_hash( hash: data, key: "lint" ), key: "canonical" )
+			@lint_canonical ||= fetch_optional_path( hash: template_hash, key: "canonical" )
+			@template_canonical = @lint_canonical
 			resolve_canonical_files!
 
 			workflow_hash = fetch_hash( hash: data, key: "workflow" )
@@ -323,18 +344,32 @@ module Carson
 				safe_expand_path( text )
 			end
 
-			# Discovers files in the canonical directory and appends them to managed_files.
-			# Canonical files mirror the .github/ structure and are synced alongside Carson's own governance files.
+			# Discovers files in the canonical lint-policy directory and appends them to managed_files.
+			# Explicit GitHub paths stay under .github/; flat policy files default to .github/linters/.
 			def resolve_canonical_files!
-				return if @template_canonical.nil? || @template_canonical.empty?
-				return unless Dir.exist?( @template_canonical )
+				return if @lint_canonical.nil? || @lint_canonical.empty?
+				return unless Dir.exist?( @lint_canonical )
 
-				Dir.glob( File.join( @template_canonical, "**", "*" ) ).sort.each do |absolute_path|
+				Dir.glob( File.join( @lint_canonical, "**", "*" ), File::FNM_DOTMATCH ).sort.each do |absolute_path|
+					basename = File.basename( absolute_path )
+					next if basename == "." || basename == ".."
 					next unless File.file?( absolute_path )
-					relative = absolute_path.delete_prefix( "#{@template_canonical}/" )
-					managed_path = ".github/#{relative}"
+					relative = absolute_path.delete_prefix( "#{@lint_canonical}/" )
+					managed_path = canonical_managed_path( relative_path: relative )
 					@template_managed_files << managed_path unless @template_managed_files.include?( managed_path )
 				end
 			end
+
+			def canonical_managed_path( relative_path: )
+				raw_relative = relative_path.to_s
+				return ".github/#{raw_relative.delete_prefix( '.github/' )}" if raw_relative.start_with?( ".github/" )
+
+				clean_relative = raw_relative
+				first_segment = clean_relative.split( "/", 2 ).first
+				return ".github/#{clean_relative}" if CANONICAL_GITHUB_DIRECTORIES.include?( first_segment )
+				return ".github/#{clean_relative}" if !clean_relative.include?( "/" ) && CANONICAL_GITHUB_ROOT_FILES.include?( clean_relative )
+
+				".github/linters/#{clean_relative}"
+			end
 	end
 end

data/lib/carson/runtime/audit.rb

@@ -26,6 +26,12 @@ module Carson
 				puts_verbose ""
 				puts_verbose "[Working Tree]"
 				puts_verbose git_capture!( "status", "--short", "--branch" ).strip
+				working_tree = audit_working_tree_report
+				if working_tree.fetch( :status ) == "block"
+					puts_verbose "ACTION: #{working_tree.fetch( :error )}; #{working_tree.fetch( :recovery )}."
+					audit_state = "block"
+					audit_concise_problems << "Working tree: #{working_tree.fetch( :error )} — #{working_tree.fetch( :recovery )}."
+				end
 				puts_verbose ""
 				puts_verbose "[Hooks]"
 				hooks_ok = hooks_health_report
@@ -110,10 +116,10 @@ module Carson
 					end
 					audit_concise_problems << "Baseline (#{default_branch_baseline.fetch( :default_branch, config.main_branch )}): #{parts.join( ', ' )}."
 				end
-				if config.template_canonical.nil? || config.template_canonical.to_s.empty?
+				if config.lint_canonical.nil? || config.lint_canonical.to_s.empty?
 					puts_verbose ""
-					puts_verbose "[Canonical Templates]"
-					puts_verbose "HINT: canonical templates not configured — run carson setup to enable."
+					puts_verbose "[Canonical Lint Policy]"
+					puts_verbose "HINT: lint.canonical not configured — run carson setup to enable."
 				end
 				write_and_print_pr_monitor_report(
 					report: monitor_report.merge(
@@ -128,6 +134,7 @@ module Carson
 						command: "audit",
 						status: audit_state,
 						branch: current_branch,
+						working_tree: working_tree,
 						hooks: { status: hooks_status },
 						main_sync: main_sync,
 						pr: monitor_report[ :pr ],
@@ -175,7 +182,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: "audit", repo_path: repo_path, reason: "path not found" )
 						failed += 1
 						next
@@ -190,15 +197,15 @@ module Carson
 							clear_batch_success( command: "audit", repo_path: repo_path )
 							passed += 1
 						when EXIT_BLOCK
-							puts_line "#{repo_name}: BLOCK" unless verbose?
+							puts_line "#{repo_name}: needs attention" unless verbose?
 							blocked += 1
 						else
-							puts_line "#{repo_name}: FAIL" unless verbose?
+							puts_line "#{repo_name}: could not complete" unless verbose?
 							record_batch_skip( command: "audit", repo_path: repo_path, reason: "audit failed" )
 							failed += 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: "audit", repo_path: repo_path, reason: exception.message )
 						failed += 1
 					end
@@ -207,11 +214,30 @@ module Carson
 				puts_line ""
 				puts_line "Audit all complete: #{passed} ok, #{blocked} blocked, #{failed} failed."
 				blocked.zero? && failed.zero? ? EXIT_OK : EXIT_BLOCK
-			end
+				end
 
-		private
-			def pr_and_check_report
-				report = {
+			# rubocop:disable Layout/AccessModifierIndentation -- tab-width calculation produces unfixable mixed tabs+spaces
+			private
+			# rubocop:enable Layout/AccessModifierIndentation
+				def audit_working_tree_report
+					dirty_reason = dirty_worktree_reason
+					return { dirty: false, context: nil, status: "ok" } if dirty_reason.nil?
+
+					if dirty_reason == "main_worktree"
+						{
+							dirty: true,
+							context: dirty_reason,
+							status: "block",
+							error: "main working tree has uncommitted changes",
+							recovery: "create a worktree with carson worktree create <name>"
+						}
+					else
+						{ dirty: true, context: dirty_reason, status: "ok" }
+					end
+				end
+
+				def pr_and_check_report
+					report = {
 					generated_at: Time.now.utc.iso8601,
 					branch: current_branch,
 					status: "ok",

data/lib/carson/runtime/deliver.rb

@@ -18,15 +18,39 @@ module Carson
 				# Guard: cannot deliver from main.
 				if branch == main
 					result[ :error ] = "cannot deliver from #{main}"
-					result[ :recovery ] = "git checkout -b <branch-name>"
-					return deliver_finish( result: result, exit_code: EXIT_ERROR, json_output: json_output )
+					result[ :recovery ] = "carson worktree create <name>"
+					return deliver_finish( result: result, exit_code: EXIT_BLOCK, json_output: json_output )
+				end
+
+				# Step 1: sync managed template files before push.
+				# `push_prep: true` stages and commits managed drift so the subsequent
+				# push carries the canonical content even though deliver uses --no-verify.
+				# Output is captured to prevent pollution of --json mode.
+				# Diagnostics are preserved for error reporting.
+				sync_exit, sync_diagnostics = begin
+					saved_output, saved_error = @output, @error
+					captured_out = StringIO.new
+					captured_err = StringIO.new
+					@output = captured_out
+					@error = captured_err
+					exit_code = template_apply!( push_prep: true )
+					[ exit_code, captured_out.string + captured_err.string ]
+				rescue StandardError => exception
+					[ EXIT_ERROR, "template sync error: #{exception.message}" ]
+				ensure
+					@output, @error = saved_output, saved_error
+				end
+
+				if sync_exit == EXIT_ERROR
+					result[ :error ] = sync_diagnostics.to_s.strip.empty? ? "template sync failed" : sync_diagnostics.strip
+					return deliver_finish( result: result, exit_code: sync_exit, json_output: json_output )
 				end
 
-				# Step 1: push the branch.
+				# Step 2: push the branch.
 				push_exit = push_branch!( branch: branch, remote: remote, result: result )
 				return deliver_finish( result: result, exit_code: push_exit, json_output: json_output ) unless push_exit == EXIT_OK
 
-				# Step 2: find or create the PR.
+				# Step 3: find or create the PR.
 				pr_number, pr_url = find_or_create_pr!(
 					branch: branch, title: title, body_file: body_file, result: result
 				)
@@ -41,7 +65,7 @@ module Carson
 					return deliver_finish( result: result, exit_code: EXIT_OK, json_output: json_output )
 				end
 
-				# Step 3: check CI status.
+				# Step 4: check CI status.
 				ci_status = check_pr_ci( number: pr_number )
 				result[ :ci ] = ci_status.to_s
 
@@ -56,25 +80,35 @@ module Carson
 					return deliver_finish( result: result, exit_code: EXIT_BLOCK, json_output: json_output )
 				end
 
-				# Step 4: check review gate — block if changes are requested.
-				review = check_pr_review( number: pr_number )
-				result[ :review ] = review.to_s
-				if review == :changes_requested
+				# Step 5: check review gate — block on unresolved review debt.
+				review = check_pr_review( number: pr_number, branch: branch, pr_url: pr_url )
+				result[ :review ] = review.fetch( :review ).to_s
+				if review.fetch( :review ) == :changes_requested
 					result[ :error ] = "review changes requested on PR ##{pr_number}"
 					result[ :recovery ] = "address review comments, push, then `carson deliver --merge`"
 					return deliver_finish( result: result, exit_code: EXIT_BLOCK, json_output: json_output )
 				end
+				if review.fetch( :status ) == :fail
+					result[ :error ] = "review gate blocked on PR ##{pr_number}: #{review.fetch( :detail )}"
+					result[ :recovery ] = "resolve review gate blockers, push, then `carson deliver --merge`"
+					return deliver_finish( result: result, exit_code: EXIT_BLOCK, json_output: json_output )
+				end
+				if review.fetch( :status ) == :error
+					result[ :error ] = "unable to evaluate review gate for PR ##{pr_number}: #{review.fetch( :detail )}"
+					result[ :recovery ] = "run `carson review gate`, then retry `carson deliver --merge`"
+					return deliver_finish( result: result, exit_code: EXIT_ERROR, json_output: json_output )
+				end
 
-				# Step 5: merge.
+				# Step 6: merge.
 				merge_exit = merge_pr!( number: pr_number, result: result )
 				return deliver_finish( result: result, exit_code: merge_exit, json_output: json_output ) unless merge_exit == EXIT_OK
 
 				result[ :merged ] = true
 
-				# Step 6: sync main in the main worktree.
+				# Step 7: sync main in the main worktree.
 				sync_after_merge!( remote: remote, main: main, result: result )
 
-				# Step 7: compute next-step guidance for the agent.
+				# Step 8: compute next-step guidance for the agent.
 				compute_post_merge_next_step!( result: result )
 
 				deliver_finish( result: result, exit_code: EXIT_OK, json_output: json_output )
@@ -100,8 +134,8 @@ module Carson
 				exit_code = result.fetch( :exit_code )
 
 				if result[ :error ]
-					puts_line "ERROR: #{result[ :error ]}"
-					puts_line "  Recovery: #{result[ :recovery ]}" if result[ :recovery ]
+					puts_line result[ :error ]
+					puts_line "  → #{result[ :recovery ]}" if result[ :recovery ]
 					return
 				end
 
@@ -118,10 +152,10 @@ module Carson
 						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 ]
+						puts_line "  → #{result[ :recovery ]}" if result[ :recovery ]
 					when "fail"
-						puts_line "CI: failing — fix before merging."
-						puts_line "  Recovery: #{result[ :recovery ]}" if result[ :recovery ]
+						puts_line "CI: not passing yet — fix before merging."
+						puts_line "  → #{result[ :recovery ]}" if result[ :recovery ]
 					end
 				end
 
@@ -132,22 +166,54 @@ module Carson
 			end
 
 			# Pushes the branch to the remote with tracking.
-			# Sets CARSON_PUSH=1 so the pre-push hook knows this is a Carson-managed push.
+			# Uses --no-verify to skip the pre-push hook that Carson itself installed.
+			# The hook blocks raw pushes unconditionally; Carson bypasses by skipping it.
+			# Template sync (previously in the hook) now runs in deliver! before push.
+			# On non-fast-forward rejection (typically after rebase), retries with
+			# --force-with-lease — a protected force push that rejects if the remote
+			# ref has been updated by another actor since the last fetch.
 			def push_branch!( branch:, remote:, result: )
-				_, push_stderr, push_success, = with_env_var( "CARSON_PUSH", "1" ) do
-					git_run( "push", "-u", remote, branch )
+				_, push_stderr, push_success, = git_run( "push", "--no-verify", "-u", remote, branch )
+
+				if !push_success && push_stderr.to_s.include?( "non-fast-forward" )
+					return force_push_with_lease!( branch: branch, remote: remote, result: result )
 				end
+
 				unless push_success
 					error_text = push_stderr.to_s.strip
 					error_text = "push failed" if error_text.empty?
 					result[ :error ] = error_text
-					result[ :recovery ] = "git pull #{remote} #{branch} --rebase && git push -u #{remote} #{branch}"
 					return EXIT_ERROR
 				end
 				puts_verbose "pushed #{branch} to #{remote}"
 				EXIT_OK
 			end
 
+			# Retries push with --force-with-lease after a non-fast-forward rejection.
+			# The lease check compares the local tracking ref against the remote — if
+			# another actor pushed since our last fetch, the push is refused ("stale info").
+			# This is atomic and safe, unlike delete-and-re-push.
+			def force_push_with_lease!( branch:, remote:, result: )
+				puts_verbose "push rejected (non-fast-forward), retrying with --force-with-lease"
+				_, lease_stderr, lease_success, = git_run( "push", "--no-verify", "--force-with-lease", "-u", remote, branch )
+
+				if lease_success
+					puts_verbose "pushed #{branch} to #{remote} (force-with-lease)"
+					return EXIT_OK
+				end
+
+				# --force-with-lease rejected — another actor pushed to this branch.
+				if lease_stderr.to_s.include?( "stale info" )
+					result[ :error ] = "force-with-lease rejected — another push landed on #{branch} since your last fetch"
+					result[ :recovery ] = "git fetch #{remote} #{branch} && carson deliver"
+				else
+					error_text = lease_stderr.to_s.strip
+					error_text = "push failed (force-with-lease)" if error_text.empty?
+					result[ :error ] = error_text
+				end
+				EXIT_ERROR
+			end
+
 			# Finds an existing PR for the branch, or creates a new one.
 			# Returns [number, url] or [nil, nil] on failure.
 			def find_or_create_pr!( branch:, title: nil, body_file: nil, result: )
@@ -161,14 +227,17 @@ module Carson
 
 			# Queries gh for an open PR on this branch.
 			# Returns [number, url] or [nil, nil].
+			# gh pr view returns any PR on the branch — open, merged, or closed.
+			# We check state explicitly so merged/closed PRs are treated as absent,
+			# letting find_or_create_pr! fall through to create a new PR.
 			def find_existing_pr( branch: )
 				stdout, _, success, = gh_run(
 					"pr", "view", branch,
-					"--json", "number,url"
+					"--json", "number,url,state"
 				)
 				if success
 					data = JSON.parse( stdout ) rescue nil
-					if data && data[ "number" ]
+					if data && data[ "number" ] && data[ "state" ] == "OPEN"
 						return [ data[ "number" ], data[ "url" ].to_s ]
 					end
 				end
@@ -231,22 +300,24 @@ module Carson
 				:pass
 			end
 
-			# Checks review decision on a PR. Returns :approved, :changes_requested, :review_required, or :none.
-			def check_pr_review( number: )
-				stdout, _, success, = gh_run(
-					"pr", "view", number.to_s,
-					"--json", "reviewDecision"
+			# Checks the full review gate on a PR. Returns a structured result hash.
+			def check_pr_review( number:, branch:, pr_url: nil )
+				owner, repo = repository_coordinates
+				report = review_gate_report_for_pr(
+					owner: owner,
+					repo: repo,
+					pr_number: number,
+					branch_name: branch,
+					pr_summary: {
+						number: number,
+						title: "",
+						url: pr_url.to_s,
+						state: "OPEN"
+					}
 				)
-				return :none unless success
-
-				data = JSON.parse( stdout ) rescue {}
-				decision = data[ "reviewDecision" ].to_s.strip.upcase
-				case decision
-				when "APPROVED" then :approved
-				when "CHANGES_REQUESTED" then :changes_requested
-				when "REVIEW_REQUIRED" then :review_required
-				else :none
-				end
+				review_gate_result( report: report )
+			rescue StandardError => exception
+				{ status: :error, review: :error, detail: exception.message }
 			end
 
 			# Merges the PR using the configured merge method.
@@ -296,12 +367,12 @@ module Carson
 			# Detects whether the agent is inside a worktree and suggests cleanup.
 			def compute_post_merge_next_step!( result: )
 				main_root = main_worktree_root
-				cwd = realpath_safe( Dir.pwd )
-				current_wt = worktree_list.select { it.fetch( :path ) != realpath_safe( main_root ) }
-					.find { cwd == it.fetch( :path ) || cwd.start_with?( File.join( it.fetch( :path ), "" ) ) }
+				current_wt = worktree_list
+					.reject { it.path == realpath_safe( main_root ) }
+					.find { it.holds_cwd? }
 
 				if current_wt
-					wt_name = File.basename( current_wt.fetch( :path ) )
+					wt_name = File.basename( current_wt.path )
 					result[ :next_step ] = "cd #{main_root} && carson worktree remove #{wt_name}"
 				else
 					result[ :next_step ] = "carson prune"