carson 1.0.0

data/exe/carson

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift( File.expand_path( "../lib", __dir__ ) )
+require "carson"
+
+exit Carson::CLI.start(
+	argv: ARGV.dup,
+	repo_root: Dir.pwd,
+	tool_root: File.expand_path( "..", __dir__ ),
+	out: $stdout,
+	err: $stderr
+)

data/lib/carson/adapters/git.rb

@@ -0,0 +1,20 @@
+require "open3"
+
+module Carson
+	module Adapters
+		class Git
+			def initialize( repo_root: )
+				@repo_root = repo_root
+			end
+
+			def run( *args )
+				stdout_text, stderr_text, status = Open3.capture3( "git", *args, chdir: repo_root )
+				[ stdout_text, stderr_text, status.success?, status.exitstatus ]
+			end
+
+		private
+
+			attr_reader :repo_root
+		end
+	end
+end

data/lib/carson/adapters/github.rb

@@ -0,0 +1,20 @@
+require "open3"
+
+module Carson
+	module Adapters
+		class GitHub
+			def initialize( repo_root: )
+				@repo_root = repo_root
+			end
+
+			def run( *args )
+				stdout_text, stderr_text, status = Open3.capture3( "gh", *args, chdir: repo_root )
+				[ stdout_text, stderr_text, status.success?, status.exitstatus ]
+			end
+
+		private
+
+			attr_reader :repo_root
+		end
+	end
+end

data/lib/carson/cli.rb

@@ -0,0 +1,189 @@
+require "optparse"
+
+module Carson
+	class CLI
+		def self.start( argv:, repo_root:, tool_root:, out:, err: )
+			parsed = parse_args( argv: argv, out: out, err: err )
+			command = parsed.fetch( :command )
+			return Runtime::EXIT_OK if command == :help
+
+			if command == "version"
+				out.puts Carson::VERSION
+				return Runtime::EXIT_OK
+			end
+
+			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 )
+				err.puts "ERROR: repository path does not exist: #{target_repo_root}"
+				return Runtime::EXIT_ERROR
+			end
+
+			runtime = Runtime.new( repo_root: target_repo_root, tool_root: tool_root, out: out, err: err )
+			dispatch( parsed: parsed, runtime: runtime )
+		rescue ConfigError => e
+			err.puts "CONFIG ERROR: #{e.message}"
+			Runtime::EXIT_ERROR
+		rescue StandardError => e
+			err.puts "ERROR: #{e.message}"
+			Runtime::EXIT_ERROR
+		end
+
+		def self.parse_args( argv:, out:, err: )
+			parser = build_parser
+			preset = parse_preset_command( argv: argv, out: out, parser: parser )
+			return preset unless preset.nil?
+
+			command = argv.shift
+			parse_command( command: command, argv: argv, parser: parser, err: err )
+		rescue OptionParser::ParseError => e
+			err.puts e.message
+			err.puts parser
+			{ command: :invalid }
+		end
+
+		def self.build_parser
+			OptionParser.new do |opts|
+				opts.banner = "Usage: carson [audit|sync|prune|hook|check|init [repo_path]|offboard [repo_path]|template check|template apply|lint setup --source <path-or-git-url>|review gate|review sweep|version]"
+			end
+		end
+
+		def self.parse_preset_command( argv:, out:, parser: )
+			first = argv.first
+			if [ "--help", "-h" ].include?( first )
+				out.puts parser
+				return { command: :help }
+			end
+			return { command: "version" } if [ "--version", "-v" ].include?( first )
+			return { command: "audit" } if argv.empty?
+
+			nil
+		end
+
+		def self.parse_command( command:, argv:, parser:, err: )
+			case command
+			when "version"
+				parser.parse!( argv )
+				{ command: "version" }
+			when "init", "offboard"
+				parse_repo_path_command( command: command, argv: argv, parser: parser, err: err )
+			when "template"
+				parse_named_subcommand( command: command, usage: "check|apply", argv: argv, parser: parser, err: err )
+			when "lint"
+				parse_lint_subcommand( argv: argv, parser: parser, err: err )
+			when "review"
+				parse_named_subcommand( command: command, usage: "gate|sweep", argv: argv, parser: parser, err: err )
+			else
+				parser.parse!( argv )
+				{ command: command }
+			end
+		end
+
+		def self.parse_repo_path_command( command:, argv:, parser:, err: )
+			parser.parse!( argv )
+			if argv.length > 1
+				err.puts "Too many arguments for #{command}. Use: carson #{command} [repo_path]"
+				err.puts parser
+				return { command: :invalid }
+			end
+
+			repo_path = argv.first
+			{
+				command: command,
+				repo_root: repo_path.to_s.strip.empty? ? nil : File.expand_path( repo_path )
+			}
+		end
+
+		def self.parse_named_subcommand( command:, usage:, argv:, parser:, err: )
+			action = argv.shift
+			parser.parse!( argv )
+			if action.to_s.strip.empty?
+				err.puts "Missing subcommand for #{command}. Use: carson #{command} #{usage}"
+				err.puts parser
+				return { command: :invalid }
+			end
+			{ command: "#{command}:#{action}" }
+		end
+
+		def self.parse_lint_subcommand( argv:, parser:, err: )
+			action = argv.shift
+			unless action == "setup"
+				err.puts "Missing or invalid subcommand for lint. Use: carson lint setup --source <path-or-git-url> [--ref <git-ref>] [--force]"
+				err.puts parser
+				return { command: :invalid }
+			end
+
+			options = {
+				source: nil,
+				ref: "main",
+				force: false
+			}
+			lint_parser = OptionParser.new do |opts|
+				opts.banner = "Usage: carson lint setup --source <path-or-git-url> [--ref <git-ref>] [--force]"
+				opts.on( "--source SOURCE", "Source repository path or git URL that contains CODING/" ) { |value| options[ :source ] = value.to_s.strip }
+				opts.on( "--ref REF", "Git ref used when --source is a git URL (default: main)" ) { |value| options[ :ref ] = value.to_s.strip }
+				opts.on( "--force", "Overwrite existing files in ~/AI/CODING" ) { options[ :force ] = true }
+			end
+			lint_parser.parse!( argv )
+			if options.fetch( :source ).to_s.empty?
+				err.puts "Missing required --source for lint setup."
+				err.puts lint_parser
+				return { command: :invalid }
+			end
+			unless argv.empty?
+				err.puts "Unexpected arguments for lint setup: #{argv.join( ' ' )}"
+				err.puts lint_parser
+				return { command: :invalid }
+			end
+			{
+				command: "lint:setup",
+				source: options.fetch( :source ),
+				ref: options.fetch( :ref ),
+				force: options.fetch( :force )
+			}
+		rescue OptionParser::ParseError => e
+			err.puts e.message
+			err.puts lint_parser
+			{ command: :invalid }
+		end
+
+		def self.dispatch( parsed:, runtime: )
+			command = parsed.fetch( :command )
+			return Runtime::EXIT_ERROR if command == :invalid
+
+			case command
+			when "audit"
+				runtime.audit!
+			when "sync"
+				runtime.sync!
+			when "prune"
+				runtime.prune!
+			when "hook"
+				runtime.hook!
+			when "check"
+				runtime.check!
+			when "init"
+				runtime.init!
+			when "offboard"
+				runtime.offboard!
+			when "template:check"
+				runtime.template_check!
+			when "template:apply"
+				runtime.template_apply!
+			when "lint:setup"
+				runtime.lint_setup!(
+					source: parsed.fetch( :source ),
+					ref: parsed.fetch( :ref ),
+					force: parsed.fetch( :force )
+				)
+			when "review:gate"
+				runtime.review_gate!
+			when "review:sweep"
+				runtime.review_sweep!
+			else
+				runtime.send( :puts_line, "Unknown command: #{command}" )
+				Runtime::EXIT_ERROR
+			end
+		end
+	end
+end

data/lib/carson/config.rb

@@ -0,0 +1,348 @@
+require "json"
+
+module Carson
+	class ConfigError < StandardError
+	end
+
+	# Config is built-in only for outsider mode; host repositories do not carry Carson config files.
+	class Config
+		attr_reader :git_remote, :main_branch, :protected_branches, :hooks_base_path, :required_hooks,
+			:path_groups, :template_managed_files, :lint_languages,
+			:review_wait_seconds, :review_poll_seconds, :review_max_polls, :review_sweep_window_days,
+			:review_sweep_states, :review_disposition_prefix, :review_risk_keywords,
+			:review_tracking_issue_title, :review_tracking_issue_label, :ruby_indentation
+
+		def self.load( repo_root: )
+			base_data = default_data
+			merged_data = deep_merge( base: base_data, overlay: load_global_config_data( repo_root: repo_root ) )
+			data = apply_env_overrides( data: merged_data )
+			new( data: data )
+		end
+
+		def self.default_data
+			{
+				"git" => {
+					"remote" => "github",
+					"main_branch" => "main",
+					"protected_branches" => [ "main", "master" ]
+				},
+				"hooks" => {
+					"base_path" => "~/.carson/hooks",
+					"required_hooks" => [ "pre-commit", "prepare-commit-msg", "pre-merge-commit", "pre-push" ]
+				},
+				"scope" => {
+					"path_groups" => {
+						"tool" => [ "exe/**", "bin/**", "lib/**", "script/**", ".github/**", "templates/.github/**", "assets/hooks/**", "install.sh", "README.md", "RELEASE.md", "VERSION", "carson.gemspec" ],
+						"ui" => [ "app/views/**", "app/assets/**", "app/javascript/**", "docs/ui_*.md" ],
+						"test" => [ "test/**", "spec/**", "features/**" ],
+						"domain" => [ "app/**", "db/**", "config/**" ],
+						"docs" => [ "docs/**", "*.md" ]
+					}
+				},
+				"template" => {
+					"managed_files" => [ ".github/copilot-instructions.md", ".github/pull_request_template.md" ]
+				},
+				"lint" => {
+					"languages" => default_lint_languages_data
+				},
+				"review" => {
+					"wait_seconds" => 60,
+					"poll_seconds" => 15,
+					"max_polls" => 20,
+					"required_disposition_prefix" => "Disposition:",
+					"risk_keywords" => [ "bug", "security", "incorrect", "block", "fail", "regression" ],
+					"sweep" => {
+						"window_days" => 3,
+						"states" => [ "open", "closed" ]
+					},
+					"tracking_issue" => {
+						"title" => "Carson review sweep findings",
+						"label" => "carson-review-sweep"
+					}
+				},
+				"style" => {
+					"ruby_indentation" => "tabs"
+				}
+				}
+			end
+
+			def self.default_lint_languages_data
+				ruby_runner = File.expand_path( "policy/ruby/lint.rb", __dir__ )
+				{
+					"ruby" => {
+						"enabled" => true,
+						"globs" => [ "**/*.rb", "Gemfile", "*.gemspec", "Rakefile" ],
+						"command" => [ "ruby", ruby_runner, "{files}" ],
+						"config_files" => [ "~/AI/CODING/rubocop.yml" ]
+					},
+					"javascript" => {
+						"enabled" => false,
+						"globs" => [ "**/*.js", "**/*.mjs", "**/*.cjs", "**/*.jsx" ],
+						"command" => [ "node", "~/AI/CODING/javascript.lint.js", "{files}" ],
+						"config_files" => [ "~/AI/CODING/javascript.lint.js" ]
+					},
+					"css" => {
+						"enabled" => false,
+						"globs" => [ "**/*.css" ],
+						"command" => [ "node", "~/AI/CODING/css.lint.js", "{files}" ],
+						"config_files" => [ "~/AI/CODING/css.lint.js" ]
+					},
+					"html" => {
+						"enabled" => false,
+						"globs" => [ "**/*.html" ],
+						"command" => [ "node", "~/AI/CODING/html.lint.js", "{files}" ],
+						"config_files" => [ "~/AI/CODING/html.lint.js" ]
+					},
+					"erb" => {
+						"enabled" => false,
+						"globs" => [ "**/*.erb" ],
+						"command" => [ "ruby", "~/AI/CODING/erb.lint.rb", "{files}" ],
+						"config_files" => [ "~/AI/CODING/erb.lint.rb" ]
+					}
+				}
+			end
+
+		def self.load_global_config_data( repo_root: )
+			path = global_config_path( repo_root: repo_root )
+			return {} if path.empty? || !File.file?( path )
+
+			raw = File.read( path )
+			parsed = JSON.parse( raw )
+			raise ConfigError, "global config must be a JSON object at #{path}" unless parsed.is_a?( Hash )
+			parsed
+		rescue JSON::ParserError => e
+			raise ConfigError, "invalid global config JSON at #{path} (#{e.message})"
+		end
+
+		def self.global_config_path( repo_root: )
+			override = ENV.fetch( "CARSON_CONFIG_FILE", "" ).to_s.strip
+			return File.expand_path( override ) unless override.empty?
+
+			home = ENV.fetch( "HOME", "" ).to_s.strip
+			return "" unless home.start_with?( "/" )
+
+			File.join( home, ".carson", "config.json" )
+		end
+
+		def self.deep_merge( base:, overlay: )
+			return deep_dup_value( value: base ) unless overlay.is_a?( Hash )
+
+			base.each_with_object( {} ) { |( key, value ), copy| copy[ key ] = deep_dup_value( value: value ) }.tap do |merged|
+				overlay.each do |key, value|
+					if merged[ key ].is_a?( Hash ) && value.is_a?( Hash )
+						merged[ key ] = deep_merge( base: merged[ key ], overlay: value )
+					else
+						merged[ key ] = deep_dup_value( value: value )
+					end
+				end
+			end
+		end
+
+		def self.deep_dup_value( value: )
+			case value
+			when Hash
+				value.each_with_object( {} ) { |( key, entry ), copy| copy[ key ] = deep_dup_value( value: entry ) }
+			when Array
+				value.map { |entry| deep_dup_value( value: entry ) }
+			else
+				value
+			end
+		end
+
+		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?
+			review = fetch_hash_section( data: copy, key: "review" )
+			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?
+			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.fetch( "CARSON_REVIEW_SWEEP_STATES", "" ).split( "," ).map( &:strip ).reject( &:empty? )
+			sweep[ "states" ] = states unless states.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?
+			copy
+		end
+
+		def self.fetch_hash_section( data:, key: )
+			value = data[ key ]
+			raise ConfigError, "missing config section #{key}" if value.nil?
+			raise ConfigError, "config section #{key} must be an object" unless value.is_a?( Hash )
+			value
+		end
+
+		def self.env_integer( key:, fallback: )
+			text = ENV.fetch( key, "" ).to_s.strip
+			return fallback if text.empty?
+			Integer( text )
+		rescue ArgumentError, TypeError
+			fallback
+		end
+
+		def initialize( data: )
+			@git_remote = fetch_string( hash: fetch_hash( hash: data, key: "git" ), key: "remote" )
+			@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" )
+
+			@path_groups = fetch_hash( hash: fetch_hash( hash: data, key: "scope" ), key: "path_groups" ).transform_values { |value| normalize_patterns( value: value ) }
+
+			@template_managed_files = fetch_string_array( hash: fetch_hash( hash: data, key: "template" ), key: "managed_files" )
+			@lint_languages = normalize_lint_languages(
+				languages_hash: fetch_hash( hash: fetch_hash( hash: data, key: "lint" ), key: "languages" )
+			)
+
+			review_hash = fetch_hash( hash: data, key: "review" )
+			@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_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" )
+			@review_sweep_states = fetch_string_array( hash: sweep_hash, key: "states" ).map( &:downcase )
+			tracking_issue_hash = fetch_hash( hash: review_hash, key: "tracking_issue" )
+			@review_tracking_issue_title = fetch_string( hash: tracking_issue_hash, key: "title" )
+			@review_tracking_issue_label = fetch_string( hash: tracking_issue_hash, key: "label" )
+			style_hash = fetch_hash( hash: data, key: "style" )
+			@ruby_indentation = fetch_string( hash: style_hash, key: "ruby_indentation" ).downcase
+
+			validate!
+		end
+
+	private
+
+			def validate!
+				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, "scope.path_groups cannot be empty" if path_groups.empty?
+				raise ConfigError, "lint.languages cannot be empty" if lint_languages.empty?
+				raise ConfigError, "review.required_disposition_prefix cannot be empty" if review_disposition_prefix.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, "style.ruby_indentation must be one of tabs, spaces, either" unless [ "tabs", "spaces", "either" ].include?( ruby_indentation )
+			end
+
+			def fetch_hash( hash:, key: )
+				value = hash[ key ]
+				raise ConfigError, "missing config key #{key}" unless value.is_a?( Hash )
+				value
+			end
+
+			def fetch_string( hash:, key: )
+				value = hash[ key ]
+				raise ConfigError, "missing config key #{key}" if value.nil?
+				text = value.to_s.strip
+				raise ConfigError, "config key #{key} cannot be blank" if text.empty?
+				text
+			end
+
+			def fetch_string_array( hash:, key: )
+				value = hash[ key ]
+				raise ConfigError, "missing config key #{key}" unless value.is_a?( Array )
+				array = value.map { |entry| entry.to_s.strip }.reject( &:empty? )
+				raise ConfigError, "config key #{key} cannot be empty" if array.empty?
+				array
+			end
+
+			def fetch_non_negative_integer( hash:, key: )
+				value = fetch_integer( hash: hash, key: key )
+				raise ConfigError, "config key #{key} must be >= 0" if value.negative?
+				value
+			end
+
+			def fetch_positive_integer( hash:, key: )
+				value = fetch_integer( hash: hash, key: key )
+				raise ConfigError, "config key #{key} must be > 0" unless value.positive?
+				value
+			end
+
+			def fetch_integer( hash:, key: )
+				value = hash[ key ]
+				raise ConfigError, "missing config key #{key}" if value.nil?
+				Integer( value )
+			rescue ArgumentError, TypeError
+				raise ConfigError, "config key #{key} must be an integer"
+			end
+
+			def normalize_patterns( value: )
+				patterns = Array( value ).map { |entry| entry.to_s.strip }.reject( &:empty? )
+				raise ConfigError, "scope.path_groups entries must contain at least one glob" if patterns.empty?
+				patterns
+			end
+
+			def normalize_lint_languages( languages_hash: )
+				raise ConfigError, "lint.languages must be an object" unless languages_hash.is_a?( Hash )
+				normalised = {}
+				languages_hash.each do |language_key, raw_entry|
+					language = language_key.to_s.strip.downcase
+					raise ConfigError, "lint.languages contains blank language key" if language.empty?
+					raise ConfigError, "lint.languages.#{language} must be an object" unless raw_entry.is_a?( Hash )
+
+					normalised[ language ] = normalize_lint_language_entry( language: language, raw_entry: raw_entry )
+				end
+				normalised
+			end
+
+			def normalize_lint_language_entry( language:, raw_entry: )
+				{
+					enabled: fetch_optional_boolean(
+						hash: raw_entry,
+						key: "enabled",
+						default: true,
+						key_path: "lint.languages.#{language}.enabled"
+					),
+					globs: normalize_lint_globs( language: language, value: raw_entry[ "globs" ] ),
+					command: normalize_lint_command( language: language, value: raw_entry[ "command" ] ),
+					config_files: normalize_lint_config_files( language: language, value: raw_entry[ "config_files" ] )
+				}
+			end
+
+			def normalize_lint_globs( language:, value: )
+				raise ConfigError, "lint.languages.#{language}.globs must be an array" unless value.is_a?( Array )
+				patterns = Array( value ).map { |entry| entry.to_s.strip }.reject( &:empty? )
+				raise ConfigError, "lint.languages.#{language}.globs must contain at least one pattern" if patterns.empty?
+				patterns
+			end
+
+			def normalize_lint_command( language:, value: )
+				raise ConfigError, "lint.languages.#{language}.command must be an array" unless value.is_a?( Array )
+				command = Array( value ).map { |entry| entry.to_s.strip }.reject( &:empty? )
+				raise ConfigError, "lint.languages.#{language}.command must contain at least one argument" if command.empty?
+				command
+			end
+
+			def normalize_lint_config_files( language:, value: )
+				raise ConfigError, "lint.languages.#{language}.config_files must be an array" unless value.is_a?( Array )
+				files = Array( value ).map { |entry| entry.to_s.strip }.reject( &:empty? )
+				raise ConfigError, "lint.languages.#{language}.config_files must contain at least one path" if files.empty?
+				files.map do |path|
+					expanded = path.start_with?( "~" ) ? File.expand_path( path ) : path
+					raise ConfigError, "lint.languages.#{language}.config_files entries must be absolute paths or ~/ paths" unless expanded.start_with?( "/" )
+					expanded
+				end
+			end
+
+			def fetch_optional_boolean( hash:, key:, default:, key_path: nil )
+				value = hash.fetch( key, default )
+				return true if value == true
+				return false if value == false
+
+				raise ConfigError, "config key #{key_path || key} must be boolean"
+			end
+	end
+end

data/lib/carson/policy/ruby/lint.rb

@@ -0,0 +1,61 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "open3"
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_BLOCK = 2
+
+def rubocop_config_path
+	File.expand_path( "~/AI/CODING/rubocop.yml" )
+end
+
+def print_stream( io, text )
+	content = text.to_s
+	return if content.empty?
+	io.print( content )
+end
+
+def run_rubocop( files: )
+	stdout_text, stderr_text, status = Open3.capture3(
+		"rubocop", "--config", rubocop_config_path, *files
+	)
+	print_stream( $stdout, stdout_text )
+	print_stream( $stderr, stderr_text )
+	{ status: :completed, exit_code: status.exitstatus.to_i }
+rescue Errno::ENOENT
+	$stderr.puts "ERROR: RuboCop executable `rubocop` is unavailable in PATH. Install the pinned RuboCop gem before running carson audit."
+	{ status: :unavailable, exit_code: nil }
+rescue StandardError => e
+	$stderr.puts "ERROR: RuboCop execution failed (#{e.message})"
+	{ status: :runtime_error, exit_code: nil }
+end
+
+def lint_exit_code( result: )
+	case result.fetch( :status )
+	when :unavailable
+		EXIT_BLOCK
+	when :runtime_error
+		EXIT_ERROR
+	else
+		case result.fetch( :exit_code )
+		when 0
+			EXIT_OK
+		when 1
+			EXIT_BLOCK
+		else
+			EXIT_ERROR
+		end
+	end
+end
+
+files = ARGV.map( &:to_s ).map( &:strip ).reject( &:empty? )
+config_path = rubocop_config_path
+unless File.file?( config_path )
+	$stderr.puts "ERROR: RuboCop config not found at #{config_path}. Run `carson lint setup --source <path-or-git-url>`."
+	exit EXIT_ERROR
+end
+
+result = run_rubocop( files: files )
+exit lint_exit_code( result: result )