carson 3.22.0 → 3.23.0

data/lib/carson/runtime/deliver.rb

@@ -1,86 +1,118 @@
-# 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 passes or no checks are configured.
-# `carson deliver --json` outputs structured result for agent consumption.
+# Branch delivery lifecycle — push, create/update PR, and register Carson-owned delivery state.
+# `carson deliver` is now the async handoff point. It does not wait for merge.
 module Carson
 	class Runtime
 		module Deliver
 			# Entry point for `carson deliver`.
-			# Pushes current branch, creates a PR if needed, reports the PR URL.
-			# With merge: true, also merges if CI passes and cleans up.
-			def deliver!( merge: false, title: nil, body_file: nil, json_output: false )
-				branch = current_branch
-				main = config.main_branch
-				remote = config.git_remote
-				result = { command: "deliver", branch: branch }
-
-				# 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 )
+			# Pushes the current branch, ensures a PR exists, records delivery state, and returns.
+			def deliver!( title: nil, body_file: nil, json_output: false )
+				branch_name = current_branch
+				main_branch = config.main_branch
+				remote_name = config.git_remote
+				result = { command: "deliver", branch: branch_name }
+
+				if branch_name == main_branch
+					result[ :error ] = "cannot deliver from #{main_branch}"
+					result[ :recovery ] = "carson worktree create <name>"
+					return deliver_finish( result: result, exit_code: EXIT_BLOCK, json_output: json_output )
+				end
+
+				sync_exit, sync_diagnostics = deliver_template_sync
+				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.
-				push_exit = push_branch!( branch: branch, remote: remote, result: result )
+				push_exit = push_branch!( branch: branch_name, remote: remote_name, 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.
 				pr_number, pr_url = find_or_create_pr!(
-					branch: branch, title: title, body_file: body_file, result: result
+					branch: branch_name,
+					title: title,
+					body_file: body_file,
+					result: result
 				)
-				if pr_number.nil?
-					return deliver_finish( result: result, exit_code: EXIT_ERROR, json_output: json_output )
-				end
+				return deliver_finish( result: result, exit_code: EXIT_ERROR, json_output: json_output ) if pr_number.nil?
+
+				branch = branch_record( name: branch_name )
+				delivery = ledger.upsert_delivery(
+					repository: repository_record,
+					branch_name: branch.name,
+					head: branch.head || current_head,
+					worktree_path: branch.worktree || repo_root,
+					authority: config.govern_authority,
+					pr_number: pr_number,
+					pr_url: pr_url,
+					status: "preparing",
+					summary: "delivery accepted",
+					cause: nil
+				)
+				delivery = assess_delivery!( delivery: delivery, branch_name: branch.name )
 
 				result[ :pr_number ] = pr_number
 				result[ :pr_url ] = pr_url
-				# Without --merge, we are done.
-				unless merge
-					return deliver_finish( result: result, exit_code: EXIT_OK, json_output: json_output )
-				end
+				result[ :ci ] = check_pr_ci( number: pr_number ).to_s
+				result[ :delivery ] = delivery_payload( delivery: delivery )
+				result[ :summary ] = delivery.summary
+				result[ :next_step ] = "carson status"
 
-				# Step 3: check CI status.
-				ci_status = check_pr_ci( number: pr_number )
-				result[ :ci ] = ci_status.to_s
-
-				case ci_status
-				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 )
-				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
-					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
+				deliver_finish( result: result, exit_code: EXIT_OK, json_output: json_output )
+			end
 
-				# Step 5: 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
+		private
 
-				result[ :merged ] = true
+			def deliver_template_sync
+				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 6: sync main in the main worktree.
-				sync_after_merge!( remote: remote, main: main, result: result )
+			# Assesses delivery readiness and records Carson's current branch state.
+			def assess_delivery!( delivery:, branch_name: )
+				review = check_pr_review( number: delivery.pull_request_number, branch: branch_name, pr_url: delivery.pull_request_url )
+				ci = check_pr_ci( number: delivery.pull_request_number )
+				status, cause, summary = delivery_assessment( ci: ci, review: review )
+
+				ledger.update_delivery(
+					delivery: delivery,
+					status: status,
+					cause: cause,
+					summary: summary,
+					pr_number: delivery.pull_request_number,
+					pr_url: delivery.pull_request_url,
+					worktree_path: delivery.worktree_path
+				)
+			end
 
-				# Step 7: compute next-step guidance for the agent.
-				compute_post_merge_next_step!( result: result )
+			def delivery_assessment( ci:, review: )
+				return [ "gated", "ci", "waiting for CI checks" ] if ci == :pending
+				return [ "gated", "ci", "CI checks are failing" ] if ci == :fail
+				return [ "gated", "review", "review changes requested" ] if review.fetch( :review, :none ) == :changes_requested
+				return [ "gated", "review", "waiting for review" ] if review.fetch( :review, :none ) == :review_required
+				return [ "gated", "review", review.fetch( :detail ).to_s ] if review.fetch( :status, :pass ) == :fail
+				return [ "gated", "policy", "unable to assess review gate: #{review.fetch( :detail )}" ] if review.fetch( :status, :pass ) == :error
 
-				deliver_finish( result: result, exit_code: EXIT_OK, json_output: json_output )
+				[ "queued", nil, "ready to integrate into #{config.main_branch}" ]
 			end
 
-		private
+			def delivery_payload( delivery: )
+				{
+					id: delivery.id,
+					status: delivery.status,
+					head: delivery.head,
+					worktree_path: delivery.worktree_path,
+					revision_count: delivery.revision_count,
+					cause: delivery.cause
+				}
+			end
 
 			# Outputs the final result — JSON or human-readable — and returns exit code.
 			def deliver_finish( result:, exit_code:, json_output: )
@@ -97,78 +129,76 @@ module Carson
 
 			# Human-readable output for deliver results.
 			def print_deliver_human( result: )
-				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
 
-				if result[ :pr_number ]
-					puts_line "PR: ##{result[ :pr_number ]} #{result[ :pr_url ]}"
-				end
-
-				if result[ :ci ]
-					ci = result[ :ci ]
-					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 ]
-					end
-				end
-
-				if result[ :merged ]
-					puts_line "Merged PR ##{result[ :pr_number ]} via #{result[ :merge_method ]}."
-					puts_line "  Next: #{result[ :next_step ]}" if result[ :next_step ]
+				puts_line "PR: ##{result[ :pr_number ]} #{result[ :pr_url ]}" if result[ :pr_number ]
+				if result[ :delivery ]
+					puts_line "Delivery: #{result.dig( :delivery, :status )}"
 				end
+				puts_line "Summary: #{result[ :summary ]}" if result[ :summary ]
+				puts_line "  Next: #{result[ :next_step ]}" if result[ :next_step ]
 			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.
 			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.
+			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
+
+				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: )
-				# Check for existing PR.
 				existing = find_existing_pr( branch: branch )
 				return existing if existing.first
 
-				# Create a new PR.
 				create_pr!( branch: branch, title: title, body_file: body_file, result: result )
 			end
 
 			# Queries gh for an open PR on this branch.
-			# Returns [number, url] or [nil, nil].
 			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
@@ -176,11 +206,10 @@ module Carson
 			end
 
 			# Creates a PR via gh. Title defaults to branch name humanised.
-			# Returns [number, url] or [nil, nil] on failure.
 			def create_pr!( branch:, title: nil, body_file: nil, result: )
 				pr_title = title || default_pr_title( branch: branch )
-
 				args = [ "pr", "create", "--title", pr_title, "--head", branch ]
+
 				if body_file && File.exist?( body_file )
 					args.push( "--body-file", body_file )
 				else
@@ -196,24 +225,18 @@ module Carson
 					return [ nil, nil ]
 				end
 
-				# gh pr create prints the URL on success. Parse number from it.
 				pr_url = stdout.to_s.strip
 				pr_number = pr_url.split( "/" ).last.to_i
-				if pr_number > 0
-					[ pr_number, pr_url ]
-				else
-					# Fallback: query the just-created PR.
-					find_existing_pr( branch: branch )
-				end
+				return [ pr_number, pr_url ] if pr_number > 0
+
+				find_existing_pr( branch: branch )
 			end
 
-			# Generates a default PR title from the branch name.
 			def default_pr_title( branch: )
-				branch.tr( "-", " " ).gsub( "/", ": " ).sub( /\A\w/ ) { it.upcase }
+				branch.tr( "-", " " ).gsub( "/", ": " ).sub( /\A\w/ ) { |character| character.upcase }
 			end
 
 			# Checks CI status on a PR. Returns :pass, :fail, :pending, or :none.
-			# Uses the `bucket` field (pass/fail/pending) from `gh pr checks --json`.
 			def check_pr_ci( number: )
 				stdout, _, success, = gh_run(
 					"pr", "checks", number.to_s,
@@ -224,35 +247,47 @@ module Carson
 				checks = JSON.parse( stdout ) rescue []
 				return :none if checks.empty?
 
-				buckets = checks.map { it[ "bucket" ].to_s.downcase }
+				buckets = checks.map { |entry| entry[ "bucket" ].to_s.downcase }
 				return :fail if buckets.include?( "fail" )
 				return :pending if buckets.include?( "pending" )
 
 				:pass
 			end
 
-			# Checks review decision on a PR. Returns :approved, :changes_requested, :review_required, or :none.
-			def check_pr_review( number: )
+			# 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"
+					}
+				)
+				review_gate_result( report: report )
+			rescue StandardError => exception
+				{ status: :error, review: :error, detail: exception.message }
+			end
+
+			# Returns the current PR state for govern reconciliation.
+			def pull_request_state( number: )
 				stdout, _, success, = gh_run(
 					"pr", "view", number.to_s,
-					"--json", "reviewDecision"
+					"--json", "number,state,isDraft,url"
 				)
-				return :none unless success
+				return nil 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
+				JSON.parse( stdout )
+			rescue JSON::ParserError
+				nil
 			end
 
-			# Merges the PR using the configured merge method.
-			# Deliberately omits --delete-branch: gh tries to switch the local
-			# checkout to main afterwards, which fails inside a worktree where
-			# main is already checked output. Branch cleanup deferred to `carson prune`.
+			# Merges the PR using the governed merge method.
 			def merge_pr!( number:, result: )
 				method = config.govern_merge_method
 				result[ :merge_method ] = method
@@ -274,9 +309,6 @@ module Carson
 			end
 
 			# Syncs main after a successful merge.
-			# Pulls into the main worktree directly — does not attempt checkout,
-			# because checkout would fail when running inside a feature worktree
-			# (main is already checked output in the main tree).
 			def sync_after_merge!( remote:, main:, result: )
 				main_root = main_worktree_root
 				_, pull_stderr, pull_success, = Open3.capture3(
@@ -291,24 +323,6 @@ module Carson
 					puts_verbose "sync failed: #{pull_stderr.to_s.strip}"
 				end
 			end
-
-			# Builds next-step guidance after a successful merge.
-			# 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 ), "" ) ) }
-
-				if current_wt
-					wt_name = File.basename( current_wt.fetch( :path ) )
-					result[ :next_step ] = "cd #{main_root} && carson worktree remove #{wt_name}"
-				else
-					result[ :next_step ] = "carson prune"
-				end
-			rescue StandardError
-				# Best-effort — do not fail deliver because of next-step detection.
-			end
 		end
 
 		include Deliver