carson 3.17.0 → 3.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5474bed385b09305a9a467655447faa7dc5b908486cf69d3124cca99cd7cc2f2
-  data.tar.gz: 4efa36d52f6642967abc25b35ae5a9bcfcfb97072064478873c99693c90a54cd
+  metadata.gz: 36c68c06630159e0dca3560f62993befe8b50dd324fac5a6f8232895b2a667bd
+  data.tar.gz: 1a4462a8b56b6b7fe505705c30ded47e24a279f4fa775baf56b05ae2e48f450a
 SHA512:
-  metadata.gz: 51a319323b1c96b15085cbdb5380a7b2b27c088cf4bade168e5b64947734f9aec2ddea05e5a359bee75b93eb253ba275280c4cb9959165457b559b022d61bcd8
-  data.tar.gz: 8665f26fb62718e6b5b6df1addeedee0caa9130c956e7f40f8aba2e79048438dacf4e49a4cd460cbc1c4a90f7ef85a7916531ec4edae3fc345f3864ff1c7c3f9
+  metadata.gz: 3f644435f5ca88527edc597a7b19134b701bc970748b5ef075f9b1e3c600b3be60724d80c8567bb919cf378a9a5da2dc54fcc27f29b0da811c0f3880c990f016
+  data.tar.gz: 12e3651de47f5f741115c58308c2fe344d542bcc94c3f1234e08990b506b6ffa2c518e5f782ea9cb0a86a699111926c6df1f6571724b5ef3d318666889f2a13f

data/API.md

@@ -29,6 +29,21 @@ carson <command> [subcommand] [arguments]
 | `carson prune` | Remove stale local branches whose upstream refs no longer exist. |
 | `carson template check` | Detect drift between managed templates and host `.github/*` files. |
 | `carson template apply` | Write canonical managed template content into host `.github/*` files. |
+| `carson status` | Show repository state (branch, worktrees, PRs, governance). |
+
+### Batch commands (Layer 2)
+
+All batch commands operate across every governed repository registered in `govern.repos`.
+
+| Command | Purpose |
+|---|---|
+| `carson refresh --all` | Re-apply hooks, templates, and audit across all governed repos. Skips repos with active worktrees or uncommitted changes. |
+| `carson audit --all` | Run governance audit across all governed repos. Reports pass/block/fail per repo. |
+| `carson sync --all` | Sync main branch across all governed repos. |
+| `carson prune --all` | Remove stale branches across all governed repos. |
+| `carson status --all [--json]` | Portfolio-wide status overview with branch, worktrees, and governance state per repo. |
+| `carson template check --all` | Read-only template drift detection across all governed repos. |
+| `carson housekeep --all` | Sync, reap dead worktrees, and prune across all governed repos. |
 
 ### Govern commands
 
@@ -132,7 +147,7 @@ Environment overrides:
 ```json
 {
   "template": {
-    "canonical": "~/AI/LINT"
+    "canonical": "~/AI/CODING/LINT"
   }
 }
 ```

data/MANUAL.md

@@ -89,7 +89,7 @@ Set `template.canonical` in `~/.carson/config.json`:
 ```json
 {
   "template": {
-    "canonical": "~/AI/LINT"
+    "canonical": "~/AI/CODING/LINT"
   }
 }
 ```
@@ -97,7 +97,7 @@ Set `template.canonical` in `~/.carson/config.json`:
 That directory mirrors the `.github/` structure:
 
 ```
-~/AI/LINT/
+~/AI/CODING/LINT/
 ├── workflows/
 │   └── lint.yml          → deployed to .github/workflows/lint.yml
 ├── .mega-linter.yml      → deployed to .github/.mega-linter.yml
@@ -207,8 +207,24 @@ carson review gate
 ```bash
 carson repos           # list all governed repositories
 carson repos --json    # machine-readable output
+carson status --all    # branch, worktrees, governance per repo
 ```
 
+**Portfolio maintenance (Layer 2):**
+
+All `--all` commands run across every governed repository registered via `carson onboard`.
+
+```bash
+carson refresh --all           # re-apply hooks, templates, audit across all repos
+carson sync --all              # fast-forward main across all repos
+carson audit --all             # governance audit across all repos
+carson prune --all             # remove stale branches across all repos
+carson template check --all    # detect template drift across all repos
+carson housekeep --all         # full maintenance cycle across all repos
+```
+
+`refresh --all` checks each repo for safety before operating: repos with active worktrees or uncommitted changes are skipped with clear reasons. Other batch commands attempt each repo and report failures without stopping.
+
 **Periodic maintenance:**
 
 ```bash

data/RELEASE.md

@@ -5,6 +5,36 @@ 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`.
 
+## 3.19.0
+
+### What changed
+
+- **Persistent pending tracking for batch operations** — repos skipped during `--all` operations (due to active worktrees, uncommitted changes, or path errors) are now recorded in `~/.carson/cache/batch_pending.json`. On the next run, pending repos are reported and automatically retried. `carson status --all` shows pending operations per repo with attempt count and timestamp.
+- **Ruby 3.4+ `it` implicit parameter** — single-parameter blocks where the parameter is the receiver now use `it` instead of named block variables (e.g. `.map { it.fetch( :name ) }` instead of `.map { |e| e.fetch( :name ) }`). Guard clause early returns replace `elsif` chains in `remote_sync_status`.
+
+### UX improvement
+
+- Batch operations are now self-healing: repos that can't be reached on one run aren't silently forgotten. They're logged with reasons and retried on the next invocation. `carson status --all` makes pending operations visible so the user always knows what needs attention.
+
+## 3.18.0
+
+### What changed
+
+- **Layer 2 batch operations** — every command that operates on a single repo now has an `--all` variant that runs across the entire governed portfolio:
+  - `carson refresh --all` — refresh hooks, templates, and audit across all repos. Checks each repo for safety (active worktrees, uncommitted changes) and skips unsafe repos.
+  - `carson prune --all` — prune stale branches across all repos.
+  - `carson audit --all` — run governance audit across all repos. Reports pass/block/fail per repo.
+  - `carson sync --all` — sync main branch across all repos.
+  - `carson status --all` — portfolio-wide status overview with branch, worktrees, and governance state per repo. Supports `--json`.
+  - `carson template check --all` — read-only template drift detection across all repos.
+- **Portfolio safety checks** — before batch `refresh`, Carson checks each repo for active worktrees and uncommitted changes. Unsafe repos are skipped with reasons, not failed.
+- **Shared `portfolio_repo_safety` helper** — centralised safety check in `Runtime` for all batch operations. Non-git directories pass through (the command reports the real error).
+- **CLI `--all` flag registration** — `audit`, `sync`, and `status` parsers now correctly register the `--all` flag with OptionParser (previously the flag was checked but never registered).
+
+### UX improvement
+
+- A user or agent managing multiple repositories can now run a single command to maintain the entire portfolio. `carson status --all` gives a quick overview; `carson refresh --all` keeps everything in sync; `carson housekeep --all` runs the full maintenance cycle. Unsafe repos are clearly reported with skip reasons instead of cryptic failures.
+
 ## 3.17.0
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-3.17.0
+3.19.0

data/lib/carson/cli.rb

@@ -12,7 +12,7 @@ module Carson
 				return Runtime::EXIT_OK
 			end
 
-			if %w[repos refresh:all prune:all housekeep:all housekeep:target].include?( command )
+			if %w[repos refresh:all prune:all housekeep:all housekeep:target template:check:all audit:all sync:all status:all].include?( command )
 				verbose = parsed.fetch( :verbose, false )
 				runtime = Runtime.new( repo_root: repo_root, tool_root: tool_root, out: out, err: err, verbose: verbose )
 				return dispatch( parsed: parsed, runtime: runtime )
@@ -409,6 +409,7 @@ module Carson
 			end
 
 			action = argv.shift
+			return { command: "template:check:all" } if action == "check" && argv.include?( "--all" )
 			return { command: "template:#{action}" } unless action == "apply"
 
 			options = { push_prep: false }
@@ -438,26 +439,29 @@ module Carson
 		# --- audit ---
 
 		def self.parse_audit_command( argv:, err: )
-			options = { json: false }
+			options = { json: false, all: false }
 			audit_parser = OptionParser.new do |opts|
-				opts.banner = "Usage: carson audit [--json]"
+				opts.banner = "Usage: carson audit [--all] [--json]"
 				opts.separator ""
 				opts.separator "Run pre-commit health checks on the repository."
 				opts.separator "Validates hooks, main-branch sync, PR status, and CI baseline."
 				opts.separator "Exits with a non-zero status when policy violations are found."
 				opts.separator ""
 				opts.separator "Options:"
+				opts.on( "--all", "Audit all governed repositories" ) { options[ :all ] = true }
 				opts.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
 				opts.separator ""
 				opts.separator "Examples:"
 				opts.separator "    carson audit           Check repository health (also the default command)"
 				opts.separator "    carson audit --json    Structured output for agent consumption"
+				opts.separator "    carson audit --all     Audit all governed repos"
 			end
 			audit_parser.parse!( argv )
 			unless argv.empty?
 				err.puts "#{BADGE} Unexpected arguments for audit: #{argv.join( ' ' )}"
 				return { command: :invalid }
 			end
+			return { command: "audit:all" } if options[ :all ]
 			{ command: "audit", json: options[ :json ] }
 		rescue OptionParser::ParseError => e
 			err.puts "#{BADGE} #{e.message}"
@@ -467,25 +471,28 @@ module Carson
 		# --- sync ---
 
 		def self.parse_sync_command( argv:, err: )
-			options = { json: false }
+			options = { json: false, all: false }
 			sync_parser = OptionParser.new do |opts|
-				opts.banner = "Usage: carson sync [--json]"
+				opts.banner = "Usage: carson sync [--all] [--json]"
 				opts.separator ""
 				opts.separator "Sync the local main branch with the remote."
 				opts.separator "Fetches and fast-forwards main without switching branches."
 				opts.separator ""
 				opts.separator "Options:"
+				opts.on( "--all", "Sync all governed repositories" ) { options[ :all ] = true }
 				opts.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
 				opts.separator ""
 				opts.separator "Examples:"
 				opts.separator "    carson sync            Pull latest changes from remote main"
 				opts.separator "    carson sync --json     Structured output for agent consumption"
+				opts.separator "    carson sync --all      Sync all governed repos"
 			end
 			sync_parser.parse!( argv )
 			unless argv.empty?
 				err.puts "#{BADGE} Unexpected arguments for sync: #{argv.join( ' ' )}"
 				return { command: :invalid }
 			end
+			return { command: "sync:all" } if options[ :all ]
 			{ command: "sync", json: options[ :json ] }
 		rescue OptionParser::ParseError => e
 			err.puts "#{BADGE} #{e.message}"
@@ -495,25 +502,28 @@ module Carson
 		# --- status ---
 
 		def self.parse_status_command( argv:, err: )
-			options = { json: false }
+			options = { json: false, all: false }
 			status_parser = OptionParser.new do |opts|
-				opts.banner = "Usage: carson status [--json]"
+				opts.banner = "Usage: carson status [--all] [--json]"
 				opts.separator ""
 				opts.separator "Show the current state of the repository."
 				opts.separator "Reports branch, worktrees, open PRs, stale branches, and version."
 				opts.separator ""
 				opts.separator "Options:"
+				opts.on( "--all", "Show status for all governed repositories" ) { options[ :all ] = true }
 				opts.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
 				opts.separator ""
 				opts.separator "Examples:"
 				opts.separator "    carson status           Quick overview of repository state"
 				opts.separator "    carson status --json    Structured output for agent consumption"
+				opts.separator "    carson status --all     Portfolio-wide status overview"
 			end
 			status_parser.parse!( argv )
 			unless argv.empty?
 				err.puts "#{BADGE} Unexpected arguments for status: #{argv.join( ' ' )}"
 				return { command: :invalid }
 			end
+			return { command: "status:all", json: options[ :json ] } if options[ :all ]
 			{ command: "status", json: options[ :json ] }
 		rescue OptionParser::ParseError => e
 			err.puts "#{BADGE} #{e.message}"
@@ -734,6 +744,14 @@ module Carson
 					json_output: parsed.fetch( :json, false ),
 					loop_seconds: parsed.fetch( :loop_seconds, nil )
 				)
+			when "template:check:all"
+				runtime.template_check_all!
+			when "audit:all"
+				runtime.audit_all!
+			when "sync:all"
+				runtime.sync_all!
+			when "status:all"
+				runtime.status_all!( json_output: parsed.fetch( :json, false ) )
 			else
 				runtime.send( :puts_line, "Unknown command: #{command}" )
 				Runtime::EXIT_ERROR

data/lib/carson/runtime/audit.rb

@@ -72,7 +72,7 @@ module Carson
 					fail_n = checks.fetch( :failing_count )
 					pend_n = checks.fetch( :pending_count )
 					total = checks.fetch( :required_total )
-					fail_names = checks.fetch( :failing ).map { |e| e.fetch( :name ) }.join( ", " )
+					fail_names = checks.fetch( :failing ).map { it.fetch( :name ) }.join( ", " )
 					if fail_n.positive? && pend_n.positive?
 						audit_concise_problems << "Checks: #{fail_n} failing (#{fail_names}), #{pend_n} pending of #{total} required."
 					elsif fail_n.positive?
@@ -89,11 +89,11 @@ module Carson
 				if baseline_st == "block"
 					parts = []
 					if default_branch_baseline.fetch( :failing_count ).positive?
-						names = default_branch_baseline.fetch( :failing ).map { |e| e.fetch( :name ) }.join( ", " )
+						names = default_branch_baseline.fetch( :failing ).map { it.fetch( :name ) }.join( ", " )
 						parts << "#{default_branch_baseline.fetch( :failing_count )} failing (#{names})"
 					end
 					if default_branch_baseline.fetch( :pending_count ).positive?
-						names = default_branch_baseline.fetch( :pending ).map { |e| e.fetch( :name ) }.join( ", " )
+						names = default_branch_baseline.fetch( :pending ).map { it.fetch( :name ) }.join( ", " )
 						parts << "#{default_branch_baseline.fetch( :pending_count )} pending (#{names})"
 					end
 					parts << "no check-runs for active workflows" if default_branch_baseline.fetch( :no_check_evidence )
@@ -101,11 +101,11 @@ module Carson
 				elsif baseline_st == "attention"
 					parts = []
 					if default_branch_baseline.fetch( :advisory_failing_count ).positive?
-						names = default_branch_baseline.fetch( :advisory_failing ).map { |e| e.fetch( :name ) }.join( ", " )
+						names = default_branch_baseline.fetch( :advisory_failing ).map { it.fetch( :name ) }.join( ", " )
 						parts << "#{default_branch_baseline.fetch( :advisory_failing_count )} advisory failing (#{names})"
 					end
 					if default_branch_baseline.fetch( :advisory_pending_count ).positive?
-						names = default_branch_baseline.fetch( :advisory_pending ).map { |e| e.fetch( :name ) }.join( ", " )
+						names = default_branch_baseline.fetch( :advisory_pending ).map { it.fetch( :name ) }.join( ", " )
 						parts << "#{default_branch_baseline.fetch( :advisory_pending_count )} advisory pending (#{names})"
 					end
 					audit_concise_problems << "Baseline (#{default_branch_baseline.fetch( :default_branch, config.main_branch )}): #{parts.join( ', ' )}."
@@ -157,6 +157,58 @@ module Carson
 				exit_code
 			end
 
+			# Runs audit across all governed repositories.
+			def audit_all!
+				repos = config.govern_repos
+				if repos.empty?
+					puts_line "No governed repositories configured."
+					puts_line "  Run carson onboard in each repo to register."
+					return EXIT_ERROR
+				end
+
+				puts_line ""
+				puts_line "Audit all (#{repos.length} repo#{plural_suffix( count: repos.length )})"
+				passed = 0
+				blocked = 0
+				failed = 0
+
+				repos.each do |repo_path|
+					repo_name = File.basename( repo_path )
+					unless Dir.exist?( repo_path )
+						puts_line "#{repo_name}: FAIL (path not found)"
+						record_batch_skip( command: "audit", repo_path: repo_path, reason: "path not found" )
+						failed += 1
+						next
+					end
+
+					begin
+						rt = build_scoped_runtime( repo_path: repo_path )
+						status = rt.audit!
+						case status
+						when EXIT_OK
+							puts_line "#{repo_name}: ok" unless verbose?
+							clear_batch_success( command: "audit", repo_path: repo_path )
+							passed += 1
+						when EXIT_BLOCK
+							puts_line "#{repo_name}: BLOCK" unless verbose?
+							blocked += 1
+						else
+							puts_line "#{repo_name}: FAIL" unless verbose?
+							record_batch_skip( command: "audit", repo_path: repo_path, reason: "audit failed" )
+							failed += 1
+						end
+					rescue StandardError => e
+						puts_line "#{repo_name}: FAIL (#{e.message})"
+						record_batch_skip( command: "audit", repo_path: repo_path, reason: e.message )
+						failed += 1
+					end
+				end
+
+				puts_line ""
+				puts_line "Audit all complete: #{passed} ok, #{blocked} blocked, #{failed} failed."
+				blocked.zero? && failed.zero? ? EXIT_OK : EXIT_BLOCK
+			end
+
 		private
 			def pr_and_check_report
 				report = {
@@ -210,7 +262,7 @@ module Carson
 					return report
 				end
 				checks_data = JSON.parse( checks_stdout )
-				pending = checks_data.select { |entry| entry[ "bucket" ].to_s == "pending" }
+				pending = checks_data.select { it[ "bucket" ].to_s == "pending" }
 				failing = checks_data.select { |entry| check_entry_failing?( entry: entry ) }
 				report[ :checks ][ :status ] = checks_success ? "ok" : ( checks_exit == 8 ? "pending" : "attention" )
 				report[ :checks ][ :required_total ] = checks_data.count

data/lib/carson/runtime/housekeep.rb

@@ -34,10 +34,18 @@ module Carson
 				end
 
 				results = []
-				repos.each { |repo_path| results << housekeep_one_entry( repo_path: repo_path, silent: json_output ) }
+				repos.each do |repo_path|
+					entry = housekeep_one_entry( repo_path: repo_path, silent: json_output )
+					if entry[ :status ] == "ok"
+						clear_batch_success( command: "housekeep", repo_path: repo_path )
+					else
+						record_batch_skip( command: "housekeep", repo_path: repo_path, reason: entry[ :error ] || "housekeep failed" )
+					end
+					results << entry
+				end
 
-				succeeded = results.count { |r| r[ :status ] == "ok" }
-				failed = results.count { |r| r[ :status ] != "ok" }
+				succeeded = results.count { it[ :status ] == "ok" }
+				failed = results.count { it[ :status ] != "ok" }
 				result = { command: "housekeep", status: failed.zero? ? "ok" : "partial", repos: results, succeeded: succeeded, failed: failed }
 				housekeep_finish( result: result, exit_code: failed.zero? ? EXIT_OK : EXIT_ERROR, json_output: json_output, results: results, succeeded: succeeded, failed: failed )
 			end

data/lib/carson/runtime/local/onboard.rb

@@ -1,3 +1,7 @@
+# Repository onboarding and refresh lifecycle.
+# Onboard: detect remote, install hooks, apply templates, run initial audit.
+# Refresh: re-apply hooks and templates after Carson upgrade.
+# Refresh all: batch refresh across governed portfolio with safety checks.
 module Carson
 	class Runtime
 		module Local
@@ -44,7 +48,7 @@ module Carson
 					hook_status = prepare!
 					return hook_status unless hook_status == EXIT_OK
 
-					drift_count = template_results.count { |entry| entry.fetch( :status ) != "ok" }
+					drift_count = template_results.count { it.fetch( :status ) != "ok" }
 					template_status = template_apply!
 					return template_status unless template_status == EXIT_OK
 
@@ -64,7 +68,7 @@ module Carson
 				return hook_status unless hook_status == EXIT_OK
 				puts_line "Hooks installed (#{config.managed_hooks.count} hooks)."
 
-				template_drift_count = template_results.count { |entry| entry.fetch( :status ) != "ok" }
+				template_drift_count = template_results.count { it.fetch( :status ) != "ok" }
 				template_status = with_captured_output { template_apply! }
 				return template_status unless template_status == EXIT_OK
 				if template_drift_count.positive?
@@ -81,6 +85,8 @@ module Carson
 			end
 
 			# Re-applies hooks, templates, and audit across all governed repositories.
+			# Checks each repo for safety (active worktrees, uncommitted changes) and
+			# marks unsafe repos as pending to avoid disrupting active work.
 			def refresh_all!
 				repos = config.govern_repos
 				if repos.empty?
@@ -89,30 +95,50 @@ module Carson
 					return EXIT_ERROR
 				end
 
+				pending_before = pending_repos_for( command: "refresh" )
+				if pending_before.any?
+					puts_line "#{pending_before.length} repo#{plural_suffix( count: pending_before.length )} pending from previous run"
+				end
+
 				puts_line ""
 				puts_line "Refresh all (#{repos.length} repo#{plural_suffix( count: repos.length )})"
 				refreshed = 0
+				pending = 0
 				failed = 0
 
 				repos.each do |repo_path|
 					repo_name = File.basename( repo_path )
 					unless Dir.exist?( repo_path )
 						puts_line "#{repo_name}: FAIL (path not found)"
+						record_batch_skip( command: "refresh", repo_path: repo_path, reason: "path not found" )
 						failed += 1
 						next
 					end
 
+					safety = portfolio_repo_safety( repo_path: repo_path )
+					unless safety.fetch( :safe )
+						reason = safety.fetch( :reasons ).join( ", " )
+						puts_line "#{repo_name}: PENDING (#{reason})"
+						record_batch_skip( command: "refresh", repo_path: repo_path, reason: reason )
+						pending += 1
+						next
+					end
+
 					status = refresh_single_repo( repo_path: repo_path, repo_name: repo_name )
 					if status == EXIT_ERROR
 						failed += 1
 					else
+						clear_batch_success( command: "refresh", repo_path: repo_path )
 						refreshed += 1
 					end
 				end
 
 				puts_line ""
-				puts_line "Refresh all complete: #{refreshed} refreshed, #{failed} failed."
-				failed.zero? ? EXIT_OK : EXIT_ERROR
+				parts = [ "#{refreshed} refreshed" ]
+				parts << "#{pending} still pending (will retry on next run)" if pending.positive?
+				parts << "#{failed} failed" if failed.positive?
+				puts_line "Refresh all complete: #{parts.join( ', ' )}."
+				failed.zero? && pending.zero? ? EXIT_OK : EXIT_ERROR
 			end
 
 			def prune_all!
@@ -132,6 +158,7 @@ module Carson
 					repo_name = File.basename( repo_path )
 					unless Dir.exist?( repo_path )
 						puts_line "#{repo_name}: FAIL (path not found)"
+						record_batch_skip( command: "prune", repo_path: repo_path, reason: "path not found" )
 						failed += 1
 						next
 					end
@@ -145,9 +172,16 @@ module Carson
 							summary = buf.string.lines.last.to_s.strip
 							puts_line "#{repo_name}: #{summary.empty? ? 'OK' : summary}"
 						end
-						status == EXIT_ERROR ? ( failed += 1 ) : ( succeeded += 1 )
+						if status == EXIT_ERROR
+							record_batch_skip( command: "prune", repo_path: repo_path, reason: "prune failed" )
+							failed += 1
+						else
+							clear_batch_success( command: "prune", repo_path: repo_path )
+							succeeded += 1
+						end
 					rescue StandardError => e
 						puts_line "#{repo_name}: FAIL (#{e.message})"
+						record_batch_skip( command: "prune", repo_path: repo_path, reason: e.message )
 						failed += 1
 					end
 				end
@@ -214,7 +248,7 @@ module Carson
 				return hook_status unless hook_status == EXIT_OK
 				puts_line "Hooks installed (#{config.managed_hooks.count} hooks)."
 
-				template_drift_count = template_results.count { |entry| entry.fetch( :status ) != "ok" }
+				template_drift_count = template_results.count { it.fetch( :status ) != "ok" }
 				template_status = with_captured_output { template_apply! }
 				return template_status unless template_status == EXIT_OK
 				if template_drift_count.positive?

data/lib/carson/runtime/local/sync.rb

@@ -42,6 +42,53 @@ module Carson
 				git_system!( "switch", start_branch ) if switched && branch_exists?( branch_name: start_branch )
 			end
 
+			# Syncs main branch across all governed repositories.
+			def sync_all!
+				repos = config.govern_repos
+				if repos.empty?
+					puts_line "No governed repositories configured."
+					puts_line "  Run carson onboard in each repo to register."
+					return EXIT_ERROR
+				end
+
+				puts_line ""
+				puts_line "Sync all (#{repos.length} repo#{plural_suffix( count: repos.length )})"
+				synced = 0
+				failed = 0
+
+				repos.each do |repo_path|
+					repo_name = File.basename( repo_path )
+					unless Dir.exist?( repo_path )
+						puts_line "#{repo_name}: FAIL (path not found)"
+						record_batch_skip( command: "sync", repo_path: repo_path, reason: "path not found" )
+						failed += 1
+						next
+					end
+
+					begin
+						rt = build_scoped_runtime( repo_path: repo_path )
+						status = rt.sync!
+						if status == EXIT_OK
+							puts_line "#{repo_name}: ok" unless verbose?
+							clear_batch_success( command: "sync", repo_path: repo_path )
+							synced += 1
+						else
+							puts_line "#{repo_name}: FAIL" unless verbose?
+							record_batch_skip( command: "sync", repo_path: repo_path, reason: "sync failed" )
+							failed += 1
+						end
+					rescue StandardError => e
+						puts_line "#{repo_name}: FAIL (#{e.message})"
+						record_batch_skip( command: "sync", repo_path: repo_path, reason: e.message )
+						failed += 1
+					end
+				end
+
+				puts_line ""
+				puts_line "Sync all complete: #{synced} synced, #{failed} failed."
+				failed.zero? ? EXIT_OK : EXIT_ERROR
+			end
+
 		private
 
 			# Runs a git command, suppressing stdout/stderr in JSON mode to keep output clean.

data/lib/carson/runtime/local/template.rb

@@ -18,8 +18,8 @@ module Carson
 				puts_verbose "[Template Sync Check]"
 				results = template_results
 				stale = template_superseded_present
-				drift_count = results.count { |entry| entry.fetch( :status ) == "drift" }
-				error_count = results.count { |entry| entry.fetch( :status ) == "error" }
+				drift_count = results.count { it.fetch( :status ) == "drift" }
+				error_count = results.count { it.fetch( :status ) == "error" }
 				stale_count = stale.count
 				results.each do |entry|
 					puts_verbose "template_file: #{entry.fetch( :file )} status=#{entry.fetch( :status )} reason=#{entry.fetch( :reason )}"
@@ -32,7 +32,7 @@ module Carson
 						summary_parts << "#{drift_count} of #{results.count} drifted" if drift_count.positive?
 						summary_parts << "#{stale_count} stale" if stale_count.positive?
 						puts_line "Templates: #{summary_parts.join( ", " )}"
-						results.select { |entry| entry.fetch( :status ) == "drift" }.each { |entry| puts_line "  #{entry.fetch( :file )}" }
+						results.select { it.fetch( :status ) == "drift" }.each { |entry| puts_line "  #{entry.fetch( :file )}" }
 						stale.each { |file| puts_line "  #{file} — superseded" }
 					else
 						puts_line "Templates: #{results.count} files in sync"
@@ -43,6 +43,53 @@ module Carson
 				( drift_count + stale_count ).positive? ? EXIT_BLOCK : EXIT_OK
 			end
 
+			# Read-only template drift check across all governed repositories.
+			def template_check_all!
+				repos = config.govern_repos
+				if repos.empty?
+					puts_line "No governed repositories configured."
+					puts_line "  Run carson onboard in each repo to register."
+					return EXIT_ERROR
+				end
+
+				puts_line ""
+				puts_line "Template check all (#{repos.length} repo#{plural_suffix( count: repos.length )})"
+				in_sync = 0
+				drifted = 0
+				failed = 0
+
+				repos.each do |repo_path|
+					repo_name = File.basename( repo_path )
+					unless Dir.exist?( repo_path )
+						puts_line "#{repo_name}: FAIL (path not found)"
+						record_batch_skip( command: "template_check", repo_path: repo_path, reason: "path not found" )
+						failed += 1
+						next
+					end
+
+					begin
+						rt = build_scoped_runtime( repo_path: repo_path )
+						status = rt.template_check!
+						if status == EXIT_OK
+							puts_line "#{repo_name}: in sync" unless verbose?
+							clear_batch_success( command: "template_check", repo_path: repo_path )
+							in_sync += 1
+						else
+							puts_line "#{repo_name}: DRIFT" unless verbose?
+							drifted += 1
+						end
+					rescue StandardError => e
+						puts_line "#{repo_name}: FAIL (#{e.message})"
+						record_batch_skip( command: "template_check", repo_path: repo_path, reason: e.message )
+						failed += 1
+					end
+				end
+
+				puts_line ""
+				puts_line "Template check complete: #{in_sync} in sync, #{drifted} drifted, #{failed} failed."
+				drifted.zero? && failed.zero? ? EXIT_OK : EXIT_BLOCK
+			end
+
 			# Applies managed template files as full-file writes from Carson sources.
 			# Also removes superseded files that are no longer part of the managed set.
 			def template_apply!( push_prep: false )
@@ -80,7 +127,7 @@ module Carson
 					removed += 1
 				end
 
-				error_count = results.count { |entry| entry.fetch( :status ) == "error" }
+				error_count = results.count { it.fetch( :status ) == "error" }
 				puts_verbose "template_apply_summary: updated=#{applied} removed=#{removed} error=#{error_count}"
 				unless verbose?
 					if applied.positive? || removed.positive?

data/lib/carson/runtime/status.rb

@@ -17,8 +17,87 @@ module Carson
 				EXIT_OK
 			end
 
+			# Portfolio-wide status overview across all governed repositories.
+			def status_all!( json_output: false )
+				repos = config.govern_repos
+				if repos.empty?
+					puts_line "No governed repositories configured."
+					puts_line "  Run carson onboard in each repo to register."
+					return EXIT_ERROR
+				end
+
+				if json_output
+					results = []
+					repos.each do |repo_path|
+						repo_name = File.basename( repo_path )
+						unless Dir.exist?( repo_path )
+							results << { name: repo_name, status: "error", error: "path not found" }
+							next
+						end
+						begin
+							rt = build_scoped_runtime( repo_path: repo_path )
+							data = rt.send( :gather_status )
+							results << { name: repo_name, status: "ok" }.merge( data )
+						rescue StandardError => e
+							results << { name: repo_name, status: "error", error: e.message }
+						end
+					end
+					out.puts JSON.pretty_generate( { command: "status", repos: results } )
+					return EXIT_OK
+				end
+
+				puts_line "Carson #{Carson::VERSION} — Portfolio (#{repos.length} repo#{plural_suffix( count: repos.length )})"
+				puts_line ""
+
+				all_pending = load_batch_pending
+				repos.each do |repo_path|
+					repo_name = File.basename( repo_path )
+					unless Dir.exist?( repo_path )
+						puts_line "#{repo_name}: MISSING"
+						next
+					end
+
+					begin
+						rt = build_scoped_runtime( repo_path: repo_path )
+						data = rt.send( :gather_status )
+						branch = data.fetch( :branch )
+						dirty = branch.fetch( :dirty ) ? " (dirty)" : ""
+						worktrees = data.fetch( :worktrees )
+						gov = data.fetch( :governance )
+						parts = []
+						parts << branch.fetch( :name ) + dirty
+						parts << "#{worktrees.count} worktree#{plural_suffix( count: worktrees.count )}" if worktrees.any?
+						parts << "templates #{gov.fetch( :templates )}" unless gov.fetch( :templates ) == :in_sync
+						puts_line "#{repo_name}: #{parts.join( '  ' )}"
+
+						# Show pending operations for this repo.
+						repo_pending = status_pending_for_repo( all_pending: all_pending, repo_path: repo_path )
+						repo_pending.each { |desc| puts_line "  pending: #{desc}" }
+					rescue StandardError => e
+						puts_line "#{repo_name}: FAIL (#{e.message})"
+					end
+				end
+
+				EXIT_OK
+			end
+
 		private
 
+			# Returns an array of human-readable pending descriptions for a repo.
+			def status_pending_for_repo( all_pending:, repo_path: )
+				descriptions = []
+				all_pending.each do |command, repos|
+					next unless repos.is_a?( Hash ) && repos.key?( repo_path )
+
+					info = repos[ repo_path ]
+					attempts = info.fetch( "attempts", 0 )
+					skipped_at = info.fetch( "skipped_at", nil )
+					time_part = skipped_at ? ", since #{skipped_at[ 11..15 ]}" : ""
+					descriptions << "#{command} (#{attempts} attempt#{attempts == 1 ? '' : 's'}#{time_part})"
+				end
+				descriptions
+			end
+
 			# Collects all status facets into a structured hash.
 			def gather_status
 				data = {
@@ -70,15 +149,10 @@ module Carson
 				ahead = parts[ 0 ].to_i
 				behind = parts[ 1 ].to_i
 
-				if ahead.zero? && behind.zero?
-					:in_sync
-				elsif ahead.positive? && behind.zero?
-					:ahead
-				elsif ahead.zero? && behind.positive?
-					:behind
-				else
-					:diverged
-				end
+				return :in_sync if ahead.zero? && behind.zero?
+				return :ahead if behind.zero?
+				return :behind if ahead.zero?
+				:diverged
 			end
 
 			# Lists all worktrees with branch name.
@@ -88,7 +162,7 @@ module Carson
 				# Filter out the main worktree (the repository root itself).
 				# Use realpath for comparison — git returns canonical paths that may differ from repo_root.
 				canonical_root = realpath_safe( repo_root )
-				entries.reject { |wt| wt.fetch( :path ) == canonical_root }.map do |wt|
+				entries.reject { it.fetch( :path ) == canonical_root }.map do |wt|
 					{
 						path: wt.fetch( :path ),
 						name: File.basename( wt.fetch( :path ) ),
@@ -126,9 +200,9 @@ module Carson
 				entries = Array( rollup )
 				return :none if entries.empty?
 
-				states = entries.map { |c| c[ "conclusion" ].to_s.upcase }
-				return :fail if states.any? { |s| s == "FAILURE" || s == "CANCELLED" || s == "TIMED_OUT" }
-				return :pending if states.any? { |s| s == "" || s == "PENDING" || s == "QUEUED" || s == "IN_PROGRESS" }
+				states = entries.map { it[ "conclusion" ].to_s.upcase }
+				return :fail if states.any? { it == "FAILURE" || it == "CANCELLED" || it == "TIMED_OUT" }
+				return :pending if states.any? { it == "" || it == "PENDING" || it == "QUEUED" || it == "IN_PROGRESS" }
 
 				:pass
 			end

data/lib/carson/runtime.rb

@@ -212,6 +212,112 @@ module Carson
 		def gh_run( *args )
 			github_adapter.run( *args )
 		end
+
+		# --- Batch pending tracking (shared by all --all commands) ---
+
+		# Path to the persistent pending log for batch operations.
+		def batch_pending_path
+			File.join( report_dir_path, "batch_pending.json" )
+		end
+
+		# Reads and parses the pending log. Returns empty hash if missing or corrupt.
+		def load_batch_pending
+			path = batch_pending_path
+			return {} unless File.file?( path )
+
+			JSON.parse( File.read( path ) )
+		rescue StandardError
+			{}
+		end
+
+		# Writes the pending log atomically.
+		def save_batch_pending( data )
+			path = batch_pending_path
+			FileUtils.mkdir_p( File.dirname( path ) )
+			tmp = "#{path}.tmp"
+			File.write( tmp, JSON.pretty_generate( data ) )
+			File.rename( tmp, path )
+		end
+
+		# Adds or updates an entry in the pending log, incrementing attempts.
+		def record_batch_skip( command:, repo_path:, reason: )
+			data = load_batch_pending
+			data[ command ] ||= {}
+			existing = data[ command ][ repo_path ]
+			attempts = existing ? existing.fetch( "attempts", 0 ) + 1 : 1
+			data[ command ][ repo_path ] = {
+				"skipped_at" => Time.now.utc.iso8601,
+				"reason" => reason,
+				"attempts" => attempts
+			}
+			save_batch_pending( data )
+		end
+
+		# Removes an entry from the pending log after successful completion.
+		def clear_batch_success( command:, repo_path: )
+			data = load_batch_pending
+			return unless data.key?( command )
+
+			data[ command ].delete( repo_path )
+			data.delete( command ) if data[ command ].empty?
+			save_batch_pending( data )
+		end
+
+		# Returns array of pending repo info hashes for a command.
+		def pending_repos_for( command: )
+			data = load_batch_pending
+			entries = data.fetch( command, {} )
+			entries.map do |path, info|
+				{
+					path: path,
+					reason: info.fetch( "reason", "unknown" ),
+					skipped_at: info.fetch( "skipped_at", nil ),
+					attempts: info.fetch( "attempts", 0 )
+				}
+			end
+		end
+
+		# --- Portfolio helpers (shared by all --all commands) ---
+
+		# Checks whether a governed repo is safe for batch operations.
+		# Returns { safe: true/false, reasons: [...] }.
+		# Safe means: no active worktrees beyond main, no uncommitted changes.
+		# Non-git directories pass through as safe — let the command handle the error.
+		def portfolio_repo_safety( repo_path: )
+			git = Adapters::Git.new( repo_root: repo_path )
+
+			# Non-git directories pass through — the calling command reports the real error.
+			stdout, _, git_ok, = git.run( "rev-parse", "--is-inside-work-tree" )
+			return { safe: true, reasons: [] } unless git_ok && stdout.to_s.strip == "true"
+
+			reasons = []
+
+			# Active worktrees beyond the main working tree.
+			rt = build_scoped_runtime( repo_path: repo_path )
+			worktrees = rt.send( :worktree_list )
+			main_root = rt.send( :realpath_safe, repo_path )
+			active = worktrees.reject { |wt| wt.fetch( :path ) == main_root }
+			if active.any?
+				reasons << "#{active.count} active worktree#{active.count == 1 ? '' : 's'}"
+			end
+
+			# Uncommitted changes in the main working tree.
+			stdout, _, success, = git.run( "status", "--porcelain" )
+			if success && !stdout.strip.empty?
+				reasons << "uncommitted changes"
+			end
+
+			{ safe: reasons.empty?, reasons: reasons }
+		rescue StandardError => e
+			{ safe: false, reasons: [ e.message ] }
+		end
+
+		# Creates a scoped Runtime for a governed repo with captured output.
+		def build_scoped_runtime( repo_path: )
+			buf = verbose? ? out : StringIO.new
+			err_buf = verbose? ? err : StringIO.new
+			Runtime.new( repo_root: repo_path, tool_root: tool_root, out: buf, err: err_buf, verbose: verbose? )
+		end
 	end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 3.17.0
+  version: 3.19.0
 platform: ruby
 authors:
 - Hailei Wang