carson 3.22.0 → 3.22.1

data/lib/carson/runtime/review.rb

@@ -24,15 +24,16 @@ module Carson
 					puts_line "Review Gate"
 				end
 				unless gh_available?
-					puts_line "ERROR: gh CLI not available in PATH."
+					puts_line "gh CLI not found in PATH — install it to use review commands."
 					return EXIT_ERROR
 				end
 
 				owner, repo = repository_coordinates
+				branch = current_branch
 				pr_number_override = carson_pr_number_override
 				pr_summary =
 					if pr_number_override.nil?
-						current_pull_request_for_branch( branch_name: current_branch )
+						current_pull_request_for_branch( branch_name: branch )
 					else
 						details = pull_request_details( owner: owner, repo: repo, pr_number: pr_number_override )
 						{
@@ -43,93 +44,36 @@ module Carson
 						}
 					end
 				if pr_summary.nil?
-					puts_line "BLOCK: no pull request found for branch #{current_branch}."
-					report = {
-						generated_at: Time.now.utc.iso8601,
-						branch: current_branch,
-						status: "block",
-						converged: false,
-						wait_seconds: config.review_wait_seconds,
-						poll_seconds: config.review_poll_seconds,
-						max_polls: config.review_max_polls,
-						block_reasons: [ "no pull request found for current branch" ],
-						pr: nil,
-						unresolved_threads: [],
-						actionable_top_level: [],
-						unacknowledged_actionable: []
-					}
+					puts_line "No pull request found for branch #{branch}."
+					report = review_gate_report_for_missing_pr( branch_name: branch )
 					write_review_gate_report( report: report )
 					return EXIT_BLOCK
 				end
 
-				pre_snapshot = wait_for_review_warmup( owner: owner, repo: repo, pr_number: pr_summary.fetch( :number ) )
-				converged = false
-				last_snapshot = pre_snapshot
-				last_signature = pre_snapshot.nil? ? nil : review_gate_signature( snapshot: pre_snapshot )
-				poll_attempts = 0
-
-				config.review_max_polls.times do |index|
-					poll_attempts = index + 1
-					snapshot = review_gate_snapshot( owner: owner, repo: repo, pr_number: pr_summary.fetch( :number ) )
-					last_snapshot = snapshot
-					signature = review_gate_signature( snapshot: snapshot )
-					puts_verbose "poll_attempt: #{poll_attempts}/#{config.review_max_polls}"
-					puts_verbose "latest_activity: #{snapshot.fetch( :latest_activity ) || 'unknown'}"
-					puts_verbose "unresolved_threads: #{snapshot.fetch( :unresolved_threads ).count}"
-					puts_verbose "unacknowledged_actionable: #{snapshot.fetch( :unacknowledged_actionable ).count}"
-					if !last_signature.nil? && signature == last_signature
-						converged = true
-						puts_verbose "convergence: stable"
-						break
-					end
-					last_signature = signature
-					wait_for_review_poll if index < config.review_max_polls - 1
-				end
-
-				block_reasons = []
-				block_reasons << "review snapshot did not converge within #{config.review_max_polls} polls" unless converged
-				if last_snapshot.fetch( :unresolved_threads ).any?
-					block_reasons << "unresolved review threads remain (#{last_snapshot.fetch( :unresolved_threads ).count})"
-				end
-				if last_snapshot.fetch( :unacknowledged_actionable ).any?
-					block_reasons << "actionable top-level comments/reviews without required disposition (#{last_snapshot.fetch( :unacknowledged_actionable ).count})"
-				end
-
-				report = {
-					generated_at: Time.now.utc.iso8601,
-					branch: current_branch,
-					status: block_reasons.empty? ? "ok" : "block",
-					converged: converged,
-					wait_seconds: config.review_wait_seconds,
-					poll_seconds: config.review_poll_seconds,
-					max_polls: config.review_max_polls,
-					poll_attempts: poll_attempts,
-					block_reasons: block_reasons,
-					pr: {
-						number: pr_summary.fetch( :number ),
-						title: pr_summary.fetch( :title ),
-						url: pr_summary.fetch( :url ),
-						state: pr_summary.fetch( :state )
-					},
-					unresolved_threads: last_snapshot.fetch( :unresolved_threads ),
-					actionable_top_level: last_snapshot.fetch( :actionable_top_level ),
-					unacknowledged_actionable: last_snapshot.fetch( :unacknowledged_actionable )
-				}
+				report = review_gate_report_for_pr(
+					owner: owner,
+					repo: repo,
+					pr_number: pr_summary.fetch( :number ),
+					branch_name: branch,
+					pr_summary: pr_summary
+				)
 				write_review_gate_report( report: report )
 				unless verbose?
+					poll_attempts = report.fetch( :poll_attempts, 0 )
 					puts_line "Polling... (converged after #{poll_attempts} attempt#{plural_suffix( count: poll_attempts )})"
 				end
+				block_reasons = report.fetch( :block_reasons )
 				if block_reasons.empty?
 					puts_line "OK: review gate passed."
 					return EXIT_OK
 				end
-				block_reasons.each { |reason| puts_line "BLOCK: #{reason}" }
+				block_reasons.each { |reason| puts_line reason }
 				EXIT_BLOCK
 			rescue JSON::ParserError => exception
-				puts_line "ERROR: invalid gh JSON response (#{exception.message})."
+				puts_line "Unexpected response from gh (#{exception.message})."
 				EXIT_ERROR
 			rescue StandardError => exception
-				puts_line "ERROR: #{exception.message}"
+				puts_line exception.message
 				EXIT_ERROR
 			end
 
@@ -140,7 +84,7 @@ module Carson
 				puts_verbose ""
 				puts_verbose "[Review Sweep]"
 				unless gh_available?
-					puts_line "ERROR: gh CLI not available in PATH."
+					puts_line "gh CLI not found in PATH — install it to use review commands."
 					return EXIT_ERROR
 				end
 
@@ -176,13 +120,13 @@ module Carson
 					puts_line "OK: no actionable late review activity detected."
 					return EXIT_OK
 				end
-				puts_line "BLOCK: actionable late review activity detected."
+				puts_line "Late review activity needs attention."
 				EXIT_BLOCK
 			rescue JSON::ParserError => exception
-				puts_line "ERROR: invalid gh JSON response (#{exception.message})."
+				puts_line "Unexpected response from gh (#{exception.message})."
 				EXIT_ERROR
 			rescue StandardError => exception
-				puts_line "ERROR: #{exception.message}"
+				puts_line exception.message
 				EXIT_ERROR
 			end
 		end

data/lib/carson/runtime/setup.rb

@@ -45,8 +45,8 @@ module Carson
 				merge_choice = prompt_merge_method
 				choices[ "govern.merge.method" ] = merge_choice unless merge_choice.nil?
 
-				canonical_choice = prompt_canonical_template
-				choices[ "template.canonical" ] = canonical_choice unless canonical_choice.nil?
+				canonical_choice = prompt_canonical_lint_policy
+				choices[ "lint.canonical" ] = canonical_choice unless canonical_choice.nil?
 
 				write_setup_config( choices: choices )
 			end
@@ -157,15 +157,15 @@ module Carson
 				prompt_choice( options: options, default: default_index )
 			end
 
-			def prompt_canonical_template
+			def prompt_canonical_lint_policy
 				puts_line ""
-				puts_line "Canonical template directory"
-				current = config.template_canonical
+				puts_line "Canonical lint policy directory"
+				current = config.lint_canonical
 				if current && !current.empty?
 					puts_line "  Currently set to: #{current}"
 					puts_line "  Leave blank to keep current value."
 				else
-					puts_line "  A directory of .github/ files to sync across governed repos."
+					puts_line "  A directory of canonical lint-policy files to sync across governed repos."
 					puts_line "  Leave blank to skip for now."
 				end
 				prompt_custom_value( label: "Path" )
@@ -327,6 +327,7 @@ module Carson
 
 				existing_data = load_existing_config( path: config_path )
 				merged = Config.deep_merge( base: existing_data, overlay: config_data )
+				remove_deprecated_template_canonical!( data: merged ) if config_data.dig( "lint", "canonical" )
 
 				FileUtils.mkdir_p( File.dirname( config_path ) )
 				File.write( config_path, JSON.pretty_generate( merged ) )
@@ -361,6 +362,14 @@ module Carson
 				{}
 			end
 
+			def remove_deprecated_template_canonical!( data: )
+				template_hash = data[ "template" ]
+				return unless template_hash.is_a?( Hash )
+
+				template_hash.delete( "canonical" )
+				data.delete( "template" ) if template_hash.empty?
+			end
+
 			def reload_config_after_setup!
 				@config = Config.load( repo_root: repo_root )
 			end

data/lib/carson/runtime/status.rb

@@ -53,7 +53,7 @@ module Carson
 				repos.each do |repo_path|
 					repo_name = File.basename( repo_path )
 					unless Dir.exist?( repo_path )
-						puts_line "#{repo_name}: MISSING"
+						puts_line "#{repo_name}: not found"
 						next
 					end
 
@@ -61,7 +61,7 @@ module Carson
 						scoped_runtime = build_scoped_runtime( repo_path: repo_path )
 						data = scoped_runtime.send( :gather_status )
 						branch = data.fetch( :branch )
-						dirty = branch.fetch( :dirty ) ? " (dirty)" : ""
+						dirty = format_dirty_marker( branch: branch )
 						worktrees = data.fetch( :worktrees )
 						gov = data.fetch( :governance )
 						parts = []
@@ -74,14 +74,16 @@ module Carson
 						repo_pending = status_pending_for_repo( all_pending: all_pending, repo_path: repo_path )
 						repo_pending.each { |description| puts_line "  pending: #{description}" }
 					rescue StandardError => exception
-						puts_line "#{repo_name}: FAIL (#{exception.message})"
+						puts_line "#{repo_name}: could not read (#{exception.message})"
 					end
 				end
 
 				EXIT_OK
 			end
 
+		# rubocop:disable Layout/AccessModifierIndentation -- tab-width calculation produces unfixable mixed tabs+spaces
 		private
+		# rubocop:enable Layout/AccessModifierIndentation
 
 			# Returns an array of human-readable pending descriptions for a repo.
 			def status_pending_for_repo( all_pending:, repo_path: )
@@ -119,10 +121,10 @@ module Carson
 			# Branch name, clean/dirty state, sync status with remote.
 			def gather_branch_info
 				branch = current_branch
-				dirty = working_tree_dirty?
+				dirty_reason = dirty_worktree_reason
 				sync = remote_sync_status( branch: branch )
 
-				{ name: branch, dirty: dirty, sync: sync }
+				{ name: branch, dirty: !dirty_reason.nil?, dirty_reason: dirty_reason, sync: sync }
 			end
 
 			# Returns true when the working tree has uncommitted changes.
@@ -132,6 +134,17 @@ module Carson
 				!stdout.strip.empty?
 			end
 
+			def dirty_worktree_reason
+				return nil unless working_tree_dirty?
+				return "main_worktree" if main_worktree_context?
+
+				"working_tree"
+			end
+
+			def main_worktree_context?
+				realpath_safe( repo_root ) == realpath_safe( main_worktree_root )
+			end
+
 			# Compares local branch against its remote tracking ref.
 			# Returns :in_sync, :ahead, :behind, :diverged, or :no_remote.
 			def remote_sync_status( branch: )
@@ -162,11 +175,11 @@ module Carson
 				# Filter output the main worktree (the repository root itself).
 				# Use realpath for comparison — git returns canonical paths that may differ from repo_root.
 				canonical_root = realpath_safe( repo_root )
-				entries.reject { it.fetch( :path ) == canonical_root }.map do |worktree|
+				entries.reject { it.path == canonical_root }.map do |worktree|
 					{
-						path: worktree.fetch( :path ),
-						name: File.basename( worktree.fetch( :path ) ),
-						branch: worktree.fetch( :branch, nil )
+						path: worktree.path,
+						name: File.basename( worktree.path ),
+						branch: worktree.branch
 					}
 				end
 			end
@@ -243,9 +256,12 @@ module Carson
 
 				# Branch
 				branch = data.fetch( :branch )
-				dirty_marker = branch.fetch( :dirty ) ? " (dirty)" : ""
+				dirty_marker = format_dirty_marker( branch: branch )
 				sync_marker = format_sync( sync: branch.fetch( :sync ) )
 				puts_line "Branch: #{branch.fetch( :name )}#{dirty_marker}#{sync_marker}"
+				if branch.fetch( :dirty_reason, nil ) == "main_worktree"
+					puts_line "Governance: main working tree has uncommitted changes — create a worktree with `carson worktree create <name>`."
+				end
 
 				# Worktrees
 				worktrees = data.fetch( :worktrees )
@@ -299,8 +315,15 @@ module Carson
 				else ""
 				end
 			end
-		end
 
-		include Status
+			def format_dirty_marker( branch: )
+				return "" unless branch.fetch( :dirty )
+				return " (dirty main worktree)" if branch.fetch( :dirty_reason, nil ) == "main_worktree"
+
+				" (dirty)"
+			end
+			end
+
+			include Status
 	end
 end

data/lib/carson/runtime.rb

@@ -310,9 +310,9 @@ module Carson
 			# so only genuinely active worktrees block the operation.
 			scoped_runtime = build_scoped_runtime( repo_path: repo_path )
 			scoped_runtime.sweep_stale_worktrees!
-			worktrees = scoped_runtime.send( :worktree_list )
-			main_root = scoped_runtime.send( :realpath_safe, repo_path )
-			active = worktrees.reject { |worktree| worktree.fetch( :path ) == main_root }
+			worktrees = scoped_runtime.worktree_list
+			main_root = scoped_runtime.realpath_safe( repo_path )
+			active = worktrees.reject { |worktree| worktree.path == main_root }
 			if active.any?
 				reasons << "#{active.count} active worktree#{active.count == 1 ? '' : 's'}"
 			end
@@ -346,3 +346,15 @@ require_relative "runtime/govern"
 require_relative "runtime/setup"
 require_relative "runtime/status"
 require_relative "runtime/deliver"
+
+# Infrastructure interface for domain objects.
+# Carson::Worktree and future domain objects call these methods
+# on a runtime reference — the way ActiveRecord models use a connection.
+# Defined private for internal use, exposed here for domain object access.
+module Carson
+	class Runtime
+		public :config, :output, :verbose?, :puts_verbose, :puts_line,
+			:git_run, :git_capture!, :main_worktree_root, :realpath_safe,
+			:block_if_outsider_fingerprints!, :branch_absorbed_into_main?
+	end
+end