carson 2.8.1 → 2.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76c0a5589cad84c4aaba1fee42bd667a21a55cea4840092b2984ae9eaeb84f6c
-  data.tar.gz: 656462b041f6764fd38780b500945ca0389b8235d741805367613051a27bd9da
+  metadata.gz: 9b99975ce01b36b30e333553f7c491ebbf92591a3bc7dbc492633984b80a807a
+  data.tar.gz: 55c64697792a9400be1fef45a68731ac7eab6be3be517c79ae2caebd5f5edc9c
 SHA512:
-  metadata.gz: 14cc66d4582c9ddfb9c5e87ec8e550d1f97cbcf6701a499e730dea4c06b5598ccdc6e8f61057a921ddba2d6ac9799fed4b3191a1a6dc1e440c4bc7249eec06bd
-  data.tar.gz: ce5e6f40342c08378830563ae0188cf61964d1f4650cc0be47a8cf52cb72f02b4f6413fa2b8d15a3dc70e3714628897446ab852ab7b276ac68a98cff0e5d1d54
+  metadata.gz: c716497d2db2c235dc5d8fa90c65fda8002722cabd7e8425305ce9c26917ebd48e905aed20564393d01178bd8d12257606097fdbf3ab1a77be71d1e48dc08681
+  data.tar.gz: 7f5358b84901463fbd1b211c3094df9c7c46566f9decc3a99d4d643264fc76e79de8b3c298d642c6efac41ecc16aa07647b52e66b6a822f7fff842345dfd9ab6

data/API.md

@@ -95,6 +95,7 @@ Environment overrides:
 - `CARSON_REVIEW_DISPOSITION_PREFIX`
 - `CARSON_REVIEW_SWEEP_WINDOW_DAYS`
 - `CARSON_REVIEW_SWEEP_STATES`
+- `CARSON_WORKFLOW_STYLE`
 - `CARSON_RUBY_INDENTATION`
 
 `lint.languages` schema:

data/MANUAL.md

@@ -212,6 +212,7 @@ Common environment overrides:
 | `CARSON_REVIEW_DISPOSITION_PREFIX` | Required prefix for disposition comments. |
 | `CARSON_REVIEW_SWEEP_WINDOW_DAYS` | Lookback window for review sweep. |
 | `CARSON_REVIEW_SWEEP_STATES` | PR states to include in sweep. |
+| `CARSON_WORKFLOW_STYLE` | Workflow style override (`branch` or `trunk`). |
 | `CARSON_RUBY_INDENTATION` | Ruby indentation policy (`tabs`, `spaces`, or `either`). |
 
 For the full configuration schema and `lint.languages` definition, see `API.md`.

data/RELEASE.md

@@ -5,6 +5,51 @@ Release-note scope rule:
 - `RELEASE.md` records only version deltas, breaking changes, and migration actions.
 - Operational usage guides live in `MANUAL.md` and `API.md`.
 
+## 2.10.0 — Lower Ruby Requirement to 3.4
+
+### What changed
+
+- **Minimum Ruby version lowered from 4.0 to 3.4.** Carson uses no Ruby 4.0-specific features. Lowering to 3.4 widens compatibility to the current stable Ruby series while enabling the `it` implicit block parameter.
+- **Removed `# frozen_string_literal: true` pragma** from the one file that had it (`lib/carson/policy/ruby/lint.rb`). Ruby 4.0 freezes strings by default; the pragma is unnecessary.
+- **Default workflow style now actually `branch` in code.** The 2.9.0 release notes documented this change, but the hooks and config default were not updated. Now fixed: hooks fall back to `branch`, config default is `branch`, and `CARSON_WORKFLOW_STYLE` env override is documented.
+
+### What users must do now
+
+1. Upgrade Carson to `2.10.0`.
+2. Ruby 3.4 or later is now sufficient — Ruby 4.0 is no longer required.
+
+## 2.9.0 — Concise UX for All Commands
+
+### What changed
+
+- **Concise output by default.** Every Carson command now prints clean, minimal output — what happened, what needs attention, what to do next. Diagnostic key-value lines are suppressed unless `--verbose` is passed.
+- **`--verbose` flag.** Global flag available on all commands. Restores full diagnostic output (same as pre-2.9.0 behaviour). The pre-commit hook runs `carson audit` (no flags) so it automatically gets clean output.
+- **Audit concise output.** A healthy audit prints one line (`Audit: ok`). Problems print only actionable summaries (e.g. `Hooks: mismatch — run carson prepare.`).
+- **Refresh concise output.** Prints ~5 lines: hooks installed, templates in sync, audit result, done.
+- **All other commands.** `prepare`, `inspect`, `offboard`, `template check/apply`, `prune`, `review gate/sweep`, `govern`, `lint setup`, `setup`, and `housekeep` all follow the same concise/verbose pattern.
+- **Default workflow style changed from `trunk` to `branch`.** All governed repositories now enforce PR-only merges by default. Direct commits, merge commits, and pushes to protected branches (`main`/`master`) are blocked by hooks unless explicitly opted out.
+
+### What users must do now
+
+1. Upgrade Carson to `2.9.0`.
+2. Use `--verbose` when you need full diagnostics (debugging, CI troubleshooting).
+3. If you rely on direct commits to main, re-run `carson setup` and choose `trunk`, or set `CARSON_WORKFLOW_STYLE=trunk` in your environment.
+
+### Breaking or removed behaviour
+
+- Default output is now concise. Scripts that parse Carson's key-value diagnostic lines must add `--verbose`.
+- Removed `@concise` internal flag (replaced by `--verbose` opt-in pattern).
+- Default `workflow.style` changed from `trunk` to `branch`. Repositories that previously relied on the implicit `trunk` default will now block direct commits to protected branches. Escape hatches: run `carson setup` to choose `trunk`, or set `CARSON_WORKFLOW_STYLE=trunk`.
+
+### Upgrade steps
+
+```bash
+cd ~/Dev/carson
+git pull
+bash install.sh
+carson version
+```
+
 ## 2.8.1 — Onboard UX and Install Cleanup
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-2.8.1
+2.10.0

data/carson.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
 	spec.description = "Carson runs outside host repositories and applies governance checks, review gates, and managed GitHub-native files."
 	spec.homepage = "https://github.com/wanghailei/carson"
 	spec.license = "MIT"
-	spec.required_ruby_version = ">= 4.0"
+	spec.required_ruby_version = ">= 3.4"
 	spec.metadata = {
 		"source_code_uri" => "https://github.com/wanghailei/carson",
 		"changelog_uri" => "https://github.com/wanghailei/carson/blob/main/RELEASE.md",

data/hooks/pre-merge-commit

@@ -2,7 +2,7 @@
 set -euo pipefail
 
 hooks_dir="$(cd "$(dirname "$0")" && pwd)"
-style="$(cat "$hooks_dir/workflow_style" 2>/dev/null || echo "trunk")"
+style="$(cat "$hooks_dir/workflow_style" 2>/dev/null || echo "branch")"
 [ "$style" = "trunk" ] && exit 0
 
 branch_name="$(git rev-parse --abbrev-ref HEAD)"

data/hooks/pre-push

@@ -2,7 +2,7 @@
 set -euo pipefail
 
 hooks_dir="$(cd "$(dirname "$0")" && pwd)"
-style="$(cat "$hooks_dir/workflow_style" 2>/dev/null || echo "trunk")"
+style="$(cat "$hooks_dir/workflow_style" 2>/dev/null || echo "branch")"
 [ "$style" = "trunk" ] && exit 0
 
 remote_name="${1:-unknown}"

data/hooks/prepare-commit-msg

@@ -2,7 +2,7 @@
 set -euo pipefail
 
 hooks_dir="$(cd "$(dirname "$0")" && pwd)"
-style="$(cat "$hooks_dir/workflow_style" 2>/dev/null || echo "trunk")"
+style="$(cat "$hooks_dir/workflow_style" 2>/dev/null || echo "branch")"
 [ "$style" = "trunk" ] && exit 0
 
 branch_name="$(git rev-parse --abbrev-ref HEAD)"

data/lib/carson/cli.rb

@@ -19,7 +19,8 @@ module Carson
 				return Runtime::EXIT_ERROR
 			end
 
-			runtime = Runtime.new( repo_root: target_repo_root, tool_root: tool_root, out: out, err: err )
+			verbose = parsed.fetch( :verbose, false )
+			runtime = Runtime.new( repo_root: target_repo_root, tool_root: tool_root, out: out, err: err, verbose: verbose )
 			dispatch( parsed: parsed, runtime: runtime )
 		rescue ConfigError => e
 			err.puts "#{BADGE} CONFIG ERROR: #{e.message}"
@@ -30,12 +31,14 @@ module Carson
 		end
 
 		def self.parse_args( argv:, out:, err: )
+			verbose = argv.delete( "--verbose" ) ? true : false
 			parser = build_parser
 			preset = parse_preset_command( argv: argv, out: out, parser: parser )
-			return preset unless preset.nil?
+			return preset.merge( verbose: verbose ) unless preset.nil?
 
 			command = argv.shift
-			parse_command( command: command, argv: argv, parser: parser, err: err )
+			result = parse_command( command: command, argv: argv, parser: parser, err: err )
+			result.merge( verbose: verbose )
 		rescue OptionParser::ParseError => e
 			err.puts "#{BADGE} #{e.message}"
 			err.puts parser

data/lib/carson/config.rb

@@ -53,7 +53,7 @@ module Carson
 					"languages" => default_lint_languages_data
 				},
 				"workflow" => {
-					"style" => "trunk"
+					"style" => "branch"
 				},
 				"review" => {
 					"bot_usernames" => [],

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

@@ -1,5 +1,4 @@
 #!/usr/bin/env ruby
-# frozen_string_literal: true
 
 require "open3"
 

data/lib/carson/runtime/audit.rb

@@ -8,42 +8,62 @@ module Carson
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
 				audit_state = "ok"
-				print_header "Repository"
-				puts_line "root: #{repo_root}"
-				puts_line "current_branch: #{current_branch}"
-				print_header "Working Tree"
-				puts_line git_capture!( "status", "--short", "--branch" ).strip
-				print_header "Hooks"
+				audit_concise_problems = []
+				puts_verbose ""
+				puts_verbose "[Repository]"
+				puts_verbose "root: #{repo_root}"
+				puts_verbose "current_branch: #{current_branch}"
+				puts_verbose ""
+				puts_verbose "[Working Tree]"
+				puts_verbose git_capture!( "status", "--short", "--branch" ).strip
+				puts_verbose ""
+				puts_verbose "[Hooks]"
 				hooks_ok = hooks_health_report
-				audit_state = "block" unless hooks_ok
-				print_header "Local Lint Quality"
+				unless hooks_ok
+					audit_state = "block"
+					audit_concise_problems << "Hooks: mismatch — run carson prepare."
+				end
+				puts_verbose ""
+				puts_verbose "[Local Lint Quality]"
 				local_lint_quality = local_lint_quality_report
-				audit_state = "block" if local_lint_quality.fetch( :status ) == "block"
-				print_header "Main Sync Status"
+				if local_lint_quality.fetch( :status ) == "block"
+					audit_state = "block"
+					blocking_langs = local_lint_quality.fetch( :languages ).select { |l| l.fetch( :status ) == "block" }
+					blocking_langs.each do |lang|
+						exit_code = lang.fetch( :exit_code, 1 )
+						audit_concise_problems << "Lint: #{lang.fetch( :language )} failed (exit #{exit_code})."
+					end
+				end
+				puts_verbose ""
+				puts_verbose "[Main Sync Status]"
 				ahead_count, behind_count, main_error = main_sync_counts
 				if main_error
-					puts_line "main_vs_remote_main: unknown"
-					puts_line "WARN: unable to calculate main sync status (#{main_error})."
+					puts_verbose "main_vs_remote_main: unknown"
+					puts_verbose "WARN: unable to calculate main sync status (#{main_error})."
 					audit_state = "attention" if audit_state == "ok"
 				elsif ahead_count.positive?
-					puts_line "main_vs_remote_main_ahead: #{ahead_count}"
-					puts_line "main_vs_remote_main_behind: #{behind_count}"
-					puts_line "ACTION: local #{config.main_branch} is ahead of #{config.git_remote}/#{config.main_branch} by #{ahead_count} commit#{plural_suffix( count: ahead_count )}; reset local drift before commit/push workflows."
+					puts_verbose "main_vs_remote_main_ahead: #{ahead_count}"
+					puts_verbose "main_vs_remote_main_behind: #{behind_count}"
+					puts_verbose "ACTION: local #{config.main_branch} is ahead of #{config.git_remote}/#{config.main_branch} by #{ahead_count} commit#{plural_suffix( count: ahead_count )}; reset local drift before commit/push workflows."
 					audit_state = "block"
+					audit_concise_problems << "Main sync: ahead by #{ahead_count} — reset local drift."
 				elsif behind_count.positive?
-					puts_line "main_vs_remote_main_ahead: #{ahead_count}"
-					puts_line "main_vs_remote_main_behind: #{behind_count}"
-					puts_line "ACTION: local #{config.main_branch} is behind #{config.git_remote}/#{config.main_branch} by #{behind_count} commit#{plural_suffix( count: behind_count )}; run carson sync."
+					puts_verbose "main_vs_remote_main_ahead: #{ahead_count}"
+					puts_verbose "main_vs_remote_main_behind: #{behind_count}"
+					puts_verbose "ACTION: local #{config.main_branch} is behind #{config.git_remote}/#{config.main_branch} by #{behind_count} commit#{plural_suffix( count: behind_count )}; run carson sync."
 					audit_state = "attention" if audit_state == "ok"
+					audit_concise_problems << "Main sync: behind by #{behind_count} — run carson sync."
 				else
-					puts_line "main_vs_remote_main_ahead: 0"
-					puts_line "main_vs_remote_main_behind: 0"
-					puts_line "ACTION: local #{config.main_branch} is in sync with #{config.git_remote}/#{config.main_branch}."
+					puts_verbose "main_vs_remote_main_ahead: 0"
+					puts_verbose "main_vs_remote_main_behind: 0"
+					puts_verbose "ACTION: local #{config.main_branch} is in sync with #{config.git_remote}/#{config.main_branch}."
 				end
-				print_header "PR and Required Checks (gh)"
+				puts_verbose ""
+				puts_verbose "[PR and Required Checks (gh)]"
 				monitor_report = pr_and_check_report
 				audit_state = "attention" if audit_state == "ok" && monitor_report.fetch( :status ) != "ok"
-				print_header "Default Branch CI Baseline (gh)"
+				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"
@@ -56,9 +76,14 @@ module Carson
 							audit_status: audit_state
 						)
 					)
-				print_header "Audit Result"
-				puts_line "status: #{audit_state}"
-				puts_line( audit_state == "block" ? "ACTION: local policy block must be resolved before commit/push." : "ACTION: no local hard block detected." )
+				puts_verbose ""
+				puts_verbose "[Audit Result]"
+				puts_verbose "status: #{audit_state}"
+				puts_verbose( audit_state == "block" ? "ACTION: local policy block must be resolved before commit/push." : "ACTION: no local hard block detected." )
+				unless verbose?
+					audit_concise_problems.each { |problem| puts_line problem }
+					puts_line "Audit: #{audit_state}"
+				end
 				audit_state == "block" ? EXIT_BLOCK : EXIT_OK
 			end
 
@@ -83,7 +108,7 @@ module Carson
 				unless gh_available?
 					report[ :status ] = "skipped"
 					report[ :skip_reason ] = "gh CLI not available in PATH"
-					puts_line "SKIP: #{report.fetch( :skip_reason )}"
+					puts_verbose "SKIP: #{report.fetch( :skip_reason )}"
 					return report
 				end
 				pr_stdout, pr_stderr, pr_success, = gh_run( "pr", "view", current_branch, "--json", "number,title,url,state,reviewDecision" )
@@ -91,7 +116,7 @@ module Carson
 					error_text = gh_error_text( stdout_text: pr_stdout, stderr_text: pr_stderr, fallback: "unable to read PR for branch #{current_branch}" )
 					report[ :status ] = "skipped"
 					report[ :skip_reason ] = error_text
-					puts_line "SKIP: #{error_text}"
+					puts_verbose "SKIP: #{error_text}"
 					return report
 				end
 				pr_data = JSON.parse( pr_stdout )
@@ -102,16 +127,16 @@ module Carson
 				state: pr_data[ "state" ].to_s,
 				review_decision: blank_to( value: pr_data[ "reviewDecision" ], default: "NONE" )
 				}
-				puts_line "pr: ##{report.dig( :pr, :number )} #{report.dig( :pr, :title )}"
-				puts_line "url: #{report.dig( :pr, :url )}"
-				puts_line "review_decision: #{report.dig( :pr, :review_decision )}"
+				puts_verbose "pr: ##{report.dig( :pr, :number )} #{report.dig( :pr, :title )}"
+				puts_verbose "url: #{report.dig( :pr, :url )}"
+				puts_verbose "review_decision: #{report.dig( :pr, :review_decision )}"
 				checks_stdout, checks_stderr, checks_success, checks_exit = gh_run( "pr", "checks", report.dig( :pr, :number ).to_s, "--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" )
 					report[ :checks ][ :status ] = "skipped"
 					report[ :checks ][ :skip_reason ] = error_text
 					report[ :status ] = "attention"
-					puts_line "checks: SKIP (#{error_text})"
+					puts_verbose "checks: SKIP (#{error_text})"
 					return report
 				end
 				checks_data = JSON.parse( checks_stdout )
@@ -123,17 +148,17 @@ module Carson
 				report[ :checks ][ :pending_count ] = pending.count
 				report[ :checks ][ :failing ] = normalise_check_entries( entries: failing )
 				report[ :checks ][ :pending ] = normalise_check_entries( entries: pending )
-				puts_line "required_checks_total: #{report.dig( :checks, :required_total )}"
-				puts_line "required_checks_failing: #{report.dig( :checks, :failing_count )}"
-				puts_line "required_checks_pending: #{report.dig( :checks, :pending_count )}"
-				report.dig( :checks, :failing ).each { |entry| puts_line "check_fail: #{entry.fetch( :workflow )} / #{entry.fetch( :name )} #{entry.fetch( :link )}".strip }
-				report.dig( :checks, :pending ).each { |entry| puts_line "check_pending: #{entry.fetch( :workflow )} / #{entry.fetch( :name )} #{entry.fetch( :link )}".strip }
+				puts_verbose "required_checks_total: #{report.dig( :checks, :required_total )}"
+				puts_verbose "required_checks_failing: #{report.dig( :checks, :failing_count )}"
+				puts_verbose "required_checks_pending: #{report.dig( :checks, :pending_count )}"
+				report.dig( :checks, :failing ).each { |entry| puts_verbose "check_fail: #{entry.fetch( :workflow )} / #{entry.fetch( :name )} #{entry.fetch( :link )}".strip }
+				report.dig( :checks, :pending ).each { |entry| puts_verbose "check_pending: #{entry.fetch( :workflow )} / #{entry.fetch( :name )} #{entry.fetch( :link )}".strip }
 				report[ :status ] = "attention" if report.dig( :checks, :failing_count ).positive? || report.dig( :checks, :pending_count ).positive?
 				report
 				rescue JSON::ParserError => e
 					report[ :status ] = "skipped"
 					report[ :skip_reason ] = "invalid gh JSON response (#{e.message})"
-					puts_line "SKIP: #{report.fetch( :skip_reason )}"
+					puts_verbose "SKIP: #{report.fetch( :skip_reason )}"
 					report
 				end
 
@@ -148,8 +173,8 @@ module Carson
 					blocking_languages: 0,
 					languages: []
 				}
-				puts_line "lint_target_source: #{target_source}"
-				puts_line "lint_target_files_total: #{target_files.count}"
+				puts_verbose "lint_target_source: #{target_source}"
+				puts_verbose "lint_target_files_total: #{target_files.count}"
 				config.lint_languages.each do |language, entry|
 					language_report = lint_language_report(
 						language: language,
@@ -162,7 +187,7 @@ module Carson
 					report[ :status ] = "block"
 					report[ :blocking_languages ] += 1
 				end
-				puts_line "lint_blocking_languages: #{report.fetch( :blocking_languages )}"
+				puts_verbose "lint_blocking_languages: #{report.fetch( :blocking_languages )}"
 				report
 			rescue StandardError => e
 				report ||= {
@@ -191,7 +216,7 @@ module Carson
 				if github_pull_request_event?
 					files = lint_target_files_for_pull_request
 					return [ files, "github_pull_request" ] unless files.nil?
-					puts_line "WARN: unable to resolve pull request changed files; falling back to full repository files."
+					puts_verbose "WARN: unable to resolve pull request changed files; falling back to full repository files."
 				end
 
 				if github_actions_environment?
@@ -265,16 +290,16 @@ module Carson
 					config_files: entry.fetch( :config_files ),
 					exit_code: 0
 				}
-				puts_line "lint_language: #{language} enabled=#{report.fetch( :enabled )} files=#{report.fetch( :file_count )}"
+				puts_verbose "lint_language: #{language} enabled=#{report.fetch( :enabled )} files=#{report.fetch( :file_count )}"
 				if language == "ruby" && outsider_mode?
 					local_rubocop_path = File.join( repo_root, ".rubocop.yml" )
 					if File.file?( local_rubocop_path )
 						report[ :status ] = "block"
 						report[ :reason ] = "repo-local RuboCop config is forbidden: #{relative_path( local_rubocop_path )}; remove it and use ~/.carson/lint/rubocop.yml."
 						report[ :exit_code ] = EXIT_BLOCK
-						puts_line "lint_#{language}_status: block"
-						puts_line "lint_#{language}_reason: #{report.fetch( :reason )}"
-						puts_line "ACTION: remove .rubocop.yml from this repository and run carson lint setup --source <path-or-git-url>."
+						puts_verbose "lint_#{language}_status: block"
+						puts_verbose "lint_#{language}_reason: #{report.fetch( :reason )}"
+						puts_verbose "ACTION: remove .rubocop.yml from this repository and run carson lint setup --source <path-or-git-url>."
 						return report
 					end
 				end
@@ -286,9 +311,9 @@ module Carson
 					report[ :status ] = "block"
 					report[ :reason ] = "missing config files: #{missing_config_files.join( ', ' )}"
 					report[ :exit_code ] = EXIT_BLOCK
-					puts_line "lint_#{language}_status: block"
-					puts_line "lint_#{language}_reason: #{report.fetch( :reason )}"
-					puts_line "ACTION: run carson lint setup --source <path-or-git-url> to prepare ~/.carson/lint policy files."
+					puts_verbose "lint_#{language}_status: block"
+					puts_verbose "lint_#{language}_reason: #{report.fetch( :reason )}"
+					puts_verbose "ACTION: run carson lint setup --source <path-or-git-url> to prepare ~/.carson/lint policy files."
 					return report
 				end
 
@@ -298,16 +323,16 @@ module Carson
 					report[ :status ] = "block"
 					report[ :reason ] = "missing lint command"
 					report[ :exit_code ] = EXIT_BLOCK
-					puts_line "lint_#{language}_status: block"
-					puts_line "lint_#{language}_reason: #{report.fetch( :reason )}"
+					puts_verbose "lint_#{language}_status: block"
+					puts_verbose "lint_#{language}_reason: #{report.fetch( :reason )}"
 					return report
 				end
 				unless command_available_for_lint?( command_name: command_name )
 					report[ :status ] = "block"
 					report[ :reason ] = "command not available: #{command_name}"
 					report[ :exit_code ] = EXIT_BLOCK
-					puts_line "lint_#{language}_status: block"
-					puts_line "lint_#{language}_reason: #{report.fetch( :reason )}"
+					puts_verbose "lint_#{language}_status: block"
+					puts_verbose "lint_#{language}_reason: #{report.fetch( :reason )}"
 					return report
 				end
 
@@ -322,9 +347,9 @@ module Carson
 						fallback: "lint command failed for #{language}"
 					)
 				end
-				puts_line "lint_#{language}_status: #{report.fetch( :status )}"
-				puts_line "lint_#{language}_exit: #{report.fetch( :exit_code )}"
-				puts_line "lint_#{language}_reason: #{report.fetch( :reason )}" unless report.fetch( :reason ).nil?
+				puts_verbose "lint_#{language}_status: #{report.fetch( :status )}"
+				puts_verbose "lint_#{language}_exit: #{report.fetch( :exit_code )}"
+				puts_verbose "lint_#{language}_reason: #{report.fetch( :reason )}" unless report.fetch( :reason ).nil?
 				report
 			end
 
@@ -405,7 +430,7 @@ module Carson
 				unless gh_available?
 					report[ :status ] = "skipped"
 					report[ :skip_reason ] = "gh CLI not available in PATH"
-					puts_line "baseline: SKIP (#{report.fetch( :skip_reason )})"
+					puts_verbose "baseline: SKIP (#{report.fetch( :skip_reason )})"
 					return report
 				end
 				owner, repo = repository_coordinates
@@ -455,32 +480,32 @@ module Carson
 				report[ :status ] = "block" if report.fetch( :pending_count ).positive?
 				report[ :status ] = "block" if report.fetch( :no_check_evidence )
 				report[ :status ] = "attention" if report.fetch( :status ) == "ok" && ( report.fetch( :advisory_failing_count ).positive? || report.fetch( :advisory_pending_count ).positive? )
-				puts_line "default_branch_repository: #{report.fetch( :repository )}"
-				puts_line "default_branch_name: #{report.fetch( :default_branch )}"
-				puts_line "default_branch_head_sha: #{report.fetch( :head_sha )}"
-				puts_line "default_branch_workflows_total: #{report.fetch( :workflows_total )}"
-				puts_line "default_branch_check_runs_total: #{report.fetch( :check_runs_total )}"
-				puts_line "default_branch_failing: #{report.fetch( :failing_count )}"
-				puts_line "default_branch_pending: #{report.fetch( :pending_count )}"
-				puts_line "default_branch_advisory_failing: #{report.fetch( :advisory_failing_count )}"
-				puts_line "default_branch_advisory_pending: #{report.fetch( :advisory_pending_count )}"
-				report.fetch( :failing ).each { |entry| puts_line "default_branch_check_fail: #{entry.fetch( :workflow )} / #{entry.fetch( :name )} #{entry.fetch( :link )}".strip }
-				report.fetch( :pending ).each { |entry| puts_line "default_branch_check_pending: #{entry.fetch( :workflow )} / #{entry.fetch( :name )} #{entry.fetch( :link )}".strip }
-				report.fetch( :advisory_failing ).each { |entry| puts_line "default_branch_check_advisory_fail: #{entry.fetch( :workflow )} / #{entry.fetch( :name )} (advisory) #{entry.fetch( :link )}".strip }
-				report.fetch( :advisory_pending ).each { |entry| puts_line "default_branch_check_advisory_pending: #{entry.fetch( :workflow )} / #{entry.fetch( :name )} (advisory) #{entry.fetch( :link )}".strip }
+				puts_verbose "default_branch_repository: #{report.fetch( :repository )}"
+				puts_verbose "default_branch_name: #{report.fetch( :default_branch )}"
+				puts_verbose "default_branch_head_sha: #{report.fetch( :head_sha )}"
+				puts_verbose "default_branch_workflows_total: #{report.fetch( :workflows_total )}"
+				puts_verbose "default_branch_check_runs_total: #{report.fetch( :check_runs_total )}"
+				puts_verbose "default_branch_failing: #{report.fetch( :failing_count )}"
+				puts_verbose "default_branch_pending: #{report.fetch( :pending_count )}"
+				puts_verbose "default_branch_advisory_failing: #{report.fetch( :advisory_failing_count )}"
+				puts_verbose "default_branch_advisory_pending: #{report.fetch( :advisory_pending_count )}"
+				report.fetch( :failing ).each { |entry| puts_verbose "default_branch_check_fail: #{entry.fetch( :workflow )} / #{entry.fetch( :name )} #{entry.fetch( :link )}".strip }
+				report.fetch( :pending ).each { |entry| puts_verbose "default_branch_check_pending: #{entry.fetch( :workflow )} / #{entry.fetch( :name )} #{entry.fetch( :link )}".strip }
+				report.fetch( :advisory_failing ).each { |entry| puts_verbose "default_branch_check_advisory_fail: #{entry.fetch( :workflow )} / #{entry.fetch( :name )} (advisory) #{entry.fetch( :link )}".strip }
+				report.fetch( :advisory_pending ).each { |entry| puts_verbose "default_branch_check_advisory_pending: #{entry.fetch( :workflow )} / #{entry.fetch( :name )} (advisory) #{entry.fetch( :link )}".strip }
 				if report.fetch( :no_check_evidence )
-					puts_line "ACTION: default branch has workflow files but no check-runs; align workflow triggers and branch protection check names."
+					puts_verbose "ACTION: default branch has workflow files but no check-runs; align workflow triggers and branch protection check names."
 				end
 				report
 			rescue JSON::ParserError => e
 				report[ :status ] = "skipped"
 				report[ :skip_reason ] = "invalid gh JSON response (#{e.message})"
-				puts_line "baseline: SKIP (#{report.fetch( :skip_reason )})"
+				puts_verbose "baseline: SKIP (#{report.fetch( :skip_reason )})"
 				report
 			rescue StandardError => e
 				report[ :status ] = "skipped"
 				report[ :skip_reason ] = e.message
-				puts_line "baseline: SKIP (#{report.fetch( :skip_reason )})"
+				puts_verbose "baseline: SKIP (#{report.fetch( :skip_reason )})"
 				report
 			end
 
@@ -577,10 +602,10 @@ module Carson
 			# Writes monitor report artefacts and prints their locations.
 			def write_and_print_pr_monitor_report( report: )
 				markdown_path, json_path = write_pr_monitor_report( report: report )
-				puts_line "report_markdown: #{markdown_path}"
-				puts_line "report_json: #{json_path}"
+				puts_verbose "report_markdown: #{markdown_path}"
+				puts_verbose "report_json: #{json_path}"
 			rescue StandardError => e
-				puts_line "report_write: SKIP (#{e.message})"
+				puts_verbose "report_write: SKIP (#{e.message})"
 			end
 
 			# Persists report in both machine-readable JSON and human-readable Markdown.
@@ -703,28 +728,29 @@ module Carson
 				return { status: "ok", split_required: false } if files.empty?
 
 				scope = scope_integrity_status( files: files, branch: current_branch )
-				print_header "Scope Integrity Guard"
-				puts_line "scope_file_source: #{files_source}"
-				puts_line "scope_file_count: #{files.count}"
-				puts_line "branch: #{scope.fetch( :branch )}"
-				puts_line "scope_basis: changed_paths_only"
-				puts_line "detected_groups: #{scope.fetch( :detected_groups ).sort.join( ', ' )}"
-				puts_line "core_groups: #{scope.fetch( :core_groups ).empty? ? 'none' : scope.fetch( :core_groups ).sort.join( ', ' )}"
-				puts_line "non_doc_groups: #{scope.fetch( :non_doc_groups ).empty? ? 'none' : scope.fetch( :non_doc_groups ).sort.join( ', ' )}"
-				puts_line "docs_only_changes: #{scope.fetch( :docs_only )}"
-				puts_line "unmatched_paths_count: #{scope.fetch( :unmatched_paths ).count}"
-				scope.fetch( :unmatched_paths ).each { |path| puts_line "unmatched_path: #{path}" }
-				puts_line "violating_files_count: #{scope.fetch( :violating_files ).count}"
-				scope.fetch( :violating_files ).each { |path| puts_line "violating_file: #{path} (group=#{scope.fetch( :grouped_paths ).fetch( path )})" }
-				puts_line "checklist_single_business_intent: pass"
-				puts_line "checklist_single_scope_group: #{scope.fetch( :split_required ) ? 'advisory' : 'pass'}"
-				puts_line "checklist_cross_boundary_changes_justified: #{( scope.fetch( :split_required ) || scope.fetch( :misc_present ) ) ? 'advisory' : 'pass'}"
+				puts_verbose ""
+				puts_verbose "[Scope Integrity Guard]"
+				puts_verbose "scope_file_source: #{files_source}"
+				puts_verbose "scope_file_count: #{files.count}"
+				puts_verbose "branch: #{scope.fetch( :branch )}"
+				puts_verbose "scope_basis: changed_paths_only"
+				puts_verbose "detected_groups: #{scope.fetch( :detected_groups ).sort.join( ', ' )}"
+				puts_verbose "core_groups: #{scope.fetch( :core_groups ).empty? ? 'none' : scope.fetch( :core_groups ).sort.join( ', ' )}"
+				puts_verbose "non_doc_groups: #{scope.fetch( :non_doc_groups ).empty? ? 'none' : scope.fetch( :non_doc_groups ).sort.join( ', ' )}"
+				puts_verbose "docs_only_changes: #{scope.fetch( :docs_only )}"
+				puts_verbose "unmatched_paths_count: #{scope.fetch( :unmatched_paths ).count}"
+				scope.fetch( :unmatched_paths ).each { |path| puts_verbose "unmatched_path: #{path}" }
+				puts_verbose "violating_files_count: #{scope.fetch( :violating_files ).count}"
+				scope.fetch( :violating_files ).each { |path| puts_verbose "violating_file: #{path} (group=#{scope.fetch( :grouped_paths ).fetch( path )})" }
+				puts_verbose "checklist_single_business_intent: pass"
+				puts_verbose "checklist_single_scope_group: #{scope.fetch( :split_required ) ? 'advisory' : 'pass'}"
+				puts_verbose "checklist_cross_boundary_changes_justified: #{( scope.fetch( :split_required ) || scope.fetch( :misc_present ) ) ? 'advisory' : 'pass'}"
 				if scope.fetch( :split_required )
-					puts_line "ACTION: multiple module groups detected (informational only)."
+					puts_verbose "ACTION: multiple module groups detected (informational only)."
 				elsif scope.fetch( :misc_present )
-					puts_line "ACTION: unmatched paths detected; classify via scope.path_groups for stricter module checks."
+					puts_verbose "ACTION: unmatched paths detected; classify via scope.path_groups for stricter module checks."
 				else
-					puts_line "ACTION: scope integrity is within commit policy."
+					puts_verbose "ACTION: scope integrity is within commit policy."
 				end
 				{ status: scope.fetch( :status ), split_required: scope.fetch( :split_required ) }
 			end

data/lib/carson/runtime/govern.rb

@@ -83,7 +83,8 @@ module Carson
 
 			# Standalone housekeep: sync + prune.
 			def housekeep!
-				print_header "Housekeep"
+				puts_verbose ""
+				puts_verbose "[Housekeep]"
 				sync_status = sync!
 				if sync_status != EXIT_OK
 					puts_line "housekeep: sync returned #{sync_status}; skipping prune."
@@ -571,8 +572,8 @@ module Carson
 				md_path = File.join( report_dir, GOVERN_REPORT_MD )
 				File.write( json_path, JSON.pretty_generate( report ) )
 				File.write( md_path, render_govern_markdown( report: report ) )
-				puts_line "report_json: #{json_path}"
-				puts_line "report_markdown: #{md_path}"
+				puts_verbose "report_json: #{json_path}"
+				puts_verbose "report_markdown: #{md_path}"
 			end
 
 			def render_govern_markdown( report: )
@@ -632,7 +633,11 @@ module Carson
 				end
 
 				repos_count = Array( report[ :repos ] ).length
-				puts_line "govern_summary: repos=#{repos_count} prs=#{total_prs} ready=#{ready_count} blocked=#{blocked_count}"
+				if verbose?
+					puts_line "govern_summary: repos=#{repos_count} prs=#{total_prs} ready=#{ready_count} blocked=#{blocked_count}"
+				else
+					puts_line "Govern: #{repos_count} repo#{plural_suffix( count: repos_count )}, #{total_prs} PR#{plural_suffix( count: total_prs )} (#{ready_count} ready, #{blocked_count} blocked)"
+				end
 			end
 		end
 

data/lib/carson/runtime/lint.rb

@@ -7,7 +7,8 @@ module Carson
 		module Lint
 			# Prepares canonical lint policy files under ~/.carson/lint from an explicit source.
 			def lint_setup!( source:, ref: "main", force: false )
-				print_header "Lint Setup"
+				puts_verbose ""
+				puts_verbose "[Lint Setup]"
 				source_text = source.to_s.strip
 				if source_text.empty?
 					puts_line "ERROR: lint setup requires --source <path-or-git-url>."
@@ -29,12 +30,12 @@ module Carson
 						target_coding_dir: target_coding_dir,
 						force: force
 					)
-					puts_line "lint_setup_source: #{source_text}"
-					puts_line "lint_setup_ref: #{ref_text}" if lint_source_git_url?( source: source_text )
-					puts_line "lint_setup_target: #{target_coding_dir}"
-					puts_line "lint_setup_created: #{copy_result.fetch( :created )}"
-					puts_line "lint_setup_updated: #{copy_result.fetch( :updated )}"
-					puts_line "lint_setup_skipped: #{copy_result.fetch( :skipped )}"
+					puts_verbose "lint_setup_source: #{source_text}"
+					puts_verbose "lint_setup_ref: #{ref_text}" if lint_source_git_url?( source: source_text )
+					puts_verbose "lint_setup_target: #{target_coding_dir}"
+					puts_verbose "lint_setup_created: #{copy_result.fetch( :created )}"
+					puts_verbose "lint_setup_updated: #{copy_result.fetch( :updated )}"
+					puts_verbose "lint_setup_skipped: #{copy_result.fetch( :skipped )}"
 
 					missing_policy = missing_lint_policy_files
 					if missing_policy.empty?
@@ -43,7 +44,7 @@ module Carson
 					end
 
 					missing_policy.each do |entry|
-						puts_line "missing_lint_policy_file: language=#{entry.fetch( :language )} path=#{entry.fetch( :path )}"
+						puts_verbose "missing_lint_policy_file: language=#{entry.fetch( :language )} path=#{entry.fetch( :path )}"
 					end
 					puts_line "ACTION: update source CODING policy files, rerun carson lint setup, then rerun carson audit."
 					EXIT_ERROR

data/lib/carson/runtime/local.rb

@@ -43,12 +43,19 @@ module Carson
 				return prune_no_stale_branches if stale_branches.empty?
 
 				counters = prune_stale_branch_entries( stale_branches: stale_branches, active_branch: active_branch )
-				puts_line "prune_summary: deleted=#{counters.fetch( :deleted )} skipped=#{counters.fetch( :skipped )}"
+				puts_verbose "prune_summary: deleted=#{counters.fetch( :deleted )} skipped=#{counters.fetch( :skipped )}"
+				unless verbose?
+					puts_line "Pruned #{counters.fetch( :deleted )} stale branch#{plural_suffix( count: counters.fetch( :deleted ) )}."
+				end
 				EXIT_OK
 			end
 
 			def prune_no_stale_branches
-				puts_line "OK: no stale local branches tracking deleted #{config.git_remote} branches."
+				if verbose?
+					puts_line "OK: no stale local branches tracking deleted #{config.git_remote} branches."
+				else
+					puts_line "No stale branches."
+				end
 				EXIT_OK
 			end
 
@@ -72,7 +79,7 @@ module Carson
 
 			def prune_skip_stale_branch( type:, branch:, upstream: )
 				status = type == :protected ? "skip_protected_branch" : "skip_current_branch"
-				puts_line "#{status}: #{branch} (upstream=#{upstream})"
+				puts_verbose "#{status}: #{branch} (upstream=#{upstream})"
 				:skipped
 			end
 
@@ -89,8 +96,8 @@ module Carson
 			end
 
 			def prune_safe_delete_success( branch:, upstream:, stdout_text: )
-				out.print stdout_text unless stdout_text.empty?
-				puts_line "deleted_local_branch: #{branch} (upstream=#{upstream})"
+				out.print stdout_text if verbose? && !stdout_text.empty?
+				puts_verbose "deleted_local_branch: #{branch} (upstream=#{upstream})"
 				:deleted
 			end
 
@@ -108,20 +115,20 @@ module Carson
 			end
 
 			def prune_force_delete_success( branch:, upstream:, merged_pr:, force_stdout: )
-				out.print force_stdout unless force_stdout.empty?
-				puts_line "deleted_local_branch_force: #{branch} (upstream=#{upstream}) merged_pr=#{merged_pr.fetch( :url )}"
+				out.print force_stdout if verbose? && !force_stdout.empty?
+				puts_verbose "deleted_local_branch_force: #{branch} (upstream=#{upstream}) merged_pr=#{merged_pr.fetch( :url )}"
 				:deleted
 			end
 
 			def prune_force_delete_failed( branch:, upstream:, force_stderr: )
 				force_error_text = normalise_branch_delete_error( error_text: force_stderr )
-				puts_line "fail_force_delete_branch: #{branch} (upstream=#{upstream}) reason=#{force_error_text}"
+				puts_verbose "fail_force_delete_branch: #{branch} (upstream=#{upstream}) reason=#{force_error_text}"
 				:skipped
 			end
 
 			def prune_force_delete_skipped( branch:, upstream:, delete_error_text:, force_error: )
-				puts_line "skip_delete_branch: #{branch} (upstream=#{upstream}) reason=#{delete_error_text}"
-				puts_line "skip_force_delete_branch: #{branch} (upstream=#{upstream}) reason=#{force_error}" unless force_error.to_s.strip.empty?
+				puts_verbose "skip_delete_branch: #{branch} (upstream=#{upstream}) reason=#{delete_error_text}"
+				puts_verbose "skip_force_delete_branch: #{branch} (upstream=#{upstream}) reason=#{force_error}" unless force_error.to_s.strip.empty?
 				:skipped
 			end
 
@@ -153,12 +160,15 @@ module Carson
 					target_path = File.join( hooks_dir, hook_name )
 					FileUtils.cp( source_path, target_path )
 					FileUtils.chmod( 0o755, target_path )
-					puts_line "hook_written: #{relative_path( target_path )}" unless concise?
+					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_line "configured_hooks_path: #{hooks_dir}" unless concise?
-				return EXIT_OK if concise?
+				puts_verbose "configured_hooks_path: #{hooks_dir}"
+				unless verbose?
+					puts_line "Hooks installed (#{config.required_hooks.count} hooks)."
+					return EXIT_OK
+				end
 
 				inspect!
 			end
@@ -188,8 +198,6 @@ module Carson
 				end
 
 				onboard_apply!
-			ensure
-				@concise = false
 			end
 
 			# Re-applies hooks, templates, and audit after upgrading Carson.
@@ -197,29 +205,52 @@ module Carson
 				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!
+
+				if verbose?
+					puts_verbose ""
+					puts_verbose "[Refresh]"
+					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
+					return audit_status
+				end
+
+				puts_line "Refresh"
+				hook_status = with_captured_output { prepare! }
 				return hook_status unless hook_status == EXIT_OK
+				puts_line "Hooks installed (#{config.required_hooks.count} hooks)."
 
-				template_status = template_apply!
+				template_drift_count = template_results.count { |entry| entry.fetch( :status ) != "ok" }
+				template_status = with_captured_output { template_apply! }
 				return template_status unless template_status == EXIT_OK
+				if template_drift_count.positive?
+					puts_line "Templates applied (#{template_drift_count} updated)."
+				else
+					puts_line "Templates in sync."
+				end
 
 				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
+				puts_line "Refresh complete."
 				audit_status
 			end
 
 			# Removes Carson-managed repository integration so a host repository can retire Carson cleanly.
 			def offboard!
-				print_header "Offboard"
+				puts_verbose ""
+				puts_verbose "[Offboard]"
 				unless inside_git_work_tree?
 					puts_line "ERROR: #{repo_root} is not a git repository."
 					return EXIT_ERROR
@@ -233,16 +264,20 @@ module Carson
 					absolute = resolve_repo_path!( relative_path: relative, label: "offboard target #{relative}" )
 					if File.exist?( absolute )
 						FileUtils.rm_rf( absolute )
-						puts_line "removed_path: #{relative}"
+						puts_verbose "removed_path: #{relative}"
 						removed_count += 1
 					else
-						puts_line "skip_missing_path: #{relative}"
+						puts_verbose "skip_missing_path: #{relative}"
 						missing_count += 1
 					end
 				end
 				remove_empty_offboard_directories!
-				puts_line "offboard_summary: removed=#{removed_count} missing=#{missing_count}"
-				puts_line "OK: Carson offboard completed for #{repo_root}."
+				puts_verbose "offboard_summary: removed=#{removed_count} missing=#{missing_count}"
+				if verbose?
+					puts_line "OK: Carson offboard completed for #{repo_root}."
+				else
+					puts_line "Removed #{removed_count} file#{plural_suffix( count: removed_count )}. Offboard complete."
+				end
 				EXIT_OK
 			end
 
@@ -251,9 +286,13 @@ module Carson
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
 
-				print_header "Inspect"
+				puts_verbose ""
+				puts_verbose "[Inspect]"
 				ok = hooks_health_report( strict: true )
-				puts_line( ok ? "status: ok" : "status: block" )
+				puts_verbose( ok ? "status: ok" : "status: block" )
+				unless verbose?
+					puts_line( ok ? "Hooks: ok" : "Hooks: block" )
+				end
 				ok ? EXIT_OK : EXIT_BLOCK
 			end
 
@@ -262,14 +301,24 @@ module Carson
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
 
-				print_header "Template Sync Check"
+				puts_verbose ""
+				puts_verbose "[Template Sync Check]"
 				results = template_results
 				drift_count = results.count { |entry| entry.fetch( :status ) == "drift" }
 				error_count = results.count { |entry| entry.fetch( :status ) == "error" }
 				results.each do |entry|
-					puts_line "template_file: #{entry.fetch( :file )} status=#{entry.fetch( :status )} reason=#{entry.fetch( :reason )}"
+					puts_verbose "template_file: #{entry.fetch( :file )} status=#{entry.fetch( :status )} reason=#{entry.fetch( :reason )}"
+				end
+				puts_verbose "template_summary: total=#{results.count} drift=#{drift_count} error=#{error_count}"
+				unless verbose?
+					if drift_count.positive?
+						drift_files = results.select { |entry| entry.fetch( :status ) == "drift" }.map { |entry| entry.fetch( :file ) }
+						puts_line "Templates: #{drift_count} of #{results.count} drifted"
+						drift_files.each { |file| puts_line "  #{file}" }
+					else
+						puts_line "Templates: #{results.count} files in sync"
+					end
 				end
-				puts_line "template_summary: total=#{results.count} drift=#{drift_count} error=#{error_count}"
 				return EXIT_ERROR if error_count.positive?
 
 				drift_count.positive? ? EXIT_BLOCK : EXIT_OK
@@ -280,29 +329,37 @@ module Carson
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
 
-				print_header "Template Sync Apply" unless concise?
+				puts_verbose ""
+				puts_verbose "[Template Sync Apply]"
 				results = template_results
 				applied = 0
 				results.each do |entry|
 					if entry.fetch( :status ) == "error"
-						puts_line "template_file: #{entry.fetch( :file )} status=error reason=#{entry.fetch( :reason )}" unless concise?
+						puts_verbose "template_file: #{entry.fetch( :file )} status=error reason=#{entry.fetch( :reason )}"
 						next
 					end
 
 					file_path = File.join( repo_root, entry.fetch( :file ) )
 					if entry.fetch( :status ) == "ok"
-						puts_line "template_file: #{entry.fetch( :file )} status=ok reason=in_sync" unless concise?
+						puts_verbose "template_file: #{entry.fetch( :file )} status=ok reason=in_sync"
 						next
 					end
 
 					FileUtils.mkdir_p( File.dirname( file_path ) )
 					File.write( file_path, entry.fetch( :applied_content ) )
-					puts_line "template_file: #{entry.fetch( :file )} status=updated reason=#{entry.fetch( :reason )}" unless concise?
+					puts_verbose "template_file: #{entry.fetch( :file )} status=updated reason=#{entry.fetch( :reason )}"
 					applied += 1
 				end
 
 				error_count = results.count { |entry| entry.fetch( :status ) == "error" }
-				puts_line "template_apply_summary: updated=#{applied} error=#{error_count}" unless concise?
+				puts_verbose "template_apply_summary: updated=#{applied} error=#{error_count}"
+				unless verbose?
+					if applied.positive?
+						puts_line "Templates applied (#{applied} updated)."
+					else
+						puts_line "Templates in sync."
+					end
+				end
 				error_count.positive? ? EXIT_ERROR : EXIT_OK
 			end
 
@@ -363,9 +420,9 @@ module Carson
 			def print_hooks_path_status( configured:, expected: )
 				configured_abs = configured.nil? ? nil : File.expand_path( configured )
 				hooks_path_ok = configured_abs == expected
-				puts_line "hooks_path: #{configured || '(unset)'}"
-				puts_line "hooks_path_expected: #{expected}"
-				puts_line( hooks_path_ok ? "hooks_path_status: ok" : "hooks_path_status: attention" )
+				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
 
@@ -374,7 +431,7 @@ module Carson
 					exists = File.file?( path )
 					symlink = File.symlink?( path )
 					executable = exists && !symlink && File.executable?( path )
-					puts_line "hook_file: #{relative_path( path )} exists=#{exists} symlink=#{symlink} executable=#{executable}"
+					puts_verbose "hook_file: #{relative_path( path )} exists=#{exists} symlink=#{symlink} executable=#{executable}"
 				end
 			end
 
@@ -399,13 +456,13 @@ module Carson
 				if strict && !hooks_path_ok
 					configured_text = configured.to_s.strip
 					if configured_text.empty?
-						puts_line "ACTION: hooks path is unset (expected=#{expected})."
+						puts_verbose "ACTION: hooks path is unset (expected=#{expected})."
 					else
-						puts_line "ACTION: hooks path mismatch (configured=#{configured_text}, expected=#{expected})."
+						puts_verbose "ACTION: hooks path mismatch (configured=#{configured_text}, expected=#{expected})."
 					end
 				end
 				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
+				puts_verbose message
 			end
 
 			# Returns ahead/behind counts for local main versus configured remote main.
@@ -604,17 +661,17 @@ module Carson
 			def disable_carson_hooks_path!
 				configured = configured_hooks_path
 				if configured.nil?
-					puts_line "hooks_path: (unset)"
+					puts_verbose "hooks_path: (unset)"
 					return EXIT_OK
 				end
-				puts_line "hooks_path: #{configured}"
+				puts_verbose "hooks_path: #{configured}"
 				configured_abs = File.expand_path( configured, repo_root )
 				unless carson_managed_hooks_path?( configured_abs: configured_abs )
-					puts_line "hooks_path_kept: #{configured} (not Carson-managed)"
+					puts_verbose "hooks_path_kept: #{configured} (not Carson-managed)"
 					return EXIT_OK
 				end
 				git_system!( "config", "--unset", "core.hooksPath" )
-				puts_line "hooks_path_unset: core.hooksPath"
+				puts_verbose "hooks_path_unset: core.hooksPath"
 				EXIT_OK
 			rescue StandardError => e
 				puts_line "ERROR: unable to update core.hooksPath (#{e.message})"
@@ -660,14 +717,14 @@ module Carson
 					next unless Dir.empty?( absolute )
 
 					Dir.rmdir( absolute )
-					puts_line "removed_empty_dir: #{relative}"
+					puts_verbose "removed_empty_dir: #{relative}"
 				end
 			end
 
 			# Verifies configured remote exists and logs status without mutating remotes.
 			def report_detected_remote!
 				if git_remote_exists?( remote_name: config.git_remote )
-					puts_line "remote_ok: #{config.git_remote}"
+					puts_verbose "remote_ok: #{config.git_remote}"
 				else
 					puts_line "WARN: remote '#{config.git_remote}' not found; run carson setup to configure."
 				end
@@ -675,14 +732,12 @@ module Carson
 
 			# Concise onboard orchestration: hooks, templates, remote, audit, guidance.
 			def onboard_apply!
-				@concise = true
-
-				hook_status = prepare!
+				hook_status = with_captured_output { prepare! }
 				return hook_status unless hook_status == EXIT_OK
 				puts_line "Hooks installed (#{config.required_hooks.count} hooks)."
 
 				template_drift_count = template_results.count { |entry| entry.fetch( :status ) != "ok" }
-				template_status = template_apply!
+				template_status = with_captured_output { template_apply! }
 				return template_status unless template_status == EXIT_OK
 				if template_drift_count.positive?
 					puts_line "Templates synced (#{template_drift_count} file#{plural_suffix( count: template_drift_count )} updated)."

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

@@ -8,10 +8,10 @@ module Carson
 					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"
+						puts_verbose "warmup_skip: all threads resolved"
 						return quick
 					end
-					puts_line "warmup_wait_seconds: #{config.review_wait_seconds}"
+					puts_verbose "warmup_wait_seconds: #{config.review_wait_seconds}"
 					sleep config.review_wait_seconds
 					nil
 				end
@@ -19,7 +19,7 @@ module Carson
 				# Poll delay between consecutive snapshot reads during convergence checks.
 				def wait_for_review_poll
 					return unless config.review_poll_seconds.positive?
-					puts_line "poll_wait_seconds: #{config.review_poll_seconds}"
+					puts_verbose "poll_wait_seconds: #{config.review_poll_seconds}"
 					sleep config.review_poll_seconds
 				end
 
@@ -173,10 +173,10 @@ module Carson
 						json_name: REVIEW_GATE_REPORT_JSON,
 						renderer: method( :render_review_gate_markdown )
 					)
-					puts_line "review_gate_report_markdown: #{markdown_path}"
-					puts_line "review_gate_report_json: #{json_path}"
+					puts_verbose "review_gate_report_markdown: #{markdown_path}"
+					puts_verbose "review_gate_report_json: #{json_path}"
 				rescue StandardError => e
-					puts_line "review_gate_report_write: SKIP (#{e.message})"
+					puts_verbose "review_gate_report_write: SKIP (#{e.message})"
 				end
 
 				# Human-readable review gate report for merge-readiness evidence.

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

@@ -202,10 +202,10 @@ module Carson
 						json_name: REVIEW_SWEEP_REPORT_JSON,
 						renderer: method( :render_review_sweep_markdown )
 					)
-					puts_line "review_sweep_report_markdown: #{markdown_path}"
-					puts_line "review_sweep_report_json: #{json_path}"
+					puts_verbose "review_sweep_report_markdown: #{markdown_path}"
+					puts_verbose "review_sweep_report_json: #{json_path}"
 				rescue StandardError => e
-					puts_line "review_sweep_report_write: SKIP (#{e.message})"
+					puts_verbose "review_sweep_report_write: SKIP (#{e.message})"
 				end
 
 				# Human-readable scheduled sweep report.

data/lib/carson/runtime/review.rb

@@ -16,7 +16,11 @@ module Carson
 			def review_gate!
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
-				print_header "Review Gate"
+				puts_verbose ""
+				puts_verbose "[Review Gate]"
+				unless verbose?
+					puts_line "Review Gate"
+				end
 				unless gh_available?
 					puts_line "ERROR: gh CLI not available in PATH."
 					return EXIT_ERROR
@@ -67,13 +71,13 @@ module Carson
 					snapshot = review_gate_snapshot( owner: owner, repo: repo, pr_number: pr_summary.fetch( :number ) )
 					last_snapshot = snapshot
 					signature = review_gate_signature( snapshot: snapshot )
-					puts_line "poll_attempt: #{poll_attempts}/#{config.review_max_polls}"
-					puts_line "latest_activity: #{snapshot.fetch( :latest_activity ) || 'unknown'}"
-					puts_line "unresolved_threads: #{snapshot.fetch( :unresolved_threads ).count}"
-					puts_line "unacknowledged_actionable: #{snapshot.fetch( :unacknowledged_actionable ).count}"
+					puts_verbose "poll_attempt: #{poll_attempts}/#{config.review_max_polls}"
+					puts_verbose "latest_activity: #{snapshot.fetch( :latest_activity ) || 'unknown'}"
+					puts_verbose "unresolved_threads: #{snapshot.fetch( :unresolved_threads ).count}"
+					puts_verbose "unacknowledged_actionable: #{snapshot.fetch( :unacknowledged_actionable ).count}"
 					if !last_signature.nil? && signature == last_signature
 						converged = true
-						puts_line "convergence: stable"
+						puts_verbose "convergence: stable"
 						break
 					end
 					last_signature = signature
@@ -110,6 +114,9 @@ module Carson
 					unacknowledged_actionable: last_snapshot.fetch( :unacknowledged_actionable )
 				}
 				write_review_gate_report( report: report )
+				unless verbose?
+					puts_line "Polling... (converged after #{poll_attempts} attempt#{plural_suffix( count: poll_attempts )})"
+				end
 				if block_reasons.empty?
 					puts_line "OK: review gate passed."
 					return EXIT_OK
@@ -128,7 +135,8 @@ module Carson
 			def review_sweep!
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
-				print_header "Review Sweep"
+				puts_verbose ""
+				puts_verbose "[Review Sweep]"
 				unless gh_available?
 					puts_line "ERROR: gh CLI not available in PATH."
 					return EXIT_ERROR
@@ -137,8 +145,8 @@ module Carson
 				owner, repo = repository_coordinates
 				cutoff_time = Time.now.utc - ( config.review_sweep_window_days * 86_400 )
 				pull_requests = recent_pull_requests_for_sweep( owner: owner, repo: repo, cutoff_time: cutoff_time )
-				puts_line "window_days: #{config.review_sweep_window_days}"
-				puts_line "candidate_prs: #{pull_requests.count}"
+				puts_verbose "window_days: #{config.review_sweep_window_days}"
+				puts_verbose "candidate_prs: #{pull_requests.count}"
 				findings = []
 
 				pull_requests.each do |entry|

data/lib/carson/runtime/setup.rb

@@ -4,7 +4,8 @@ module Carson
 			WELL_KNOWN_REMOTES = %w[origin github upstream].freeze
 
 			def setup!
-				print_header "Setup"
+				puts_verbose ""
+				puts_verbose "[Setup]"
 
 				unless inside_git_work_tree?
 					puts_line "WARN: not a git repository. Skipping remote and branch detection."
@@ -43,19 +44,19 @@ module Carson
 				choices = {}
 				if detected && detected != config.git_remote
 					choices[ "git.remote" ] = detected
-					puts_line "detected_remote: #{detected}"
+					puts_verbose "detected_remote: #{detected}"
 				elsif detected
-					puts_line "detected_remote: #{detected}"
+					puts_verbose "detected_remote: #{detected}"
 				else
-					puts_line "detected_remote: none"
+					puts_verbose "detected_remote: none"
 				end
 
 				branch = detect_main_branch
 				if branch && branch != config.main_branch
 					choices[ "git.main_branch" ] = branch
-					puts_line "detected_main_branch: #{branch}"
+					puts_verbose "detected_main_branch: #{branch}"
 				elsif branch
-					puts_line "detected_main_branch: #{branch}"
+					puts_verbose "detected_main_branch: #{branch}"
 				end
 
 				write_setup_config( choices: choices )
@@ -103,8 +104,8 @@ module Carson
 				puts_line ""
 				puts_line "Workflow style"
 				options = [
-					{ label: "trunk — commit directly to main (default)", value: "trunk" },
-					{ label: "branch — enforce PR-only merges", value: "branch" }
+					{ label: "branch — enforce PR-only merges (default)", value: "branch" },
+					{ label: "trunk — commit directly to main", value: "trunk" }
 				]
 				prompt_choice( options: options, default: 0 )
 			end

data/lib/carson/runtime.rb

@@ -23,13 +23,13 @@ module Carson
 		DISPOSITION_TOKENS = %w[accepted rejected deferred].freeze
 
 		# Runtime wiring for repository context, tool paths, and output streams.
-		def initialize( repo_root:, tool_root:, out:, err:, in_stream: $stdin )
+		def initialize( repo_root:, tool_root:, out:, err:, in_stream: $stdin, verbose: false )
 			@repo_root = repo_root
 			@tool_root = tool_root
 			@out = out
 			@err = err
 			@in = in_stream
-			@concise = false
+			@verbose = verbose
 			@config = Config.load( repo_root: repo_root )
 			@git_adapter = Adapters::Git.new( repo_root: repo_root )
 			@github_adapter = Adapters::GitHub.new( repo_root: repo_root )
@@ -39,9 +39,14 @@ module Carson
 
 		attr_reader :repo_root, :tool_root, :out, :err, :in, :config, :git_adapter, :github_adapter
 
-		# Returns true when output should be minimal (used by onboard/refresh).
-		def concise?
-			@concise
+		# Returns true when full diagnostic output is enabled via --verbose.
+		def verbose?
+			@verbose
+		end
+
+		# Prints a line only when verbose mode is active.
+		def puts_verbose( message )
+			puts_line( message ) if verbose?
 		end
 
 		# Runs a block with all output captured (suppressed from the user).

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 2.8.1
+  version: 2.10.0
 platform: ruby
 authors:
 - Hailei Wang
@@ -88,7 +88,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '4.0'
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="