carson 3.21.1 → 3.22.1

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
@@ -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
 
-				# Step 1: push the branch.
+				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 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,43 +65,50 @@ 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
 
 				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.
-				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 )
@@ -103,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
 
@@ -117,15 +148,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 ]
+						puts_line "  → #{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 ]
+						puts_line "CI: not passing yet — fix before merging."
+						puts_line "  → #{result[ :recovery ]}" if result[ :recovery ]
 					end
 				end
 
@@ -136,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: )
@@ -165,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
@@ -235,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.
@@ -300,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"

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