carson 3.21.1 → 3.22.1

data/lib/carson/cli.rb

@@ -4,6 +4,8 @@ require "optparse"
 module Carson
 	class CLI
 		def self.start( arguments:, repo_root:, tool_root:, output:, error: )
+			ensure_global_artefacts!( tool_root: tool_root )
+
 			parsed = parse_args( arguments: arguments, output: output, error: error )
 			command = parsed.fetch( :command )
 			return Runtime::EXIT_OK if command == :help
@@ -22,7 +24,7 @@ module Carson
 			target_repo_root = parsed.fetch( :repo_root, nil )
 			target_repo_root = repo_root if target_repo_root.to_s.strip.empty?
 			unless Dir.exist?( target_repo_root )
-				error.puts "#{BADGE} ERROR: repository path does not exist: #{target_repo_root}"
+				error.puts "#{BADGE} Repository path not found: #{target_repo_root}"
 				return Runtime::EXIT_ERROR
 			end
 
@@ -30,10 +32,10 @@ module Carson
 			runtime = Runtime.new( repo_root: target_repo_root, tool_root: tool_root, output: output, error: error, verbose: verbose )
 			dispatch( parsed: parsed, runtime: runtime )
 		rescue ConfigError => exception
-			error.puts "#{BADGE} CONFIG ERROR: #{exception.message}"
+			error.puts "#{BADGE} Configuration problem: #{exception.message}"
 			Runtime::EXIT_ERROR
 		rescue StandardError => exception
-			error.puts "#{BADGE} ERROR: #{exception.message}"
+			error.puts "#{BADGE} #{exception.message}"
 			Runtime::EXIT_ERROR
 		end
 
@@ -147,7 +149,7 @@ module Carson
 				parser.on( "--main-branch NAME", "Main branch name" ) { |value| options[ "git.main_branch" ] = value }
 				parser.on( "--workflow STYLE", "Workflow style (branch or trunk)" ) { |value| options[ "workflow.style" ] = value }
 				parser.on( "--merge METHOD", "Merge method (squash, rebase, or merge)" ) { |value| options[ "govern.merge.method" ] = value }
-				parser.on( "--canonical PATH", "Canonical template directory path" ) { |value| options[ "template.canonical" ] = value }
+				parser.on( "--canonical PATH", "Canonical lint policy directory path" ) { |value| options[ "lint.canonical" ] = value }
 				parser.separator ""
 				parser.separator "Examples:"
 				parser.separator "    carson setup                            Auto-detect and write config"
@@ -163,6 +165,7 @@ module Carson
 			{ command: "setup", cli_choices: options }
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts setup_parser
 			{ command: :invalid }
 		end
 
@@ -193,6 +196,7 @@ module Carson
 			}
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts onboard_parser
 			{ command: :invalid }
 		end
 
@@ -220,6 +224,7 @@ module Carson
 			}
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts offboard_parser
 			{ command: :invalid }
 		end
 
@@ -263,6 +268,7 @@ module Carson
 			}
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts refresh_parser
 			{ command: :invalid }
 		end
 
@@ -290,6 +296,7 @@ module Carson
 			{ command: "prune", json: options[ :json ] }
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts prune_parser
 			{ command: :invalid }
 		end
 
@@ -346,6 +353,7 @@ module Carson
 			end
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts worktree_parser
 			{ command: :invalid }
 		end
 
@@ -376,6 +384,7 @@ module Carson
 			{ command: "review:#{action}" }
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts review_parser
 			{ command: :invalid }
 		end
 
@@ -434,6 +443,7 @@ module Carson
 			{ command: "template:apply", push_prep: options.fetch( :push_prep ) }
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts( apply_parser || template_parser )
 			{ command: :invalid }
 		end
 
@@ -466,6 +476,7 @@ module Carson
 			{ command: "audit", json: options[ :json ] }
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts audit_parser
 			{ command: :invalid }
 		end
 
@@ -497,6 +508,7 @@ module Carson
 			{ command: "sync", json: options[ :json ] }
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts sync_parser
 			{ command: :invalid }
 		end
 
@@ -528,6 +540,7 @@ module Carson
 			{ command: "status", json: options[ :json ] }
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts status_parser
 			{ command: :invalid }
 		end
 
@@ -566,6 +579,7 @@ module Carson
 			}
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts deliver_parser
 			{ command: :invalid }
 		end
 
@@ -594,27 +608,30 @@ module Carson
 			{ command: "repos", json: options[ :json ] }
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts repos_parser
 			{ command: :invalid }
 		end
 
 		# --- housekeep ---
 
 		def self.parse_housekeep_command( arguments:, error: )
-			options = { all: false, json: false }
+			options = { all: false, json: false, dry_run: false }
 			housekeep_parser = OptionParser.new do |parser|
-				parser.banner = "Usage: carson housekeep [REPO] [--all] [--json]"
+				parser.banner = "Usage: carson housekeep [REPO] [--all] [--dry-run] [--json]"
 				parser.separator ""
 				parser.separator "Run housekeeping: sync main, reap dead worktrees, and prune stale branches."
 				parser.separator "Defaults to the current repository."
 				parser.separator ""
 				parser.separator "Options:"
 				parser.on( "--all", "Housekeep all governed repositories" ) { options[ :all ] = true }
+				parser.on( "--dry-run", "Show what would be reaped/deleted without making changes" ) { options[ :dry_run ] = true }
 				parser.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
 				parser.separator ""
 				parser.separator "Examples:"
-				parser.separator "    carson housekeep           Housekeep the current repository"
-				parser.separator "    carson housekeep nexus     Housekeep a named governed repo"
-				parser.separator "    carson housekeep --all     Housekeep all governed repos"
+				parser.separator "    carson housekeep              Housekeep the current repository"
+				parser.separator "    carson housekeep --dry-run    Preview what housekeep would do"
+				parser.separator "    carson housekeep nexus        Housekeep a named governed repo"
+				parser.separator "    carson housekeep --all        Housekeep all governed repos"
 			end
 			housekeep_parser.parse!( arguments )
 
@@ -623,7 +640,7 @@ module Carson
 				return { command: :invalid }
 			end
 
-			return { command: "housekeep:all", json: options[ :json ] } if options[ :all ]
+			return { command: "housekeep:all", json: options[ :json ], dry_run: options[ :dry_run ] } if options[ :all ]
 
 			if arguments.length > 1
 				error.puts "#{BADGE} Too many arguments for housekeep. Use: carson housekeep [repo]"
@@ -631,11 +648,12 @@ module Carson
 			end
 
 			target = arguments.shift
-			return { command: "housekeep:target", target: target, json: options[ :json ] } if target
+			return { command: "housekeep:target", target: target, json: options[ :json ], dry_run: options[ :dry_run ] } if target
 
-			{ command: "housekeep", json: options[ :json ] }
+			{ command: "housekeep", json: options[ :json ], dry_run: options[ :dry_run ] }
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts housekeep_parser
 			{ command: :invalid }
 		end
 
@@ -658,7 +676,7 @@ module Carson
 				parser.on( "--dry-run", "Run all checks but do not merge or dispatch" ) { options[ :dry_run ] = true }
 				parser.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
 				parser.on( "--loop SECONDS", Integer, "Run continuously, sleeping SECONDS between cycles" ) do |seconds|
-					error.puts( "#{BADGE} Error: --loop must be a positive integer" ) || ( return { command: :invalid } ) if seconds < 1
+					error.puts( "#{BADGE} --loop expects a positive integer" ) || ( return { command: :invalid } ) if seconds < 1
 					options[ :loop_seconds ] = seconds
 				end
 				parser.separator ""
@@ -685,6 +703,27 @@ module Carson
 			{ command: :invalid }
 		end
 
+		# --- global artefacts ---
+
+		# Ensures global (non-repo) artefacts are installed at CLI startup.
+		# The command-guard lives at a stable path (~/.carson/hooks/command-guard)
+		# referenced by Claude Code's PreToolUse hook. It must exist regardless of
+		# whether `carson refresh` has been run in any governed repo.
+		def self.ensure_global_artefacts!( tool_root: )
+			source = File.join( tool_root, "hooks", "command-guard" )
+			return unless File.file?( source )
+
+			hooks_base = File.expand_path( "~/.carson/hooks" )
+			target = File.join( hooks_base, "command-guard" )
+			return if File.file?( target ) && FileUtils.identical?( source, target )
+
+			FileUtils.mkdir_p( hooks_base )
+			FileUtils.cp( source, target )
+			FileUtils.chmod( 0o755, target )
+		rescue StandardError
+			# Best-effort — do not block any command if this fails.
+		end
+
 		# --- dispatch ---
 
 		def self.dispatch( parsed:, runtime: )
@@ -734,11 +773,11 @@ module Carson
 			when "repos"
 				runtime.repos!( json_output: parsed.fetch( :json, false ) )
 			when "housekeep"
-				runtime.housekeep!( json_output: parsed.fetch( :json, false ) )
+				runtime.housekeep!( json_output: parsed.fetch( :json, false ), dry_run: parsed.fetch( :dry_run, false ) )
 			when "housekeep:target"
-				runtime.housekeep_target!( target: parsed.fetch( :target ), json_output: parsed.fetch( :json, false ) )
+				runtime.housekeep_target!( target: parsed.fetch( :target ), json_output: parsed.fetch( :json, false ), dry_run: parsed.fetch( :dry_run, false ) )
 			when "housekeep:all"
-				runtime.housekeep_all!( json_output: parsed.fetch( :json, false ) )
+				runtime.housekeep_all!( json_output: parsed.fetch( :json, false ), dry_run: parsed.fetch( :dry_run, false ) )
 			when "govern"
 				runtime.govern!(
 					dry_run: parsed.fetch( :dry_run, false ),

data/lib/carson/config.rb

@@ -7,9 +7,24 @@ module Carson
 
 	# Config is built-in only for outsider mode; host repositories do not carry Carson config files.
 	class Config
+		CANONICAL_GITHUB_DIRECTORIES = %w[actions workflows ISSUE_TEMPLATE DISCUSSION_TEMPLATE linters].freeze
+		CANONICAL_GITHUB_ROOT_FILES = [
+			".mega-linter.yml",
+			"AGENTS.md",
+			"CLAUDE.md",
+			"CODEOWNERS",
+			"FUNDING.yml",
+			"carson.md",
+			"copilot-instructions.md",
+			"dependabot.yml",
+			"funding.yml",
+			"labeler.yml",
+			"pull_request_template.md"
+		].freeze
+
 		attr_accessor :git_remote
 		attr_reader :main_branch, :protected_branches, :hooks_path, :managed_hooks,
-			:template_managed_files, :template_canonical,
+			:template_managed_files, :lint_canonical, :template_canonical,
 			:review_wait_seconds, :review_poll_seconds, :review_max_polls, :review_sweep_window_days,
 			:review_sweep_states, :review_disposition, :review_risk_keywords,
 			:review_tracking_issue_title, :review_tracking_issue_label, :review_bot_usernames,
@@ -38,7 +53,10 @@ module Carson
 					"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" ],
+					"managed_files" => [],
+					"canonical" => nil
+				},
+				"lint" => {
 					"canonical" => nil
 				},
 				"workflow" => {
@@ -66,7 +84,9 @@ module Carson
 				"govern" => {
 					"repos" => [],
 					"auto_merge" => true,
-					"merge_method" => "squash",
+					"merge" => {
+						"method" => "squash"
+					},
 					"agent" => {
 						"provider" => "auto",
 						"codex" => {},
@@ -154,7 +174,10 @@ module Carson
 			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
-			govern[ "merge_method" ] = govern_method unless govern_method.empty?
+			unless govern_method.empty?
+				govern[ "merge" ] ||= {}
+				govern[ "merge" ][ "method" ] = govern_method
+			end
 			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?
@@ -189,8 +212,11 @@ module Carson
 			@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_canonical = fetch_optional_path( hash: fetch_hash( hash: data, key: "template" ), key: "canonical" )
+			template_hash = fetch_hash( hash: data, key: "template" )
+			@template_managed_files = fetch_optional_string_array( hash: template_hash, key: "managed_files" )
+			@lint_canonical = fetch_optional_path( hash: fetch_hash( hash: data, key: "lint" ), key: "canonical" )
+			@lint_canonical ||= fetch_optional_path( hash: template_hash, key: "canonical" )
+			@template_canonical = @lint_canonical
 			resolve_canonical_files!
 
 			workflow_hash = fetch_hash( hash: data, key: "workflow" )
@@ -215,7 +241,8 @@ module Carson
 			govern_hash = fetch_hash( hash: data, key: "govern" )
 			@govern_repos = fetch_optional_string_array( hash: govern_hash, key: "repos" ).map { |path| safe_expand_path( path ) }
 			@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_merge_hash = fetch_hash( hash: govern_hash, key: "merge" )
+			@govern_merge_method = fetch_string( hash: govern_merge_hash, key: "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
@@ -317,18 +344,32 @@ module Carson
 				safe_expand_path( text )
 			end
 
-			# Discovers files in the canonical directory and appends them to managed_files.
-			# Canonical files mirror the .github/ structure and are synced alongside Carson's own governance files.
+			# Discovers files in the canonical lint-policy directory and appends them to managed_files.
+			# Explicit GitHub paths stay under .github/; flat policy files default to .github/linters/.
 			def resolve_canonical_files!
-				return if @template_canonical.nil? || @template_canonical.empty?
-				return unless Dir.exist?( @template_canonical )
+				return if @lint_canonical.nil? || @lint_canonical.empty?
+				return unless Dir.exist?( @lint_canonical )
 
-				Dir.glob( File.join( @template_canonical, "**", "*" ) ).sort.each do |absolute_path|
+				Dir.glob( File.join( @lint_canonical, "**", "*" ), File::FNM_DOTMATCH ).sort.each do |absolute_path|
+					basename = File.basename( absolute_path )
+					next if basename == "." || basename == ".."
 					next unless File.file?( absolute_path )
-					relative = absolute_path.delete_prefix( "#{@template_canonical}/" )
-					managed_path = ".github/#{relative}"
+					relative = absolute_path.delete_prefix( "#{@lint_canonical}/" )
+					managed_path = canonical_managed_path( relative_path: relative )
 					@template_managed_files << managed_path unless @template_managed_files.include?( managed_path )
 				end
 			end
+
+			def canonical_managed_path( relative_path: )
+				raw_relative = relative_path.to_s
+				return ".github/#{raw_relative.delete_prefix( '.github/' )}" if raw_relative.start_with?( ".github/" )
+
+				clean_relative = raw_relative
+				first_segment = clean_relative.split( "/", 2 ).first
+				return ".github/#{clean_relative}" if CANONICAL_GITHUB_DIRECTORIES.include?( first_segment )
+				return ".github/#{clean_relative}" if !clean_relative.include?( "/" ) && CANONICAL_GITHUB_ROOT_FILES.include?( clean_relative )
+
+				".github/linters/#{clean_relative}"
+			end
 	end
 end

data/lib/carson/runtime/audit.rb

@@ -26,6 +26,12 @@ module Carson
 				puts_verbose ""
 				puts_verbose "[Working Tree]"
 				puts_verbose git_capture!( "status", "--short", "--branch" ).strip
+				working_tree = audit_working_tree_report
+				if working_tree.fetch( :status ) == "block"
+					puts_verbose "ACTION: #{working_tree.fetch( :error )}; #{working_tree.fetch( :recovery )}."
+					audit_state = "block"
+					audit_concise_problems << "Working tree: #{working_tree.fetch( :error )} — #{working_tree.fetch( :recovery )}."
+				end
 				puts_verbose ""
 				puts_verbose "[Hooks]"
 				hooks_ok = hooks_health_report
@@ -110,17 +116,17 @@ module Carson
 					end
 					audit_concise_problems << "Baseline (#{default_branch_baseline.fetch( :default_branch, config.main_branch )}): #{parts.join( ', ' )}."
 				end
-				if config.template_canonical.nil? || config.template_canonical.to_s.empty?
+				if config.lint_canonical.nil? || config.lint_canonical.to_s.empty?
 					puts_verbose ""
-					puts_verbose "[Canonical Templates]"
-					puts_verbose "HINT: canonical templates not configured — run carson setup to enable."
+					puts_verbose "[Canonical Lint Policy]"
+					puts_verbose "HINT: lint.canonical not configured — run carson setup to enable."
 				end
-					write_and_print_pr_monitor_report(
-						report: monitor_report.merge(
-							default_branch_baseline: default_branch_baseline,
-							audit_status: audit_state
-						)
+				write_and_print_pr_monitor_report(
+					report: monitor_report.merge(
+						default_branch_baseline: default_branch_baseline,
+						audit_status: audit_state
 					)
+				)
 				exit_code = audit_state == "block" ? EXIT_BLOCK : EXIT_OK
 
 				if json_output
@@ -128,6 +134,7 @@ module Carson
 						command: "audit",
 						status: audit_state,
 						branch: current_branch,
+						working_tree: working_tree,
 						hooks: { status: hooks_status },
 						main_sync: main_sync,
 						pr: monitor_report[ :pr ],
@@ -175,7 +182,7 @@ module Carson
 				repos.each do |repo_path|
 					repo_name = File.basename( repo_path )
 					unless Dir.exist?( repo_path )
-						puts_line "#{repo_name}: FAIL (path not found)"
+						puts_line "#{repo_name}: not found"
 						record_batch_skip( command: "audit", repo_path: repo_path, reason: "path not found" )
 						failed += 1
 						next
@@ -190,15 +197,15 @@ module Carson
 							clear_batch_success( command: "audit", repo_path: repo_path )
 							passed += 1
 						when EXIT_BLOCK
-							puts_line "#{repo_name}: BLOCK" unless verbose?
+							puts_line "#{repo_name}: needs attention" unless verbose?
 							blocked += 1
 						else
-							puts_line "#{repo_name}: FAIL" unless verbose?
+							puts_line "#{repo_name}: could not complete" unless verbose?
 							record_batch_skip( command: "audit", repo_path: repo_path, reason: "audit failed" )
 							failed += 1
 						end
 					rescue StandardError => exception
-						puts_line "#{repo_name}: FAIL (#{exception.message})"
+						puts_line "#{repo_name}: could not complete (#{exception.message})"
 						record_batch_skip( command: "audit", repo_path: repo_path, reason: exception.message )
 						failed += 1
 					end
@@ -207,11 +214,30 @@ module Carson
 				puts_line ""
 				puts_line "Audit all complete: #{passed} ok, #{blocked} blocked, #{failed} failed."
 				blocked.zero? && failed.zero? ? EXIT_OK : EXIT_BLOCK
-			end
+				end
 
-		private
-			def pr_and_check_report
-				report = {
+			# rubocop:disable Layout/AccessModifierIndentation -- tab-width calculation produces unfixable mixed tabs+spaces
+			private
+			# rubocop:enable Layout/AccessModifierIndentation
+				def audit_working_tree_report
+					dirty_reason = dirty_worktree_reason
+					return { dirty: false, context: nil, status: "ok" } if dirty_reason.nil?
+
+					if dirty_reason == "main_worktree"
+						{
+							dirty: true,
+							context: dirty_reason,
+							status: "block",
+							error: "main working tree has uncommitted changes",
+							recovery: "create a worktree with carson worktree create <name>"
+						}
+					else
+						{ dirty: true, context: dirty_reason, status: "ok" }
+					end
+				end
+
+				def pr_and_check_report
+					report = {
 					generated_at: Time.now.utc.iso8601,
 					branch: current_branch,
 					status: "ok",
@@ -581,7 +607,6 @@ module Carson
 				lines.join( "\n" )
 			end
 
-			# True when there are no staged/unstaged/untracked file changes.
 		end
 
 		include Audit