carson 3.22.0 → 3.23.0

data/carson.gemspec

@@ -7,8 +7,8 @@ Gem::Specification.new do |spec|
 	spec.version = Carson::VERSION
 	spec.authors = [ "Hailei Wang", "Codex", "Claude Code" ]
 	spec.email = [ "wanghailei@users.noreply.github.com" ]
-	spec.summary = "Autonomous repository governance — you write the code, Carson manages everything else."
-	spec.description = "Carson is a governance runtime that lives outside the repositories it governs — no Carson-owned artefacts in your repo. On every commit, managed hooks enforce centralised lint policy and review gates. At portfolio level, carson govern triages every open PR across your registered repositories: merge what's ready, dispatch coding agents to fix what's failing, escalate what needs human judgement. One command, all your projects, unmanned."
+	spec.summary = "Autonomous git strategist and repositories governor — you write the code, Carson manages everything else."
+	spec.description = "Carson is an autonomous git strategist and repositories governor that lives outside the repositories it governs — no Carson-owned artefacts in your repo. As strategist, Carson knows when to branch, how to isolate concurrent work, and how to recover from failures. As governor, it enforces review gates, manages templates, and triages every open PR across your portfolio: merge what's ready, dispatch coding agents to fix what's failing, escalate what needs human judgement. One command, all your projects, unmanned."
 	spec.homepage = "https://github.com/wanghailei/carson"
 	spec.license = "PolyForm-Shield-1.0.0"
 	spec.required_ruby_version = ">= 3.4"
@@ -28,9 +28,8 @@ Gem::Specification.new do |spec|
 	spec.bindir = "exe"
 	spec.executables = [ "carson" ]
 	spec.require_paths = [ "lib" ]
+	spec.add_dependency "sqlite3", ">= 1.3", "< 3"
 	spec.files = Dir.glob( "{lib,exe,templates,hooks}/**/*", File::FNM_DOTMATCH ).select { |path| File.file?( path ) } + [
-		".github/copilot-instructions.md",
-		".github/pull_request_template.md",
 		".github/workflows/carson_policy.yml",
 		"README.md",
 		"MANUAL.md",

data/hooks/command-guard

@@ -53,6 +53,6 @@ if ! grep -qF "\"$normalised\"" "$config_file" 2>/dev/null; then
 fi
 
 # This is a raw gh pr command in a governed repo — block it.
-echo "BLOCKED: raw \`gh pr create/merge\` in a Carson-governed repository." >&2
+echo "This repo is Carson-governed — use \`carson deliver\` instead of raw \`gh pr\`." >&2
 echo "Use \`carson deliver\` instead — it handles push, PR, and merge with safety guards." >&2
 exit 2

data/hooks/pre-push

@@ -4,9 +4,9 @@
 # Guards:
 #   1. Blocks direct push to main/master refs.
 #   2. Blocks raw git push in governed repos — agents must use `carson deliver`.
-#      Carson sets CARSON_PUSH=1 internally so its own pushes pass through.
+#      Carson bypasses via --no-verify internally. No env-var signal to spoof.
 #
-# Bypass (emergency only): git push --no-verify
+# Bypass: git push --no-verify
 set -euo pipefail
 
 hooks_dir="$(cd "$(dirname "$0")" && pwd)"
@@ -21,9 +21,9 @@ has_commit_push=false
 while read -r local_ref local_sha remote_ref remote_sha; do
 	case "$remote_ref" in
 		refs/heads/main|refs/heads/master)
-			echo "BLOCKED: direct push to ${remote_ref#refs/heads/} is not allowed." >&2
+			echo "Pushes to ${remote_ref#refs/heads/} go through PRs, not direct push." >&2
 			echo "Use \`carson deliver\` instead — it handles push, PR, and merge with safety guards." >&2
-			echo "Bypass (emergency only): git push --no-verify" >&2
+			echo "Bypass: git push --no-verify" >&2
 			exit 1
 			;;
 	esac
@@ -31,23 +31,20 @@ while read -r local_ref local_sha remote_ref remote_sha; do
 done
 
 # --- Guard 2: block raw git push in governed repos ---
-# Carson sets CARSON_PUSH=1 when pushing internally via `deliver`.
-# If the variable is absent, this is a raw git push from an agent or human.
+# All pushes in governed repos are blocked unconditionally.
+# Carson bypasses this hook via --no-verify when pushing internally.
+# No env-var bypass — cannot be spoofed.
 
-if [[ -z "${CARSON_PUSH:-}" ]]; then
-	config_file="${HOME}/.carson/config.json"
-	if [[ -f "$config_file" ]]; then
-		repo_root="$(git rev-parse --show-toplevel 2>/dev/null || echo "")"
-		if [[ -n "$repo_root" ]]; then
-			# Check if this repo appears in govern.repos.
-			# Uses a simple grep against the JSON — no jq dependency required.
-			normalised="$(cd "$repo_root" && pwd -P)"
-			if grep -qF "\"$normalised\"" "$config_file" 2>/dev/null; then
-				echo "BLOCKED: raw \`git push\` in a Carson-governed repository." >&2
-				echo "Use \`carson deliver\` instead — it handles push, PR, and merge with safety guards." >&2
-				echo "Bypass (emergency only): git push --no-verify" >&2
-				exit 1
-			fi
+config_file="${HOME}/.carson/config.json"
+if [[ -f "$config_file" ]]; then
+	repo_root="$(git rev-parse --show-toplevel 2>/dev/null || echo "")"
+	if [[ -n "$repo_root" ]]; then
+		normalised="$(cd "$repo_root" && pwd -P)"
+		if grep -qF "\"$normalised\"" "$config_file" 2>/dev/null; then
+			echo "This repo is Carson-governed — use \`carson deliver\` instead of raw \`git push\`." >&2
+			echo "Use \`carson deliver\` instead — it handles push, PR, and merge with safety guards." >&2
+			echo "Bypass: git push --no-verify" >&2
+			exit 1
 		fi
 	fi
 fi

data/lib/carson/adapters/agent.rb

@@ -2,14 +2,14 @@
 module Carson
 	module Adapters
 		module Agent
-			WorkOrder = Data.define( :repo, :branch, :pr_number, :objective, :context, :acceptance_checks )
+			WorkOrder = Struct.new( :repo, :branch, :pr_number, :objective, :context, :acceptance_checks, keyword_init: true )
 			# objective: "fix_ci" | "address_review" | "fix_audit"
 			# context: String (legacy — PR title) or Hash with structured evidence:
 			#   fix_ci:         { title:, ci_logs:, ci_run_url:, prior_attempt: { summary:, dispatched_at: } }
 			#   address_review: { title:, review_findings: [{ kind:, url:, body: }], prior_attempt: ... }
 			# acceptance_checks: what must pass for the fix to be accepted
 
-			Result = Data.define( :status, :summary, :evidence, :commit_sha )
+			Result = Struct.new( :status, :summary, :evidence, :commit_sha, keyword_init: true )
 			# status: "done" | "failed" | "timeout"
 		end
 	end

data/lib/carson/branch.rb

@@ -0,0 +1,38 @@
+# Passive branch record. Branch holds identity and current facts only.
+module Carson
+	class Branch
+		attr_reader :repository, :name, :purpose, :head, :worktree, :delivery
+
+		def initialize( repository:, name:, runtime:, purpose: nil, head: nil, worktree: nil, delivery: nil )
+			@repository = repository
+			@name = name
+			@runtime = runtime
+			@purpose = purpose
+			@head = head
+			@worktree = worktree
+			@delivery = delivery
+		end
+
+		# Re-reads the branch facts from git and Carson's ledger.
+		def reload
+			refreshed_head = runtime.git_capture!( "rev-parse", name ).strip
+			refreshed_worktree = runtime.worktree_list.find { |entry| entry.branch == name }&.path || worktree
+			refreshed_delivery = runtime.ledger.active_delivery( repo_path: repository.path, branch_name: name )
+			self.class.new(
+				repository: repository,
+				name: name,
+				runtime: runtime,
+				purpose: purpose,
+				head: refreshed_head,
+				worktree: refreshed_worktree,
+				delivery: refreshed_delivery
+			)
+		rescue StandardError
+			self
+		end
+
+	private
+
+		attr_reader :runtime
+	end
+end

data/lib/carson/cli.rb

@@ -24,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
 
@@ -32,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
 
@@ -61,11 +61,11 @@ module Carson
 				parser.separator "Repository governance and workflow automation for coding agents."
 				parser.separator ""
 				parser.separator "Commands:"
-				parser.separator "    status       Show repository state (branch, PRs, worktrees)"
+				parser.separator "    status       Show repository delivery state"
 				parser.separator "    setup        Initialise Carson configuration"
 				parser.separator "    audit        Run pre-commit health checks"
 				parser.separator "    sync         Sync local main with remote"
-				parser.separator "    deliver      Push, create PR, and optionally merge"
+				parser.separator "    deliver      Start autonomous branch delivery"
 				parser.separator "    prune        Remove stale local branches"
 				parser.separator "    worktree     Manage isolated coding worktrees"
 				parser.separator "    housekeep    Sync, reap worktrees, and prune branches"
@@ -138,7 +138,7 @@ module Carson
 		def self.parse_setup_command( arguments:, error: )
 			options = {}
 			setup_parser = OptionParser.new do |parser|
-				parser.banner = "Usage: carson setup [--remote NAME] [--main-branch NAME] [--workflow STYLE] [--merge METHOD] [--canonical PATH]"
+				parser.banner = "Usage: carson setup [--remote NAME] [--main-branch NAME] [--workflow STYLE] [--canonical PATH]"
 				parser.separator ""
 				parser.separator "Initialise Carson configuration for the current repository."
 				parser.separator "Detects git remote, main branch, and workflow style, then writes .carson.yml."
@@ -148,13 +148,11 @@ module Carson
 				parser.on( "--remote NAME", "Git remote name" ) { |value| options[ "git.remote" ] = value }
 				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"
 				parser.separator "    carson setup --remote github            Use 'github' as the git remote"
-				parser.separator "    carson setup --merge squash             Set squash as the merge method"
 			end
 			setup_parser.parse!( arguments )
 			unless arguments.empty?
@@ -165,6 +163,7 @@ module Carson
 			{ command: "setup", cli_choices: options }
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts setup_parser
 			{ command: :invalid }
 		end
 
@@ -195,6 +194,7 @@ module Carson
 			}
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts onboard_parser
 			{ command: :invalid }
 		end
 
@@ -222,6 +222,7 @@ module Carson
 			}
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts offboard_parser
 			{ command: :invalid }
 		end
 
@@ -265,6 +266,7 @@ module Carson
 			}
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts refresh_parser
 			{ command: :invalid }
 		end
 
@@ -292,6 +294,7 @@ module Carson
 			{ command: "prune", json: options[ :json ] }
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts prune_parser
 			{ command: :invalid }
 		end
 
@@ -348,6 +351,7 @@ module Carson
 			end
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts worktree_parser
 			{ command: :invalid }
 		end
 
@@ -378,6 +382,7 @@ module Carson
 			{ command: "review:#{action}" }
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts review_parser
 			{ command: :invalid }
 		end
 
@@ -436,6 +441,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
 
@@ -468,6 +474,7 @@ module Carson
 			{ command: "audit", json: options[ :json ] }
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts audit_parser
 			{ command: :invalid }
 		end
 
@@ -499,6 +506,7 @@ module Carson
 			{ command: "sync", json: options[ :json ] }
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts sync_parser
 			{ command: :invalid }
 		end
 
@@ -530,28 +538,32 @@ module Carson
 			{ command: "status", json: options[ :json ] }
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts status_parser
 			{ command: :invalid }
 		end
 
 		# --- deliver ---
 
 		def self.parse_deliver_command( arguments:, error: )
-			options = { merge: false, json: false, title: nil, body_file: nil }
+			if arguments.include?( "--merge" )
+				error.puts "#{BADGE} carson deliver --merge is no longer supported; use carson deliver"
+				return { command: :invalid }
+			end
+
+			options = { json: false, title: nil, body_file: nil }
 			deliver_parser = OptionParser.new do |parser|
-				parser.banner = "Usage: carson deliver [--merge] [--json] [--title TITLE] [--body-file PATH]"
+				parser.banner = "Usage: carson deliver [--json] [--title TITLE] [--body-file PATH]"
 				parser.separator ""
-				parser.separator "Push the current branch, create a pull request, and optionally merge."
-				parser.separator "Collapses the manual push → PR → merge flow into a single command."
+				parser.separator "Push the current branch, create or refresh the pull request, and hand the branch to Carson."
+				parser.separator "Carson records delivery state and continues from there."
 				parser.separator ""
 				parser.separator "Options:"
-				parser.on( "--merge", "Also merge the PR if CI passes" ) { options[ :merge ] = true }
 				parser.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
 				parser.on( "--title TITLE", "PR title (defaults to branch name)" ) { |value| options[ :title ] = value }
 				parser.on( "--body-file PATH", "File containing PR body text" ) { |value| options[ :body_file ] = value }
 				parser.separator ""
 				parser.separator "Examples:"
-				parser.separator "    carson deliver               Push and open a PR"
-				parser.separator "    carson deliver --merge       Push, open a PR, and merge if CI passes"
+				parser.separator "    carson deliver               Push, open a PR, and register delivery state"
 			end
 			deliver_parser.parse!( arguments )
 			unless arguments.empty?
@@ -561,13 +573,13 @@ module Carson
 			end
 			{
 				command: "deliver",
-				merge: options.fetch( :merge ),
 				json: options.fetch( :json ),
 				title: options[ :title ],
 				body_file: options[ :body_file ]
 			}
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
+			error.puts deliver_parser
 			{ command: :invalid }
 		end
 
@@ -596,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 )
 
@@ -625,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]"
@@ -633,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
 
@@ -660,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 ""
@@ -745,7 +761,6 @@ module Carson
 				runtime.template_apply!( push_prep: parsed.fetch( :push_prep, false ) )
 			when "deliver"
 				runtime.deliver!(
-					merge: parsed.fetch( :merge, false ),
 					title: parsed.fetch( :title, nil ),
 					body_file: parsed.fetch( :body_file, nil ),
 					json_output: parsed.fetch( :json, false )
@@ -757,11 +772,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,16 +7,31 @@ 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,
 			:audit_advisory_check_names,
 			:workflow_style,
-			:govern_repos, :govern_auto_merge, :govern_merge_method,
-			:govern_agent_provider, :govern_dispatch_state_path,
+			:govern_repos, :govern_authority, :govern_merge_method,
+			:govern_agent_provider, :govern_state_path,
 			:govern_check_wait
 
 		def self.load( repo_root: )
@@ -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" => {
@@ -65,7 +83,7 @@ module Carson
 				},
 				"govern" => {
 					"repos" => [],
-					"auto_merge" => true,
+					"authority" => "remote",
 					"merge" => {
 						"method" => "squash"
 					},
@@ -74,7 +92,7 @@ module Carson
 						"codex" => {},
 						"claude" => {}
 					},
-					"dispatch_state_path" => "~/.carson/govern/dispatch_state.json",
+					"state_path" => "~/.carson/state.sqlite3",
 					"check_wait" => 30
 				}
 			}
@@ -153,8 +171,8 @@ module Carson
 			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?
-			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_authority = ENV.fetch( "CARSON_GOVERN_AUTHORITY", "" ).to_s.strip
+			govern[ "authority" ] = govern_authority unless govern_authority.empty?
 			govern_method = ENV.fetch( "CARSON_GOVERN_MERGE_METHOD", "" ).to_s.strip
 			unless govern_method.empty?
 				govern[ "merge" ] ||= {}
@@ -191,11 +209,17 @@ 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_path = fetch_string( hash: fetch_hash( hash: data, key: "hooks" ), key: "path" )
+			@hooks_path = resolve_runtime_path(
+				path: fetch_string( hash: fetch_hash( hash: data, key: "hooks" ), key: "path" ),
+				fallback_leaf: "hooks"
+			)
 			@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" )
@@ -219,13 +243,15 @@ 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_authority = fetch_string( hash: govern_hash, key: "authority" ).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
-			@govern_dispatch_state_path = safe_expand_path( dispatch_path )
+			@govern_state_path = resolve_runtime_path(
+				path: govern_hash.fetch( "state_path" ).to_s,
+				fallback_leaf: "state.sqlite3"
+			)
 			@govern_check_wait = fetch_non_negative_integer( hash: govern_hash, key: "check_wait" )
 
 			validate!
@@ -246,7 +272,8 @@ module Carson
 				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, "govern.merge.method must be one of merge, squash, rebase" unless [ "merge", "squash", "rebase" ].include?( govern_merge_method )
+				raise ConfigError, "govern.authority must be one of remote, local" unless [ "remote", "local" ].include?( govern_authority )
+				raise ConfigError, "govern.merge.method must be squash" unless govern_merge_method == "squash"
 				raise ConfigError, "govern.agent.provider must be one of auto, codex, claude" unless [ "auto", "codex", "claude" ].include?( govern_agent_provider )
 			end
 
@@ -298,13 +325,6 @@ module Carson
 			rescue ArgumentError, TypeError
 				raise ConfigError, "config key #{key} must be an integer"
 			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
 
 			def safe_expand_path( path )
 				return path unless path.start_with?( "~" )
@@ -314,6 +334,23 @@ module Carson
 				path
 			end
 
+			# Resolves Carson-owned runtime paths even when HOME is intentionally invalid.
+			# CI smoke uses that condition to verify TMPDIR and /tmp fallbacks.
+			def resolve_runtime_path( path:, fallback_leaf: )
+				expanded = safe_expand_path( path )
+				return expanded unless expanded.start_with?( "~" )
+
+				File.join( runtime_fallback_root, fallback_leaf )
+			end
+
+			# Shared fallback root for Carson-owned artefacts when HOME cannot be expanded.
+			def runtime_fallback_root
+				tmpdir = ENV.fetch( "TMPDIR", "" ).to_s.strip
+				return File.join( tmpdir, "carson" ) if tmpdir.start_with?( "/" )
+
+				"/tmp/carson"
+			end
+
 			# Returns an expanded path string, or nil when the value is absent/blank.
 			def fetch_optional_path( hash:, key: )
 				value = hash[ key ]
@@ -323,18 +360,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