carson 3.29.0 → 3.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d026cfc1581b568aaa9459ab21faf0d4f52d1026995b5ce62f21dca0072853a
-  data.tar.gz: '08bdaaebab6ccaf1dac6768057f55acf3833ddbe903001b2ca3934551f280bae'
+  metadata.gz: 5156cb5207a0ee95cad65c30d494a24ddcee97c90f2aab6861b34f9ec8e92069
+  data.tar.gz: 182a83aaa84ec1d9c0a548bdaf98e421b4eab9e4ab1248b0d67db58e42a7c5ae
 SHA512:
-  metadata.gz: 68d7fd88800a7a2756466ae88e3be1baae2df66b25d285cd54b676b6506d1ee86c69a110bf4f040c8259fc9dc8aa623120b0150b4a73c3081460c080940bfb2b
-  data.tar.gz: 35403e45bad7632031bbc9c56a8aece6e7b3dc7eafa1c36c4f183bc7c6271beb1b39d4b35985373cb9be0baee3b8cc58491920bb2f63dcf852fb20c4198c33ed
+  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,27 @@ 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
+
+- **Delivery output now shows the remote target explicitly** — `Delivery: branch → github/main` instead of the ambiguous `→ main`, making it clear the target is the remote branch, not local.
+
+### No migration required
+
+- Existing workflows continue to work unchanged.
+
 ## 3.29.0
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-3.29.0
+3.30.0

data/carson.gemspec

@@ -37,7 +37,6 @@ Gem::Specification.new do |spec|
 		"RELEASE.md",
 		"VERSION",
 		"LICENSE",
-		"SKILL.md",
 		"icon.svg",
 		"carson.gemspec"
 	]

data/lib/carson/runtime/deliver.rb

@@ -16,6 +16,7 @@ module Carson
 				result = {
 					command: "deliver",
 					branch: branch_name,
+					git_remote: remote_name,
 					watch_window_seconds: config.govern_check_wait.to_i,
 					waited_seconds: 0,
 					merge_attempted: false
@@ -220,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 )
@@ -277,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
@@ -296,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 ),
@@ -388,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 )
@@ -418,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,
@@ -427,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",
@@ -435,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,
@@ -444,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,
@@ -453,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,
@@ -462,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,
@@ -471,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,
@@ -480,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,
@@ -489,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
 
@@ -581,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 {
@@ -889,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: )
@@ -948,8 +969,10 @@ module Carson
 
 				if result[ :delivery ]
 					branch = result[ :branch ]
+					remote = result[ :git_remote ] || "github"
 					main = result[ :main_branch ] || "main"
-					puts_line "Delivery: #{branch} → #{main}"
+					remote_main = "#{remote}/#{main}"
+					puts_line "Delivery: #{branch} → #{remote_main}"
 				end
 				if result[ :commit ]
 					puts_line "Committed: #{result.dig( :commit, :summary )}"
@@ -961,9 +984,9 @@ module Carson
 					summary = result[ :summary ]
 					if outcome == "integrated" || status == "integrated"
 						if result[ :merge_method ]
-							puts_line "Merged into #{main} with #{result[ :merge_method ]}."
+							puts_line "Merged into #{remote_main} with #{result[ :merge_method ]}."
 						else
-							puts_line "Merged into #{main}."
+							puts_line "Merged into #{remote_main}."
 						end
 						if result[ :synced ] == false
 							puts_line "Local #{main} sync failed — #{result[ :sync_error ]}."

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.0
+  version: 3.30.0
 platform: ruby
 authors:
 - Hailei Wang
@@ -51,7 +51,6 @@ files:
 - MANUAL.md
 - README.md
 - RELEASE.md
-- SKILL.md
 - VERSION
 - carson.gemspec
 - exe/carson

data/SKILL.md

@@ -1,99 +0,0 @@
-# Carson Skill
-
-You are working in a repository governed by Carson — an autonomous git strategist and repositories governor. Carson handles git hooks, PR triage, agent dispatch, merge, and cleanup. You provide the intelligence; Carson provides the infrastructure.
-
-## When to use Carson commands
-
-| User intent | Command | What happens |
-|---|---|---|
-| "Check if my code is ready" | `carson audit` | Scope, boundary checks. Exit 0 = clean. Exit 2 = policy block. |
-| "Is my PR mergeable?" | `carson review gate` | Polls for unresolved review threads and actionable comments. Blocks until resolved. |
-| "What's happening across my repos?" | `carson govern --dry-run` | Classifies every open PR without taking action. Read the summary. |
-| "Run governance continuously" | `carson govern --loop 300` | Triage-dispatch-merge cycle every 300 seconds. Ctrl-C to stop. |
-| "Merge ready PRs and dispatch fixes" | `carson govern` | Full autonomous cycle: merge, dispatch agents, escalate. |
-| "Set up Carson for a repo" | `carson onboard /path/to/repo` | Installs hooks, syncs templates, runs first audit. |
-| "Refresh after upgrading Carson" | `carson refresh` | Re-applies hooks and templates for the current version. |
-| "Update my local main" | `carson sync` | Fast-forward local main from remote. Blocks if tree is dirty. |
-| "Clean up stale branches" | `carson prune` | Removes local branches whose upstream is gone. |
-| "Check template drift" | `carson template check` then `carson template apply` | Detect and fix .github/* drift. |
-| "Remove Carson from a repo" | `carson offboard /path/to/repo` | Removes hooks and managed files. |
-| "What version?" | `carson version` | Prints installed version with ⧓ badge. |
-
-## Exit codes
-
-- `0` — success, all clear.
-- `1` — runtime or configuration error. Read the error message.
-- `2` — policy block. Something must be fixed before proceeding (unresolved review, boundary breach).
-
-When you see exit 2, do NOT bypass it. Read the output, fix the root cause, and re-run.
-
-## Interpreting audit output
-
-Carson audit output is structured as labelled key-value lines prefixed with ⧓. Key sections:
-
-- **Working Tree** — staged/unstaged status.
-- **Main Sync Status** — whether local main matches remote. If ahead, reset drift before committing.
-- **Scope Integrity Guard** — checks that commits stay within a single business intent and scope group.
-- **Audit Result** — final verdict: `status: ok` (clean), `status: attention` (advisory, not blocking), `status: block` (must fix).
-
-## Interpreting govern output
-
-`carson govern --dry-run` classifies each PR:
-
-- **ready** → would merge. All gates pass.
-- **ci_failing** → would dispatch agent to fix CI.
-- **review_blocked** → would dispatch agent to address review comments.
-- **pending** → skip. Checks still running (within check_wait window).
-- **needs_attention** → escalate. Needs human judgement.
-
-The summary line: `govern_summary: repos=N prs=N ready=N blocked=N`
-
-## Configuration
-
-Single config file: `~/.carson/config.json`. Key settings:
-
-```json
-{
-  "govern": {
-    "repos": ["~/Dev/repo-a", "~/Dev/repo-b"],
-    "merge": { "method": "rebase" },
-    "agent": { "provider": "auto" }
-  },
-  "review": {
-    "bot_usernames": ["gemini-code-assist"]
-  }
-}
-```
-
-- `govern.merge.method` — must match GitHub branch protection. Use `rebase` if linear history is required.
-- `govern.repos` — list of repo paths for portfolio-level governance. Empty = current repo only.
-- `govern.agent.provider` — `auto` (tries codex then claude), `codex`, or `claude`.
-- `review.bot_usernames` — bot logins to ignore in review gate. Use GraphQL login format (no `[bot]` suffix).
-
-Environment overrides take precedence over config file. Common ones:
-- `CARSON_GOVERN_MERGE_METHOD`
-- `CARSON_REVIEW_BOT_USERNAMES`
-- `CARSON_GOVERN_CHECK_WAIT`
-
-## Common scenarios
-
-**Commit blocked by audit:**
-Run `carson audit`, read the block reason, fix it, then `git add` and `git commit` again. Do not skip the hook.
-
-**Review gate blocked:**
-Run `carson review gate` to see which comments need disposition. Respond to each with the required prefix (default: `Disposition:`), then re-run.
-
-**Local main drifted ahead of remote:**
-This means a commit was made to main that couldn't be pushed (branch protection). Reset: `git checkout main && git reset --hard github/main`.
-
-**Hooks out of date after upgrade:**
-Run `carson refresh` to re-apply hooks and templates for the current version.
-
-**Govern merge fails:**
-Check that `govern.merge.method` in config matches what GitHub allows. If the repo enforces linear history, only `rebase` works.
-
-## Boundaries
-
-- Carson never lives inside governed repositories. No `.carson.yml`, no `bin/carson`, no `.tools/carson/`.
-- Carson-managed files in repos are limited to `.github/*` templates.
-- Carson's hooks live at `~/.carson/hooks/<version>/`, never in `.git/hooks/`.