carson 2.24.0 → 2.26.0

data/lib/carson/config.rb

@@ -7,16 +7,14 @@ module Carson
 	# Config is built-in only for outsider mode; host repositories do not carry Carson config files.
 	class Config
 		attr_accessor :git_remote
-		attr_reader :main_branch, :protected_branches, :hooks_base_path, :required_hooks,
-			:template_managed_files, :template_superseded_files, :template_canonical,
-			:lint_policy_source,
+		attr_reader :main_branch, :protected_branches, :hooks_path, :managed_hooks,
+			:template_managed_files, :template_canonical,
 			:review_wait_seconds, :review_poll_seconds, :review_max_polls, :review_sweep_window_days,
-			:review_sweep_states, :review_disposition_prefix, :review_risk_keywords,
+			:review_sweep_states, :review_disposition, :review_risk_keywords,
 			:review_tracking_issue_title, :review_tracking_issue_label, :review_bot_usernames,
-			:ruby_indentation,
 			:audit_advisory_check_names,
 			:workflow_style,
-			:govern_repos, :govern_merge_authority, :govern_merge_method,
+			:govern_repos, :govern_auto_merge, :govern_merge_method,
 			:govern_agent_provider, :govern_dispatch_state_path,
 			:govern_check_wait
 
@@ -35,17 +33,13 @@ module Carson
 					"protected_branches" => [ "main", "master" ]
 				},
 				"hooks" => {
-					"base_path" => "~/.carson/hooks",
-					"required_hooks" => [ "pre-commit", "prepare-commit-msg", "pre-merge-commit", "pre-push" ]
+					"path" => "~/.carson/hooks",
+					"managed" => [ "pre-commit", "prepare-commit-msg", "pre-merge-commit", "pre-push" ]
 				},
 				"template" => {
 					"managed_files" => [ ".github/carson.md", ".github/copilot-instructions.md", ".github/CLAUDE.md", ".github/AGENTS.md", ".github/pull_request_template.md" ],
-					"superseded_files" => [ ".github/carson-instructions.md", ".github/workflows/carson-lint.yml", ".github/.mega-linter.yml" ],
 					"canonical" => nil
 				},
-				"lint" => {
-					"policy_source" => "wanghailei/lint.git"
-				},
 				"workflow" => {
 					"style" => "branch"
 				},
@@ -54,7 +48,7 @@ module Carson
 					"wait_seconds" => 10,
 					"poll_seconds" => 15,
 					"max_polls" => 20,
-					"required_disposition_prefix" => "Disposition:",
+					"disposition" => "Disposition:",
 					"risk_keywords" => [ "bug", "security", "incorrect", "block", "fail", "regression" ],
 					"sweep" => {
 						"window_days" => 3,
@@ -70,10 +64,8 @@ module Carson
 				},
 				"govern" => {
 					"repos" => [],
-					"merge" => {
-						"authority" => true,
-						"method" => "squash"
-					},
+					"auto_merge" => true,
+					"merge_method" => "squash",
 					"agent" => {
 						"provider" => "auto",
 						"codex" => {},
@@ -81,11 +73,8 @@ module Carson
 					},
 					"dispatch_state_path" => "~/.carson/govern/dispatch_state.json",
 					"check_wait" => 30
-				},
-				"style" => {
-					"ruby_indentation" => "tabs"
-				}
 				}
+			}
 			end
 
 		def self.load_global_config_data( repo_root: )
@@ -138,8 +127,8 @@ module Carson
 		def self.apply_env_overrides( data: )
 			copy = deep_dup_value( value: data )
 			hooks = fetch_hash_section( data: copy, key: "hooks" )
-			hooks_path = ENV.fetch( "CARSON_HOOKS_BASE_PATH", "" ).to_s.strip
-			hooks[ "base_path" ] = hooks_path unless hooks_path.empty?
+			hooks_path = ENV.fetch( "CARSON_HOOKS_PATH", "" ).to_s.strip
+			hooks[ "path" ] = hooks_path unless hooks_path.empty?
 			workflow = fetch_hash_section( data: copy, key: "workflow" )
 			workflow_style = ENV.fetch( "CARSON_WORKFLOW_STYLE", "" ).to_s.strip
 			workflow[ "style" ] = workflow_style unless workflow_style.empty?
@@ -147,8 +136,8 @@ module Carson
 			review[ "wait_seconds" ] = env_integer( key: "CARSON_REVIEW_WAIT_SECONDS", fallback: review.fetch( "wait_seconds" ) )
 			review[ "poll_seconds" ] = env_integer( key: "CARSON_REVIEW_POLL_SECONDS", fallback: review.fetch( "poll_seconds" ) )
 			review[ "max_polls" ] = env_integer( key: "CARSON_REVIEW_MAX_POLLS", fallback: review.fetch( "max_polls" ) )
-			disposition_prefix = ENV.fetch( "CARSON_REVIEW_DISPOSITION_PREFIX", "" ).to_s.strip
-			review[ "required_disposition_prefix" ] = disposition_prefix unless disposition_prefix.empty?
+			disposition = ENV.fetch( "CARSON_REVIEW_DISPOSITION", "" ).to_s.strip
+			review[ "disposition" ] = disposition unless disposition.empty?
 			sweep = fetch_hash_section( data: review, key: "sweep" )
 			sweep[ "window_days" ] = env_integer( key: "CARSON_REVIEW_SWEEP_WINDOW_DAYS", fallback: sweep.fetch( "window_days" ) )
 			states = env_string_array( key: "CARSON_REVIEW_SWEEP_STATES" )
@@ -158,20 +147,13 @@ module Carson
 			audit = fetch_hash_section( data: copy, key: "audit" )
 			advisory_names = env_string_array( key: "CARSON_AUDIT_ADVISORY_CHECK_NAMES" )
 			audit[ "advisory_check_names" ] = advisory_names unless advisory_names.empty?
-			lint = fetch_hash_section( data: copy, key: "lint" )
-			lint_policy_source_env = ENV.fetch( "CARSON_LINT_POLICY_SOURCE", "" ).to_s.strip
-			lint[ "policy_source" ] = lint_policy_source_env unless lint_policy_source_env.empty?
-			style = fetch_hash_section( data: copy, key: "style" )
-			ruby_indentation = ENV.fetch( "CARSON_RUBY_INDENTATION", "" ).to_s.strip
-			style[ "ruby_indentation" ] = ruby_indentation unless ruby_indentation.empty?
 			govern = fetch_hash_section( data: copy, key: "govern" )
 			govern_repos = env_string_array( key: "CARSON_GOVERN_REPOS" )
 			govern[ "repos" ] = govern_repos unless govern_repos.empty?
-			merge = fetch_hash_section( data: govern, key: "merge" )
-			govern_authority = ENV.fetch( "CARSON_GOVERN_MERGE_AUTHORITY", "" ).to_s.strip
-			merge[ "authority" ] = ( govern_authority == "true" ) unless govern_authority.empty?
+			govern_auto_merge = ENV.fetch( "CARSON_GOVERN_AUTO_MERGE", "" ).to_s.strip
+			govern[ "auto_merge" ] = ( govern_auto_merge == "true" ) unless govern_auto_merge.empty?
 			govern_method = ENV.fetch( "CARSON_GOVERN_MERGE_METHOD", "" ).to_s.strip
-			merge[ "method" ] = govern_method unless govern_method.empty?
+			govern[ "merge_method" ] = govern_method unless govern_method.empty?
 			agent = fetch_hash_section( data: govern, key: "agent" )
 			govern_provider = ENV.fetch( "CARSON_GOVERN_AGENT_PROVIDER", "" ).to_s.strip
 			agent[ "provider" ] = govern_provider unless govern_provider.empty?
@@ -203,15 +185,12 @@ module Carson
 			@main_branch = fetch_string( hash: fetch_hash( hash: data, key: "git" ), key: "main_branch" )
 			@protected_branches = fetch_string_array( hash: fetch_hash( hash: data, key: "git" ), key: "protected_branches" )
 
-			@hooks_base_path = fetch_string( hash: fetch_hash( hash: data, key: "hooks" ), key: "base_path" )
-			@required_hooks = fetch_string_array( hash: fetch_hash( hash: data, key: "hooks" ), key: "required_hooks" )
+			@hooks_path = fetch_string( hash: fetch_hash( hash: data, key: "hooks" ), key: "path" )
+			@managed_hooks = fetch_string_array( hash: fetch_hash( hash: data, key: "hooks" ), key: "managed" )
 
 			@template_managed_files = fetch_string_array( hash: fetch_hash( hash: data, key: "template" ), key: "managed_files" )
-			@template_superseded_files = fetch_optional_string_array( hash: fetch_hash( hash: data, key: "template" ), key: "superseded_files" )
 			@template_canonical = fetch_optional_path( hash: fetch_hash( hash: data, key: "template" ), key: "canonical" )
 			resolve_canonical_files!
-			lint_hash = fetch_hash( hash: data, key: "lint" )
-			@lint_policy_source = lint_hash.fetch( "policy_source", "" ).to_s.strip
 
 			workflow_hash = fetch_hash( hash: data, key: "workflow" )
 			@workflow_style = fetch_string( hash: workflow_hash, key: "style" ).downcase
@@ -220,7 +199,7 @@ module Carson
 			@review_wait_seconds = fetch_non_negative_integer( hash: review_hash, key: "wait_seconds" )
 			@review_poll_seconds = fetch_non_negative_integer( hash: review_hash, key: "poll_seconds" )
 			@review_max_polls = fetch_positive_integer( hash: review_hash, key: "max_polls" )
-			@review_disposition_prefix = fetch_string( hash: review_hash, key: "required_disposition_prefix" )
+			@review_disposition = fetch_string( hash: review_hash, key: "disposition" )
 			@review_risk_keywords = fetch_string_array( hash: review_hash, key: "risk_keywords" )
 			sweep_hash = fetch_hash( hash: review_hash, key: "sweep" )
 			@review_sweep_window_days = fetch_positive_integer( hash: sweep_hash, key: "window_days" )
@@ -231,14 +210,11 @@ module Carson
 			@review_bot_usernames = fetch_optional_string_array( hash: review_hash, key: "bot_usernames" )
 			audit_hash = fetch_hash( hash: data, key: "audit" )
 			@audit_advisory_check_names = fetch_optional_string_array( hash: audit_hash, key: "advisory_check_names" )
-			style_hash = fetch_hash( hash: data, key: "style" )
-			@ruby_indentation = fetch_string( hash: style_hash, key: "ruby_indentation" ).downcase
 
 			govern_hash = fetch_hash( hash: data, key: "govern" )
 			@govern_repos = fetch_optional_string_array( hash: govern_hash, key: "repos" ).map { |p| safe_expand_path( p ) }
-			govern_merge_hash = fetch_hash( hash: govern_hash, key: "merge" )
-			@govern_merge_authority = fetch_optional_boolean( hash: govern_merge_hash, key: "authority", default: true, key_path: "govern.merge.authority" )
-			@govern_merge_method = fetch_string( hash: govern_merge_hash, key: "method" ).downcase
+			@govern_auto_merge = fetch_optional_boolean( hash: govern_hash, key: "auto_merge", default: true, key_path: "govern.auto_merge" )
+			@govern_merge_method = fetch_string( hash: govern_hash, key: "merge_method" ).downcase
 			govern_agent_hash = fetch_hash( hash: govern_hash, key: "agent" )
 			@govern_agent_provider = fetch_string( hash: govern_agent_hash, key: "provider" ).downcase
 			dispatch_path = govern_hash.fetch( "dispatch_state_path" ).to_s
@@ -254,16 +230,15 @@ module Carson
 				raise ConfigError, "git.remote cannot be empty" if git_remote.empty?
 				raise ConfigError, "git.main_branch cannot be empty" if main_branch.empty?
 				raise ConfigError, "git.protected_branches must include #{main_branch}" unless protected_branches.include?( main_branch )
-				raise ConfigError, "hooks.base_path cannot be empty" if hooks_base_path.empty?
-				raise ConfigError, "hooks.required_hooks cannot be empty" if required_hooks.empty?
-				raise ConfigError, "review.required_disposition_prefix cannot be empty" if review_disposition_prefix.empty?
+				raise ConfigError, "hooks.path cannot be empty" if hooks_path.empty?
+				raise ConfigError, "hooks.managed cannot be empty" if managed_hooks.empty?
+				raise ConfigError, "review.disposition cannot be empty" if review_disposition.empty?
 				raise ConfigError, "review.risk_keywords cannot be empty" if review_risk_keywords.empty?
 				raise ConfigError, "review.sweep.states must contain one or both of open, closed" if ( review_sweep_states - [ "open", "closed" ] ).any? || review_sweep_states.empty?
 				raise ConfigError, "review.sweep.states cannot contain duplicates" unless review_sweep_states.uniq.length == review_sweep_states.length
 				raise ConfigError, "review.tracking_issue.title cannot be empty" if review_tracking_issue_title.empty?
 				raise ConfigError, "review.tracking_issue.label cannot be empty" if review_tracking_issue_label.empty?
 				raise ConfigError, "workflow.style must be one of trunk, branch" unless [ "trunk", "branch" ].include?( workflow_style )
-				raise ConfigError, "style.ruby_indentation must be one of tabs, spaces, either" unless [ "tabs", "spaces", "either" ].include?( ruby_indentation )
 				raise ConfigError, "govern.merge.method must be one of merge, squash, rebase" unless [ "merge", "squash", "rebase" ].include?( govern_merge_method )
 				raise ConfigError, "govern.agent.provider must be one of auto, codex, claude" unless [ "auto", "codex", "claude" ].include?( govern_agent_provider )
 			end

data/lib/carson/runtime/audit.rb

@@ -24,7 +24,7 @@ module Carson
 				hooks_ok = hooks_health_report
 				unless hooks_ok
 					audit_state = "block"
-					audit_concise_problems << "Hooks: mismatch — run carson prepare."
+					audit_concise_problems << "Hooks: mismatch — run carson refresh."
 				end
 				puts_verbose ""
 				puts_verbose "[Main Sync Status]"
@@ -75,7 +75,6 @@ module Carson
 				puts_verbose ""
 				puts_verbose "[Default Branch CI Baseline (gh)]"
 				default_branch_baseline = default_branch_ci_baseline_report
-				audit_state = "block" if default_branch_baseline.fetch( :status ) == "block"
 				audit_state = "attention" if audit_state == "ok" && default_branch_baseline.fetch( :status ) != "ok"
 				baseline_st = default_branch_baseline.fetch( :status )
 				if baseline_st == "block"
@@ -83,7 +82,7 @@ module Carson
 					parts << "#{default_branch_baseline.fetch( :failing_count )} failing" if default_branch_baseline.fetch( :failing_count ).positive?
 					parts << "#{default_branch_baseline.fetch( :pending_count )} pending" if default_branch_baseline.fetch( :pending_count ).positive?
 					parts << "no check-runs for active workflows" if default_branch_baseline.fetch( :no_check_evidence )
-					audit_concise_problems << "Baseline (#{default_branch_baseline.fetch( :default_branch, config.main_branch )}): #{parts.join( ', ' )} — merge blocked."
+					audit_concise_problems << "Baseline (#{default_branch_baseline.fetch( :default_branch, config.main_branch )}): #{parts.join( ', ' )} — fix before merge."
 				elsif baseline_st == "attention"
 					parts = []
 					parts << "#{default_branch_baseline.fetch( :advisory_failing_count )} advisory failing" if default_branch_baseline.fetch( :advisory_failing_count ).positive?
@@ -115,64 +114,6 @@ module Carson
 				audit_state == "block" ? EXIT_BLOCK : EXIT_OK
 			end
 
-			# Thin focused command: show required-check status for the current branch's open PR.
-			# Always exits 0 for pending or passing so callers never see a false "Error: Exit code 8".
-			def check!
-				unless head_exists?
-					puts_line "Checks: no commits yet."
-					return EXIT_OK
-				end
-				unless gh_available?
-					puts_line "Checks: gh CLI not available."
-					return EXIT_ERROR
-				end
-
-				pr_stdout, pr_stderr, pr_success, = gh_run(
-					"pr", "view", current_branch,
-					"--json", "number,title,url"
-				)
-				unless pr_success
-					error_text = gh_error_text( stdout_text: pr_stdout, stderr_text: pr_stderr, fallback: "no open PR for branch #{current_branch}" )
-					puts_line "Checks: #{error_text}."
-					return EXIT_ERROR
-				end
-				pr_data = JSON.parse( pr_stdout )
-				pr_number = pr_data[ "number" ].to_s
-
-				checks_stdout, checks_stderr, checks_success, checks_exit = gh_run(
-					"pr", "checks", pr_number, "--required", "--json", "name,state,bucket,workflow,link"
-				)
-				if checks_stdout.to_s.strip.empty?
-					error_text = gh_error_text( stdout_text: checks_stdout, stderr_text: checks_stderr, fallback: "required checks unavailable" )
-					puts_line "Checks: #{error_text}."
-					return EXIT_ERROR
-				end
-
-				checks_data = JSON.parse( checks_stdout )
-				pending = checks_data.select { |e| e[ "bucket" ].to_s == "pending" }
-				failing = checks_data.select { |e| check_entry_failing?( entry: e ) }
-				total = checks_data.count
-				# gh exits 8 when required checks are still pending (not a failure).
-				is_pending = !checks_success && checks_exit == 8
-
-				if failing.any?
-					puts_line "Checks: FAIL (#{failing.count} of #{total} failing)."
-					normalise_check_entries( entries: failing ).each { |e| puts_line "  #{e.fetch( :workflow )} / #{e.fetch( :name )} #{e.fetch( :link )}".strip }
-					return EXIT_BLOCK
-				end
-
-				if is_pending || pending.any?
-					puts_line "Checks: pending (#{total - pending.count} of #{total} complete)."
-					return EXIT_OK
-				end
-
-				puts_line "Checks: all passing (#{total} required)."
-				EXIT_OK
-			rescue JSON::ParserError => e
-				puts_line "Checks: invalid gh response (#{e.message})."
-				EXIT_ERROR
-			end
-
 		private
 			def pr_and_check_report
 				report = {

data/lib/carson/runtime/govern.rb

@@ -81,18 +81,6 @@ module Carson
 				EXIT_OK
 			end
 
-			# Standalone housekeep: sync + prune.
-			def housekeep!
-				puts_verbose ""
-				puts_verbose "[Housekeep]"
-				sync_status = sync!
-				if sync_status != EXIT_OK
-					puts_line "housekeep: sync returned #{sync_status}; skipping prune."
-					return sync_status
-				end
-				prune!
-			end
-
 		private
 
 			# Resolves the list of repo paths to govern from config.
@@ -209,10 +197,6 @@ module Carson
 					return [ TRIAGE_REVIEW_BLOCKED, "changes requested by reviewer" ]
 				end
 
-				# Run audit and review gate checks for deeper analysis
-				audit_status, audit_detail = check_audit_status( pr: pr, repo_path: repo_path )
-				return [ TRIAGE_NEEDS_ATTENTION, audit_detail ] unless audit_status == :pass
-
 				review_status, review_detail = check_review_gate_status( pr: pr, repo_path: repo_path )
 				return [ TRIAGE_REVIEW_BLOCKED, review_detail ] unless review_status == :pass
 
@@ -245,20 +229,6 @@ module Carson
 				[ "PENDING", "QUEUED", "IN_PROGRESS", "WAITING", "REQUESTED" ].include?( state.upcase )
 			end
 
-			# Checks if the PR's branch is available locally and defers audit. Returns [:pass/:fail, detail].
-			def check_audit_status( pr:, repo_path: )
-				branch = pr[ "headRefName" ].to_s
-				stdout_text, stderr_text, status = Open3.capture3(
-					"git", "rev-parse", "--verify", "refs/heads/#{branch}",
-					chdir: repo_path
-				)
-				unless status.success?
-					return [ :pass, "branch not local; skipping audit" ]
-				end
-
-				[ :pass, "audit deferred to merge gate" ]
-			end
-
 			# Checks review gate status. Returns [:pass/:fail, detail].
 			def check_review_gate_status( pr:, repo_path: )
 				review_decision = pr[ "reviewDecision" ].to_s.upcase
@@ -308,7 +278,7 @@ module Carson
 
 			# Merges a PR that has passed all gates.
 			def merge_if_ready!( pr:, repo_path: )
-				unless config.govern_merge_authority
+				unless config.govern_auto_merge
 					puts_line "    merge authority disabled; skipping merge"
 					return
 				end
@@ -373,14 +343,15 @@ module Carson
 				puts_line "    agent result: #{result.status} — #{result.summary.to_s[0, 120]}"
 			end
 
-			# Runs housekeep in the given repo after a successful merge.
+			# Runs sync + prune in the given repo after a successful merge.
 			def housekeep_repo!( repo_path: )
-				if repo_path == self.repo_root
-					housekeep!
+				rt = if repo_path == self.repo_root
+					self
 				else
-					rt = Runtime.new( repo_root: repo_path, tool_root: tool_root, out: out, err: err )
-					rt.housekeep!
+					Runtime.new( repo_root: repo_path, tool_root: tool_root, out: out, err: err )
 				end
+				sync_status = rt.sync!
+				rt.prune! if sync_status == EXIT_OK
 			end
 
 			# Selects which agent provider to use based on config and availability.

data/lib/carson/runtime/local/hooks.rb

@@ -0,0 +1,142 @@
+module Carson
+	class Runtime
+		module Local
+		private
+
+			# Installs required hook files and enforces repository hook path.
+			def prepare!
+				fingerprint_status = block_if_outsider_fingerprints!
+				return fingerprint_status unless fingerprint_status.nil?
+
+				FileUtils.mkdir_p( hooks_dir )
+				missing_templates = config.managed_hooks.reject { |name| File.file?( hook_template_path( hook_name: name ) ) }
+				unless missing_templates.empty?
+					puts_line "BLOCK: missing hook templates in Carson: #{missing_templates.join( ', ' )}."
+					return EXIT_BLOCK
+				end
+
+				symlinked = symlink_hook_files
+				unless symlinked.empty?
+					puts_line "BLOCK: symlink hook files are not allowed: #{symlinked.join( ', ' )}."
+					return EXIT_BLOCK
+				end
+
+				config.managed_hooks.each do |hook_name|
+					source_path = hook_template_path( hook_name: hook_name )
+					target_path = File.join( hooks_dir, hook_name )
+					FileUtils.cp( source_path, target_path )
+					FileUtils.chmod( 0o755, target_path )
+					puts_verbose "hook_written: #{relative_path( target_path )}"
+				end
+				git_system!( "config", "core.hooksPath", hooks_dir )
+				File.write( File.join( hooks_dir, "workflow_style" ), config.workflow_style )
+				puts_verbose "configured_hooks_path: #{hooks_dir}"
+				puts_line "Hooks installed (#{config.managed_hooks.count} hooks)."
+				EXIT_OK
+			end
+
+			# Canonical hook template location inside Carson repository.
+			def hook_template_path( hook_name: )
+				File.join( tool_root, "hooks", hook_name )
+			end
+
+			# Reports full hook health and can enforce stricter action messaging in `check`.
+			def hooks_health_report( strict: false )
+				configured = configured_hooks_path
+				expected = hooks_dir
+				hooks_path_ok = print_hooks_path_status( configured: configured, expected: expected )
+				print_required_hook_status
+				hooks_integrity = hook_integrity_state
+				hooks_ok = hooks_integrity_ok?( hooks_integrity: hooks_integrity )
+				print_hook_action(
+					strict: strict,
+					hooks_ok: hooks_path_ok && hooks_ok,
+					hooks_path_ok: hooks_path_ok,
+					configured: configured,
+					expected: expected
+				)
+				hooks_path_ok && hooks_ok
+			end
+
+			def print_hooks_path_status( configured:, expected: )
+				configured_abs = configured.nil? ? nil : File.expand_path( configured )
+				hooks_path_ok = configured_abs == expected
+				puts_verbose "hooks_path: #{configured || '(unset)'}"
+				puts_verbose "hooks_path_expected: #{expected}"
+				puts_verbose( hooks_path_ok ? "hooks_path_status: ok" : "hooks_path_status: attention" )
+				hooks_path_ok
+			end
+
+			def print_required_hook_status
+				required_hook_paths.each do |path|
+					exists = File.file?( path )
+					symlink = File.symlink?( path )
+					executable = exists && !symlink && File.executable?( path )
+					puts_verbose "hook_file: #{relative_path( path )} exists=#{exists} symlink=#{symlink} executable=#{executable}"
+				end
+			end
+
+			def hook_integrity_state
+				{
+					missing: missing_hook_files,
+					non_executable: non_executable_hook_files,
+					symlinked: symlink_hook_files
+				}
+			end
+
+			def hooks_integrity_ok?( hooks_integrity: )
+				missing_ok = hooks_integrity.fetch( :missing ).empty?
+				non_executable_ok = hooks_integrity.fetch( :non_executable ).empty?
+				symlinked_ok = hooks_integrity.fetch( :symlinked ).empty?
+				missing_ok && non_executable_ok && symlinked_ok
+			end
+
+			def print_hook_action( strict:, hooks_ok:, hooks_path_ok:, configured:, expected: )
+				return if hooks_ok
+
+				if strict && !hooks_path_ok
+					configured_text = configured.to_s.strip
+					if configured_text.empty?
+						puts_verbose "ACTION: hooks path is unset (expected=#{expected})."
+					else
+						puts_verbose "ACTION: hooks path mismatch (configured=#{configured_text}, expected=#{expected})."
+					end
+				end
+				message = strict ? "ACTION: run carson refresh to align hooks with Carson #{Carson::VERSION}." : "ACTION: run carson refresh to enforce local main protections."
+				puts_verbose message
+			end
+
+			# Reads configured core.hooksPath and normalises empty values to nil.
+			def configured_hooks_path
+				stdout_text, = git_capture_soft( "config", "--get", "core.hooksPath" )
+				value = stdout_text.to_s.strip
+				value.empty? ? nil : value
+			end
+
+			# Fully-qualified required hook file locations in the target repository.
+			def required_hook_paths
+				config.managed_hooks.map { |name| File.join( hooks_dir, name ) }
+			end
+
+			# Missing required hook files.
+			def missing_hook_files
+				required_hook_paths.reject { |path| File.file?( path ) }.map { |path| relative_path( path ) }
+			end
+
+			# Required hook files that exist but are not executable.
+			def non_executable_hook_files
+				required_hook_paths.select { |path| File.file?( path ) && !File.executable?( path ) }.map { |path| relative_path( path ) }
+			end
+
+			# Symlink hooks are disallowed to prevent bypassing managed hook content.
+			def symlink_hook_files
+				required_hook_paths.select { |path| File.symlink?( path ) }.map { |path| relative_path( path ) }
+			end
+
+			# Local directory where managed hooks are installed.
+			def hooks_dir
+				File.expand_path( File.join( config.hooks_path, Carson::VERSION ) )
+			end
+		end
+	end
+end