carson 1.0.1 → 2.7.0

data/lib/carson/runtime/local.rb

@@ -131,7 +131,7 @@ module Carson
 			end
 
 			# Installs required hook files and enforces repository hook path.
-			def hook!
+			def prepare!
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
 
@@ -156,23 +156,24 @@ module Carson
 					puts_line "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_line "configured_hooks_path: #{hooks_dir}"
-				check!
+				inspect!
 			end
 
-			# One-command initialisation for new repositories: align remote naming, install hooks,
+			# One-command onboarding for new repositories: align remote naming, install hooks,
 			# apply templates, and produce a first audit report.
-			def init!
+			def onboard!
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
 
-				print_header "Init"
+				print_header "Onboard"
 				unless inside_git_work_tree?
 					puts_line "ERROR: #{repo_root} is not a git repository."
 					return EXIT_ERROR
 				end
 				align_remote_name_for_carson!
-				hook_status = hook!
+				hook_status = prepare!
 				return hook_status unless hook_status == EXIT_OK
 
 				template_status = template_apply!
@@ -180,9 +181,35 @@ module Carson
 
 				audit_status = audit!
 				if audit_status == EXIT_OK
-					puts_line "OK: Carson initialisation completed for #{repo_root}."
+					puts_line "OK: Carson onboard completed for #{repo_root}."
 				elsif audit_status == EXIT_BLOCK
-					puts_line "BLOCK: Carson initialisation completed with policy blocks; resolve and rerun carson audit."
+					puts_line "BLOCK: Carson onboard completed with policy blocks; resolve and rerun carson audit."
+				end
+				print_onboarding_guidance
+				audit_status
+			end
+
+			# Re-applies hooks, templates, and audit after upgrading Carson.
+			def refresh!
+				fingerprint_status = block_if_outsider_fingerprints!
+				return fingerprint_status unless fingerprint_status.nil?
+
+				print_header "Refresh"
+				unless inside_git_work_tree?
+					puts_line "ERROR: #{repo_root} is not a git repository."
+					return EXIT_ERROR
+				end
+				hook_status = prepare!
+				return hook_status unless hook_status == EXIT_OK
+
+				template_status = template_apply!
+				return template_status unless template_status == EXIT_OK
+
+				audit_status = audit!
+				if audit_status == EXIT_OK
+					puts_line "OK: Carson refresh completed for #{repo_root}."
+				elsif audit_status == EXIT_BLOCK
+					puts_line "BLOCK: Carson refresh completed with policy blocks; resolve and rerun carson audit."
 				end
 				audit_status
 			end
@@ -217,11 +244,11 @@ module Carson
 			end
 
 			# Strict hook health check used by humans, hooks, and CI paths.
-			def check!
+			def inspect!
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
 
-				print_header "Hooks Check"
+				print_header "Inspect"
 				ok = hooks_health_report( strict: true )
 				puts_line( ok ? "status: ok" : "status: block" )
 				ok ? EXIT_OK : EXIT_BLOCK
@@ -309,7 +336,7 @@ module Carson
 
 			# Canonical hook template location inside Carson repository.
 			def hook_template_path( hook_name: )
-				File.join( tool_root, "assets", "hooks", hook_name )
+				File.join( tool_root, "hooks", hook_name )
 			end
 
 			# Reports full hook health and can enforce stricter action messaging in `check`.
@@ -374,7 +401,7 @@ module Carson
 						puts_line "ACTION: hooks path mismatch (configured=#{configured_text}, expected=#{expected})."
 					end
 				end
-				message = strict ? "ACTION: run carson hook to align hooks with Carson #{Carson::VERSION}." : "ACTION: run carson hook to enforce local main protections."
+				message = strict ? "ACTION: run carson prepare to align hooks with Carson #{Carson::VERSION}." : "ACTION: run carson prepare to enforce local main protections."
 				puts_line message
 			end
 
@@ -649,6 +676,18 @@ module Carson
 				puts_line "WARN: no #{config.git_remote} or origin remote configured; continue with local baseline only."
 			end
 
+
+			def print_onboarding_guidance
+				puts_line ""
+				puts_line "Carson is ready. Current workflow: #{config.workflow_style}"
+				puts_line ""
+				puts_line "Customise in ~/.carson/config.json:"
+				puts_line "  { \"workflow\": { \"style\": \"branch\" } }  — enforce PR-only merges"
+				puts_line "  { \"workflow\": { \"style\": \"trunk\" } }   — allow direct main commits (default)"
+				puts_line ""
+				puts_line "Run carson refresh after changing config."
+			end
+
 			# Uses `git remote get-url` as existence check to avoid parsing remote lists.
 			def git_remote_exists?( remote_name: )
 				_, _, success, = git_run( "remote", "get-url", remote_name.to_s )

data/lib/carson/runtime/review/gate_support.rb

@@ -4,10 +4,16 @@ module Carson
 			module GateSupport
 			private
 
-				def wait_for_review_warmup
+				def wait_for_review_warmup( owner:, repo:, pr_number: )
 					return unless config.review_wait_seconds.positive?
+					quick = review_gate_snapshot( owner: owner, repo: repo, pr_number: pr_number )
+					if quick[ :unresolved_threads ].empty? && quick[ :unacknowledged_actionable ].empty?
+						puts_line "warmup_skip: all threads resolved"
+						return quick
+					end
 					puts_line "warmup_wait_seconds: #{config.review_wait_seconds}"
 					sleep config.review_wait_seconds
+					nil
 				end
 
 				# Poll delay between consecutive snapshot reads during convergence checks.
@@ -60,6 +66,10 @@ module Carson
 					}
 				end
 
+				def bot_username?( author: )
+					config.review_bot_usernames.any? { |bot| bot.downcase == author.to_s.downcase }
+				end
+
 				def unresolved_thread_entries( details: )
 					Array( details.fetch( :review_threads ) ).each_with_index.map do |thread, index|
 						next if thread.fetch( :is_resolved )
@@ -67,6 +77,7 @@ module Carson
 						next if thread.fetch( :is_outdated )
 						comments = thread.fetch( :comments )
 						first_comment = comments.first || {}
+						next if bot_username?( author: first_comment.fetch( :author, "" ) )
 						latest_time = comments.map { |entry| entry.fetch( :created_at ) }.max.to_s
 						{
 							url: blank_to( value: first_comment.fetch( :url, "" ), default: "#{details.fetch( :url )}#thread-#{index + 1}" ),
@@ -83,6 +94,7 @@ module Carson
 					items = []
 					Array( details.fetch( :comments ) ).each do |comment|
 						next if comment.fetch( :author ) == pr_author
+						next if bot_username?( author: comment.fetch( :author ) )
 						next if disposition_prefixed?( text: comment.fetch( :body ) )
 						hits = matched_risk_keywords( text: comment.fetch( :body ) )
 						next if hits.empty?
@@ -96,6 +108,7 @@ module Carson
 					end
 					Array( details.fetch( :reviews ) ).each do |review|
 						next if review.fetch( :author ) == pr_author
+						next if bot_username?( author: review.fetch( :author ) )
 						next if disposition_prefixed?( text: review.fetch( :body ) )
 						hits = matched_risk_keywords( text: review.fetch( :body ) )
 						changes_requested = review.fetch( :state ) == "CHANGES_REQUESTED"

data/lib/carson/runtime/review.rb

@@ -56,10 +56,10 @@ module Carson
 					return EXIT_BLOCK
 				end
 
-				wait_for_review_warmup
+				pre_snapshot = wait_for_review_warmup( owner: owner, repo: repo, pr_number: pr_summary.fetch( :number ) )
 				converged = false
-				last_snapshot = nil
-				last_signature = nil
+				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|

data/lib/carson/runtime.rb

@@ -3,6 +3,7 @@
 # adapter invocation, and report-location policy.
 require "fileutils"
 require "json"
+require "open3"
 require "time"
 
 module Carson
@@ -58,8 +59,13 @@ module Carson
 		end
 
 		# Single output funnel to keep messaging style consistent.
+		# Prefixes non-empty lines with the Carson badge (⧓).
 		def puts_line( message )
-			out.puts message
+			if message.to_s.strip.empty?
+				out.puts ""
+			else
+				out.puts "#{BADGE} #{message}"
+			end
 		end
 
 		# Converts absolute paths into repo-relative output paths.
@@ -76,12 +82,12 @@ module Carson
 		end
 
 		# Resolves report output precedence:
-		# 1) ~/.cache/carson when HOME is an absolute path
+		# 1) ~/.carson/cache when HOME is an absolute path
 		# 2) TMPDIR/carson when HOME is invalid and TMPDIR is absolute
 		# 3) /tmp/carson as final safety fallback
 		def report_dir_path
 			home = ENV.fetch( "HOME", "" ).to_s
-			return File.join( home, ".cache", "carson" ) if absolute_env_path?( path: home )
+			return File.join( home, ".carson", "cache" ) if absolute_env_path?( path: home )
 
 			tmpdir = ENV.fetch( "TMPDIR", "" ).to_s
 			return File.join( tmpdir, "carson" ) if absolute_env_path?( path: tmpdir )
@@ -180,3 +186,4 @@ require_relative "runtime/local"
 require_relative "runtime/lint"
 require_relative "runtime/audit"
 require_relative "runtime/review"
+require_relative "runtime/govern"

data/lib/carson.rb

@@ -1,6 +1,15 @@
 require_relative "carson/version"
+
+module Carson
+	BADGE = "\u29D3".freeze # ⧓ BLACK BOWTIE (U+29D3)
+end
+
 require_relative "carson/config"
 require_relative "carson/adapters/git"
 require_relative "carson/adapters/github"
+require_relative "carson/adapters/agent"
+require_relative "carson/adapters/prompt"
+require_relative "carson/adapters/codex"
+require_relative "carson/adapters/claude"
 require_relative "carson/runtime"
 require_relative "carson/cli"

data/templates/.github/AGENTS.md

@@ -0,0 +1 @@
+Read `.github/carson-instructions.md` for repository governance rules enforced by Carson.

data/templates/.github/CLAUDE.md

@@ -0,0 +1 @@
+Read `.github/carson-instructions.md` for repository governance rules enforced by Carson.

data/templates/.github/carson-instructions.md

@@ -0,0 +1,12 @@
+## Shared Governance Baseline
+
+- GitHub rulesets and required checks are merge authority.
+- Carson runs as an outsider runtime for hook health, main sync, scope integrity, and gh visibility.
+- Before commit and before push, run `carson audit`.
+- At session start and again immediately before merge recommendation, run `gh pr list --state open --limit 50` and re-confirm active PR priorities.
+- Before merge recommendation, run `carson review gate`; it enforces warm-up wait, unresolved-thread convergence, and `Disposition:` dispositions for actionable top-level findings.
+- Actionable findings are unresolved review threads, any non-author `CHANGES_REQUESTED` review, or non-author comments/reviews with risk keywords (`bug`, `security`, `incorrect`, `block`, `fail`, `regression`).
+- `Disposition:` dispositions must include one token (`accepted`, `rejected`, `deferred`) and the target review URL.
+- Scheduled governance runs `carson review sweep` every 8 hours to track late actionable review activity on recent open/closed PRs.
+- Do not treat green checks or `mergeStateStatus: CLEAN` as sufficient if unresolved review threads remain.
+- Never suggest destructive operations on protected refs (`main`/`master`, local or remote).

data/templates/.github/copilot-instructions.md

@@ -1,12 +1 @@
-## Shared Governance Baseline
-
-- GitHub rulesets and required checks are merge authority.
-- Carson runs as an outsider runtime for hook health, main sync, scope integrity, and gh visibility.
-- Before commit and before push, run `carson audit`.
-- At session start and again immediately before merge recommendation, run `gh pr list --state open --limit 50` and re-confirm active PR priorities.
-- Before merge recommendation, run `carson review gate`; it enforces warm-up wait, unresolved-thread convergence, and `Disposition:` dispositions for actionable top-level findings.
-- Actionable findings are unresolved review threads, any non-author `CHANGES_REQUESTED` review, or non-author comments/reviews with risk keywords (`bug`, `security`, `incorrect`, `block`, `fail`, `regression`).
-- `Disposition:` dispositions must include one token (`accepted`, `rejected`, `deferred`) and the target review URL.
-- Scheduled governance runs `carson review sweep` every 8 hours to track late actionable review activity on recent open/closed PRs.
-- Do not treat green checks or `mergeStateStatus: CLEAN` as sufficient if unresolved review threads remain.
-- Never suggest destructive operations on protected refs (`main`/`master`, local or remote).
+Read `.github/carson-instructions.md` for repository governance rules enforced by Carson.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 2.7.0
 platform: ruby
 authors:
 - Hailei Wang
@@ -26,21 +26,28 @@ files:
 - MANUAL.md
 - README.md
 - RELEASE.md
+- SKILL.md
 - VERSION
-- assets/hooks/pre-commit
-- assets/hooks/pre-merge-commit
-- assets/hooks/pre-push
-- assets/hooks/prepare-commit-msg
 - carson.gemspec
 - exe/carson
+- hooks/pre-commit
+- hooks/pre-merge-commit
+- hooks/pre-push
+- hooks/prepare-commit-msg
+- icon.svg
 - lib/carson.rb
+- lib/carson/adapters/agent.rb
+- lib/carson/adapters/claude.rb
+- lib/carson/adapters/codex.rb
 - lib/carson/adapters/git.rb
 - lib/carson/adapters/github.rb
+- lib/carson/adapters/prompt.rb
 - lib/carson/cli.rb
 - lib/carson/config.rb
 - lib/carson/policy/ruby/lint.rb
 - lib/carson/runtime.rb
 - lib/carson/runtime/audit.rb
+- lib/carson/runtime/govern.rb
 - lib/carson/runtime/lint.rb
 - lib/carson/runtime/local.rb
 - lib/carson/runtime/review.rb
@@ -50,6 +57,9 @@ files:
 - lib/carson/runtime/review/sweep_support.rb
 - lib/carson/runtime/review/utility.rb
 - lib/carson/version.rb
+- templates/.github/AGENTS.md
+- templates/.github/CLAUDE.md
+- templates/.github/carson-instructions.md
 - templates/.github/copilot-instructions.md
 - templates/.github/pull_request_template.md
 homepage: https://github.com/wanghailei/carson