carson 3.29.1 → 3.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bdb70b55b0dddf63dd2e96b68d060472e3abfd10ae6c55010df2d43ad766c7b8
-  data.tar.gz: 122ef3005263475ce82fce1177037ddd4f017662a5a74bbee16ada7a464e0fc6
+  metadata.gz: 5156cb5207a0ee95cad65c30d494a24ddcee97c90f2aab6861b34f9ec8e92069
+  data.tar.gz: 182a83aaa84ec1d9c0a548bdaf98e421b4eab9e4ab1248b0d67db58e42a7c5ae
 SHA512:
-  metadata.gz: f526c974bf821f31a025e5a7c2a09644d3ef814c04f62a5d7021c0c6d102a9a883320c16ab20ab559159a95eee0198a26dfdec37c5684fd09936a13cbd7d081e
-  data.tar.gz: 6e7b04be1bf3a96d607599af821f38b4fb9cbaadea9c54f69407bf5d5d90bd4f10b46eec1e9254b4bbc6f1fa0c3e3bd673e9be8343a3b6e4006fe3a3291b8913
+  metadata.gz: 3e42b39fad6ca26a05bd914f7653c9cd4e7bb4227c9eb03ba5288b5e54d30f87f4b8e69991236caab797964d293ec1e6b01c4ec6a8853b24f80f7a7bb1670cfe
+  data.tar.gz: fd147d7b1941670279ad3261b0cca81639d72043b3e429a1f0290aff4a9deb53000971c5bb5953d7f36b4b574a1c5b03547f9cf33fdb3bcc16bbe4f30e5b770a

data/README.md

@@ -64,7 +64,7 @@ cd your/repo/path
 carson housekeep
 ```
 
-`carson deliver` runs Carson-owned branch delivery. Before any push, Carson verifies that the branch is fresh against the configured remote `main`. If freshness is behind or unknown, delivery stops with an explicit block and no PR side effect. Plain `deliver` transports existing commits only; `carson deliver --commit "..."` creates one all-dirty delivery commit first, then continues the same flow. If the branch is fresh, Carson pushes it, creates or refreshes the PR, watches the delivery for a bounded settle window, merges when clear, and syncs local `main`. If the settle window expires without integration, Carson exits with an explicit `Merge deferred` or `Merge blocked` handoff instead of leaving the PR mysteriously open. Deferred and blocked exits say whether Carson attempted merge and list the next commands in order.
+`carson deliver` runs Carson-owned branch delivery. Before any push, Carson verifies that the branch is fresh against the configured remote `main` using local git. If freshness is behind or unknown, delivery stops with an explicit block and no PR side effect. After a PR exists, Carson delegates merge eligibility to GitHub's `mergeStateStatus` — if GitHub reports `CLEAN`, Carson proceeds regardless of local ancestor status. Plain `deliver` transports existing commits only; `carson deliver --commit "..."` creates one all-dirty delivery commit first, then continues the same flow. If the branch is fresh, Carson pushes it, creates or refreshes the PR, watches the delivery for a bounded settle window, merges when clear, and syncs local `main`. If the settle window expires without integration, Carson exits with an explicit `Merge deferred` or `Merge blocked` handoff instead of leaving the PR mysteriously open. Deferred and blocked exits say whether Carson attempted merge and list the next commands in order.
 
 When one Carson-governed required check is already red on the default branch and the current PR is the repair, use `carson recover --check "..."`. Recovery is the explicit exceptional path: Carson proves the baseline failure, keeps every other gate intact, records an audit event, and never teaches operators to step outside Carson first.
 

data/RELEASE.md

@@ -5,6 +5,17 @@ Release-note scope rule:
 - `RELEASE.md` records only version deltas, breaking changes, and migration actions.
 - Operational usage guides live in `MANUAL.md` and `API.md`.
 
+## 3.30.0
+
+### What changed
+
+- **Post-PR merge eligibility is now delegated to GitHub** — After a PR exists, Carson uses GitHub's `mergeStateStatus` as the sole authority for merge eligibility instead of running a local `git merge-base --is-ancestor` check. If GitHub reports `CLEAN`, Carson proceeds regardless of local ancestor status. If GitHub reports `BEHIND`, the delivery is held. The pre-push freshness check (before any PR exists) is unchanged.
+- **Govern and deliver no longer false-block in busy repos** — In repositories where govern merges PRs serially, each merge advances main and previously made every subsequent queued PR permanently stuck unless manually rebased. Carson now integrates any PR that GitHub considers merge-eligible.
+
+### No migration required
+
+- Existing workflows continue to work unchanged. PRs that were previously false-blocked by local freshness checks will now integrate when GitHub reports them as merge-eligible.
+
 ## 3.29.1
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-3.29.1
+3.30.0

data/lib/carson/runtime/deliver.rb

@@ -221,24 +221,8 @@ module Carson
 			end
 
 			# Assesses delivery readiness and records Carson's current branch state.
+			# Post-PR freshness is delegated to GitHub's mergeStateStatus via delivery_assessment.
 			def assess_delivery!( delivery:, branch_name: )
-				freshness = assess_branch_freshness(
-					head_ref: delivery.head || branch_name,
-					remote: config.git_remote,
-					main: config.main_branch
-				)
-				unless freshness.fetch( :ready )
-					return ledger.update_delivery(
-						delivery: delivery,
-						status: "gated",
-						cause: "freshness",
-						summary: freshness.fetch( :summary ),
-						pr_number: delivery.pull_request_number,
-						pr_url: delivery.pull_request_url,
-						worktree_path: delivery.worktree_path
-					)
-				end
-
 					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 )
 					pr_state = pull_request_state( number: delivery.pull_request_number )
@@ -278,7 +262,14 @@ module Carson
 					last_evaluation = evaluation
 					successful_assessments += 1 if evaluation[ :assessment_success ]
 					result[ :ci ] = evaluation[ :ci ].to_s
-					result[ :freshness ] = freshness_payload( freshness: evaluation.fetch( :freshness ) ) if evaluation[ :freshness ]
+					if evaluation[ :cause ] == "freshness"
+						result[ :freshness ] = {
+							status: "behind",
+							reason: "freshness_behind",
+							summary: evaluation[ :summary ],
+							base_ref: "#{config.git_remote}/#{main}"
+						}
+					end
 
 					delivery = update_delivery_for_settle_evaluation( delivery: delivery, evaluation: evaluation )
 					result[ :summary ] = delivery.summary
@@ -297,7 +288,7 @@ module Carson
 					when :blocked
 						result[ :outcome ] = "blocked"
 						result[ :waited_seconds ] = elapsed_settle_seconds( started_at: started_at )
-						result[ :recovery ] = freshness_recovery( freshness: evaluation.fetch( :freshness ) ) if evaluation[ :cause ] == "freshness" && evaluation[ :freshness ]
+						result[ :recovery ] = "git rebase #{config.git_remote}/#{main} && carson deliver" if evaluation[ :cause ] == "freshness"
 						apply_handoff!(
 							result: result,
 							reason: evaluation.fetch( :reason ),
@@ -389,25 +380,8 @@ module Carson
 				delivery
 			end
 
+				# Post-PR freshness is delegated to GitHub's mergeStateStatus via settle_mergeability_assessment.
 				def evaluate_delivery_for_settle( branch_name:, head_ref:, pr_number:, pr_url:, main: )
-					freshness = assess_branch_freshness(
-						branch_name: branch_name,
-						head_ref: head_ref,
-						remote: config.git_remote,
-						main: main
-					)
-					unless freshness.fetch( :ready )
-						return {
-							phase: :blocked,
-							reason: freshness.fetch( :reason ),
-							cause: "freshness",
-							summary: freshness.fetch( :summary ),
-							assessment_success: freshness.fetch( :status ) != :unknown,
-							ci: :none,
-							freshness: freshness
-						}
-					end
-
 					review = check_pr_review( number: pr_number, branch: branch_name, pr_url: pr_url )
 					ci = settle_check_pr_ci( number: pr_number )
 					pr_state = pull_request_state( number: pr_number )
@@ -419,7 +393,7 @@ module Carson
 						summary: "waiting for GitHub assessment",
 						assessment_success: false,
 						ci: ci
-					}.merge( freshness: freshness, pr_state: pr_state ) if ci == :error || review.fetch( :status, :pass ) == :error || !pr_state.is_a?( Hash )
+					}.merge( pr_state: pr_state ) if ci == :error || review.fetch( :status, :pass ) == :error || !pr_state.is_a?( Hash )
 
 					return {
 						phase: :integrated,
@@ -428,7 +402,7 @@ module Carson
 						summary: "integrated into #{main}",
 						assessment_success: true,
 						ci: ci
-					}.merge( freshness: freshness, pr_state: pr_state ) if pr_state[ "state" ] == "MERGED"
+					}.merge( pr_state: pr_state ) if pr_state[ "state" ] == "MERGED"
 					return {
 						phase: :blocked,
 						reason: "pull_request_closed",
@@ -436,7 +410,7 @@ module Carson
 						summary: "pull request closed without integration",
 						assessment_success: true,
 						ci: ci
-					}.merge( freshness: freshness, pr_state: pr_state ) if pr_state[ "state" ] == "CLOSED"
+					}.merge( pr_state: pr_state ) if pr_state[ "state" ] == "CLOSED"
 
 					return {
 						phase: :blocked,
@@ -445,7 +419,7 @@ module Carson
 						summary: "pull request is still a draft",
 						assessment_success: true,
 						ci: ci
-					}.merge( freshness: freshness, pr_state: pr_state ) if pr_state[ "isDraft" ]
+					}.merge( pr_state: pr_state ) if pr_state[ "isDraft" ]
 
 					return {
 						phase: :waiting,
@@ -454,7 +428,7 @@ module Carson
 						summary: "waiting for CI checks",
 						assessment_success: true,
 						ci: ci
-					}.merge( freshness: freshness, pr_state: pr_state ) if ci == :pending
+					}.merge( pr_state: pr_state ) if ci == :pending
 
 					return {
 						phase: :blocked,
@@ -463,7 +437,7 @@ module Carson
 						summary: "CI checks are failing",
 						assessment_success: true,
 						ci: ci
-					}.merge( freshness: freshness, pr_state: pr_state ) if ci == :fail
+					}.merge( pr_state: pr_state ) if ci == :fail
 
 					return {
 						phase: :blocked,
@@ -472,7 +446,7 @@ module Carson
 						summary: "review changes requested",
 						assessment_success: true,
 						ci: ci
-					}.merge( freshness: freshness, pr_state: pr_state ) if review.fetch( :review, :none ) == :changes_requested
+					}.merge( pr_state: pr_state ) if review.fetch( :review, :none ) == :changes_requested
 
 					return {
 						phase: :waiting,
@@ -481,7 +455,7 @@ module Carson
 						summary: "waiting for review",
 						assessment_success: true,
 						ci: ci
-					}.merge( freshness: freshness, pr_state: pr_state ) if review.fetch( :review, :none ) == :review_required
+					}.merge( pr_state: pr_state ) if review.fetch( :review, :none ) == :review_required
 
 					return {
 						phase: :blocked,
@@ -490,49 +464,28 @@ module Carson
 						summary: review.fetch( :detail ).to_s,
 						assessment_success: true,
 						ci: ci
-					}.merge( freshness: freshness, pr_state: pr_state ) if review.fetch( :status, :pass ) == :fail
+					}.merge( pr_state: pr_state ) if review.fetch( :status, :pass ) == :fail
 
 					mergeability = settle_mergeability_assessment( pr_state: pr_state, main: main )
-					mergeability.merge( assessment_success: true, ci: ci, freshness: freshness, pr_state: pr_state )
+					mergeability.merge( assessment_success: true, ci: ci, pr_state: pr_state )
 				end
 
 			def settle_mergeability_assessment( pr_state:, main: )
-				mergeable = pr_state.fetch( "mergeable", "" ).to_s.upcase
-				merge_state = pr_state.fetch( "mergeStateStatus", "" ).to_s.upcase
-
-				return {
-					phase: :blocked,
-					reason: "merge_conflict",
-					cause: "merge",
-					summary: "pull request has merge conflicts"
-				} if mergeable == "CONFLICTING" || merge_state == "DIRTY" || merge_state == "CONFLICTING"
-
-				return {
-					phase: :blocked,
-					reason: "repository_policy_block",
-					cause: "merge",
-					summary: "merge is blocked by repository policy"
-				} if merge_state == "BLOCKED"
-
-				return {
-					phase: :blocked,
-					reason: "freshness_behind",
-					cause: "freshness",
-					summary: "branch is behind #{config.git_remote}/#{main}"
-				} if merge_state == "BEHIND"
-
-				return {
-					phase: :ready,
-					reason: "ready",
-					cause: nil,
-					summary: "ready to integrate into #{main}"
-				} if merge_state == "CLEAN" || mergeable == "MERGEABLE"
-
+				assessment = github_merge_assessment( pr_state: pr_state )
+				phase = if assessment[ :ready ]
+					:ready
+				elsif [ "mergeability_pending", "assessment_unavailable" ].include?( assessment[ :reason ] )
+					:waiting
+				else
+					:blocked
+				end
+				# Preserve the settle-loop's "assessment" cause for pending/unavailable states
+				cause = phase == :waiting ? "assessment" : assessment[ :cause ]
 				{
-					phase: :waiting,
-					reason: "mergeability_pending",
-					cause: "assessment",
-					summary: "waiting for GitHub mergeability"
+					phase: phase,
+					reason: assessment[ :reason ],
+					cause: cause,
+					summary: assessment[ :summary ]
 				}
 			end
 
@@ -582,29 +535,37 @@ module Carson
 				end
 			end
 
+			# Pre-merge recheck using GitHub as the authority for merge eligibility.
+			# Blocks on definite GitHub-reported issues (BEHIND, CONFLICTING, BLOCKED, draft).
+			# Allows through pending/unknown states — the merge attempt itself will succeed or fail.
 			def attempt_delivery_merge!( delivery:, remote:, main:, result: )
-				freshness = assess_branch_freshness(
-					head_ref: delivery.head || delivery.branch,
-					remote: remote,
-					main: main
-				)
-				result[ :freshness ] = freshness_payload( freshness: freshness )
-				unless freshness.fetch( :ready )
-					result[ :recovery ] = freshness_recovery( freshness: freshness )
-					return {
-						phase: :blocked,
-						attempted: false,
-						reason: freshness.fetch( :reason ),
-						delivery: ledger.update_delivery(
-							delivery: delivery,
-							status: "gated",
-							cause: "freshness",
-							summary: freshness.fetch( :summary )
-						)
-					}
-				end
-
 					pr_state = pull_request_state( number: delivery.pull_request_number )
+					merge_check = github_merge_assessment( pr_state: pr_state )
+					definite_blocker = !merge_check[ :ready ] &&
+						![ "mergeability_pending", "assessment_unavailable" ].include?( merge_check[ :reason ] )
+					if definite_blocker
+						if merge_check[ :cause ] == "freshness"
+							result[ :freshness ] = {
+								status: "behind",
+								reason: "freshness_behind",
+								summary: merge_check[ :summary ],
+								base_ref: "#{remote}/#{main}"
+							}
+						end
+						result[ :recovery ] = merge_check[ :recovery ] if merge_check[ :recovery ]
+						return {
+							phase: :blocked,
+							attempted: false,
+							reason: merge_check[ :reason ],
+							delivery: ledger.update_delivery(
+								delivery: delivery,
+								status: "gated",
+								cause: merge_check[ :cause ],
+								summary: merge_check[ :summary ]
+							)
+						}
+					end
+
 					observation = pull_request_observation_attributes( pr_state: pr_state )
 					if pr_state && pr_state[ "state" ] == "MERGED"
 						return {
@@ -890,19 +851,78 @@ module Carson
 				[ "gated", "merge", "waiting for GitHub mergeability" ]
 			end
 
-			def mergeability_assessment( pr_state: )
-				return nil unless pr_state.is_a?( Hash )
+			# Interprets GitHub's PR state into a merge readiness verdict.
+			# Pure method — no API calls. Accepts the already-fetched pr_state hash.
+			# Returns a standardised hash: { ready:, reason:, cause:, summary:, recovery: }
+			def github_merge_assessment( pr_state: )
+				unless pr_state.is_a?( Hash )
+					return {
+						ready: false,
+						reason: "assessment_unavailable",
+						cause: "merge",
+						summary: "waiting for GitHub mergeability",
+						recovery: nil
+					}
+				end
 
 				mergeable = pr_state.fetch( "mergeable", "" ).to_s.upcase
 				merge_state = pr_state.fetch( "mergeStateStatus", "" ).to_s.upcase
+				remote_main = "#{config.git_remote}/#{config.main_branch}"
 
-				return [ "gated", "policy", "pull request is still a draft" ] if pr_state[ "isDraft" ]
-				return [ "gated", "merge", "pull request has merge conflicts" ] if mergeable == "CONFLICTING" || merge_state == "DIRTY" || merge_state == "CONFLICTING"
-				return [ "gated", "merge", "merge is blocked by repository policy" ] if merge_state == "BLOCKED"
-				return [ "gated", "freshness", "branch is behind #{config.git_remote}/#{config.main_branch}" ] if merge_state == "BEHIND"
-				return [ "queued", nil, "ready to integrate into #{config.main_branch}" ] if merge_state == "CLEAN" || mergeable == "MERGEABLE"
+				return {
+					ready: false,
+					reason: "draft_pr",
+					cause: "policy",
+					summary: "pull request is still a draft",
+					recovery: nil
+				} if pr_state[ "isDraft" ]
 
-				nil
+				return {
+					ready: false,
+					reason: "merge_conflict",
+					cause: "merge",
+					summary: "pull request has merge conflicts",
+					recovery: nil
+				} if mergeable == "CONFLICTING" || merge_state == "DIRTY" || merge_state == "CONFLICTING"
+
+				return {
+					ready: false,
+					reason: "repository_policy_block",
+					cause: "merge",
+					summary: "merge is blocked by repository policy",
+					recovery: nil
+				} if merge_state == "BLOCKED"
+
+				return {
+					ready: false,
+					reason: "freshness_behind",
+					cause: "freshness",
+					summary: "branch is behind #{remote_main}",
+					recovery: "git rebase #{remote_main} && carson deliver"
+				} if merge_state == "BEHIND"
+
+				return {
+					ready: true,
+					reason: "ready",
+					cause: nil,
+					summary: "ready to integrate into #{config.main_branch}",
+					recovery: nil
+				} if merge_state == "CLEAN" || mergeable == "MERGEABLE"
+
+				{
+					ready: false,
+					reason: "mergeability_pending",
+					cause: "merge",
+					summary: "waiting for GitHub mergeability",
+					recovery: nil
+				}
+			end
+
+			def mergeability_assessment( pr_state: )
+				assessment = github_merge_assessment( pr_state: pr_state )
+				return nil if assessment[ :reason ] == "mergeability_pending" && pr_state.is_a?( Hash )
+				status = assessment[ :ready ] ? "queued" : "gated"
+				[ status, assessment[ :cause ], assessment[ :summary ] ]
 			end
 
 			def delivery_payload( delivery: )

data/lib/carson/runtime/govern.rb

@@ -216,19 +216,20 @@ module Carson
 				end
 			end
 
+				# Final pre-merge recheck using GitHub as authority for merge eligibility.
+				# Intentionally strict: blocks on ANY non-ready state (including pending/unavailable).
+				# Unlike deliver's attempt_delivery_merge! which allows speculative merges on pending states,
+				# govern runs unattended and should not speculatively attempt merges on uncertain state.
 				def integrate_delivery!( delivery:, repo_path: )
 					result = {}
-					freshness = assess_branch_freshness(
-						head_ref: delivery.head || delivery.branch,
-						remote: config.git_remote,
-						main: config.main_branch
-					)
-					unless freshness.fetch( :ready )
+					pr_state = pull_request_state( number: delivery.pull_request_number )
+					merge_check = github_merge_assessment( pr_state: pr_state )
+					unless merge_check[ :ready ]
 						return ledger.update_delivery(
 							delivery: delivery,
 							status: "gated",
-							cause: "freshness",
-							summary: freshness.fetch( :summary )
+							cause: merge_check[ :cause ],
+							summary: merge_check[ :summary ]
 						)
 					end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 3.29.1
+  version: 3.30.0
 platform: ruby
 authors:
 - Hailei Wang