carson 3.13.2 → 3.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d49ac2582d874ea7b4a25a9d71401fd8424b33ef8740ef8c9d1588d81616b00a
-  data.tar.gz: 37d5ba4ebe4c7455eb1751a55cff6724f073bcce37463080fa3324db86c42fac
+  metadata.gz: a6187204d01b1fc7f62657f451451a0124e039b265d83379ce8c23e9ba62a346
+  data.tar.gz: d5b11033558afc8847386858bc62d9ba19816636dece60dfe4a5f1708528a50f
 SHA512:
-  metadata.gz: 33498b92e55ab4caab2ddb9935ca1ce2b1965e61f03898849720cedbd24e878d981662fa1acad7312addb08d7bb90e83ab72e2f55658087f2af2c3f3d9c37f2c
-  data.tar.gz: 01ee3460c17e00db79f9216592bda4171cc135ceb90ff88d3c83fa8925653f50ad1b3b8ea98e1f6ef37bce1a4f0f2e868d06968d7788e466f54d7d21e99b842b
+  metadata.gz: 005575df223f30f900794447f012d29bfa3c6a939433870da80dd54cdbcb43dd9099413357a049232ffdcd7d7c502996e3d4279a40f310fde576fe991c8659a0
+  data.tar.gz: 9c4c5023488bce12162fbcb0c4746db515c72e2b28618ca35682a3076ec2b3c1c67513af7712cb4238dc76a2fd389f9abf75385baf6d63ea10970be960d949e9

data/MANUAL.md

@@ -142,6 +142,36 @@ carson prune
 
 After squash or rebase merge, the content matches main — removal proceeds without `--force`.
 
+### Carson vs Claude Code EnterWorktree
+
+Claude Code has a built-in `EnterWorktree` tool. Both create a git worktree under `.claude/worktrees/` with a new branch — but they solve different problems and have different trade-offs.
+
+**What Carson adds over EnterWorktree:**
+
+| Concern | EnterWorktree | Carson |
+|---|---|---|
+| Auto-sync main before branching | No — branches from current HEAD, which may be stale | Yes — `git pull --ff-only` before branch creation |
+| CWD guard on removal | No | Yes — blocks if shell is inside the worktree |
+| Unpushed-commits guard | No | Yes — blocks if work hasn't been pushed |
+| Content-aware squash/rebase detection | No | Yes — compares tree content, not SHAs |
+| Branch cleanup (local + remote) | No | Yes — one command removes worktree, local branch, and remote branch |
+| `.git/info/exclude` management | No | Yes — prevents `.claude/` appearing as untracked |
+| Recovery-aware errors | No | Yes — every error includes a concrete recovery command |
+| `--json` output | No | Yes — machine-readable for agent consumption |
+
+**What EnterWorktree does that Carson does not:**
+
+- **Automatic session CWD switch.** After creating the worktree, Claude Code moves the agent's working directory into it — no manual `cd` required. This is genuine friction that Carson should learn from.
+
+**What EnterWorktree gets wrong:**
+
+- **Session-exit cleanup prompt.** On session exit, Claude Code asks the user whether to keep or remove each worktree. In an agent workflow this is pure friction — the user cannot verify the state of bot-created worktrees and is forced to choose "keep" every time. Carson's approach is better: deferred deletion by default, with safety guards when you do choose to clean up.
+- **Random names.** Without a name argument, EnterWorktree generates a random string. `git branch` output becomes unreadable. Carson requires a meaningful name that doubles as the branch name.
+
+**Relationship — complementary, not competing:**
+
+The two tools serve different layers. EnterWorktree owns the session (CWD switch); Carson owns the git lifecycle (sync, safety, cleanup). The ideal integration is Claude Code's `WorktreeCreate`/`WorktreeRemove` hook mechanism — Carson registers as the hook handler, so `EnterWorktree` delegates creation to `carson worktree create` and gets both Carson's safety and Claude Code's automatic CWD switch.
+
 ## Daily Operations
 
 **Start of work:**
@@ -170,6 +200,13 @@ carson template apply
 carson review gate
 ```
 
+**Portfolio overview:**
+
+```bash
+carson repos           # list all governed repositories
+carson repos --json    # machine-readable output
+```
+
 **Periodic maintenance:**
 
 ```bash

data/README.md

@@ -29,6 +29,8 @@ Carson is an autonomous governance runtime that lives on your workstation and in
 
 This separation is Carson's defining trait — the **outsider boundary**: no Carson scripts, config files, or governance payloads are ever placed inside a governed repository.
 
+**Agent workspace management** — `carson worktree create` and `carson worktree remove` give coding agents safe, isolated workspaces. Unlike Claude Code's built-in `EnterWorktree`, Carson auto-syncs main before branching, guards against removing worktrees with unpushed work or an active shell inside, detects squash/rebase merges so removal doesn't falsely block, and cleans up the local and remote branch in one step. The two tools are complementary — see `MANUAL.md § Carson vs Claude Code EnterWorktree` for the full comparison.
+
 ### The Governance Loop
 
 Carson orchestrates a closed governance loop across two layers:

data/RELEASE.md

@@ -5,6 +5,16 @@ 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.14.0
+
+### What changed
+
+- **`carson repos` command** — lists all governed repositories from Carson's global config. Shows which repos Carson is serving at a glance. Supports `--json` for machine-readable output. Portfolio-level command — works from any directory.
+
+### UX improvement
+
+- Bots and humans can now verify which repos Carson oversees with a single command instead of reading raw config JSON.
+
 ## 3.13.2
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-3.13.2
+3.14.0

data/lib/carson/cli.rb

@@ -12,7 +12,7 @@ module Carson
 				return Runtime::EXIT_OK
 			end
 
-			if %w[refresh:all prune:all].include?( command )
+			if %w[repos refresh:all prune: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 )
@@ -53,7 +53,7 @@ module Carson
 
 		def self.build_parser
 			OptionParser.new do |opts|
-				opts.banner = "Usage: carson [status [--json]|setup|audit [--json]|sync [--json]|deliver [--merge] [--json] [--title T] [--body-file F]|prune [--all] [--json]|worktree [--json] create|remove <name>|onboard|refresh [--all]|offboard|template check|apply|review gate|sweep|govern [--dry-run] [--json] [--loop SECONDS]|version]"
+				opts.banner = "Usage: carson [status [--json]|setup|audit [--json]|sync [--json]|deliver [--merge] [--json] [--title T] [--body-file F]|prune [--all] [--json]|worktree [--json] create|remove <name>|repos [--json]|onboard|refresh [--all]|offboard|template check|apply|review gate|sweep|govern [--dry-run] [--json] [--loop SECONDS]|version]"
 			end
 		end
 
@@ -86,6 +86,8 @@ module Carson
 				parse_prune_command( argv: argv, parser: parser, err: err )
 			when "worktree"
 				parse_worktree_subcommand( argv: argv, parser: parser, err: err )
+			when "repos"
+				parse_repos_command( argv: argv, err: err )
 			when "review"
 				parse_named_subcommand( command: command, usage: "gate|sweep", argv: argv, parser: parser, err: err )
 			when "audit"
@@ -299,6 +301,15 @@ module Carson
 			{ command: :invalid }
 		end
 
+		def self.parse_repos_command( argv:, err: )
+			json_flag = argv.delete( "--json" ) ? true : false
+			unless argv.empty?
+				err.puts "#{BADGE} Unexpected arguments for repos: #{argv.join( ' ' )}"
+				return { command: :invalid }
+			end
+			{ command: "repos", json: json_flag }
+		end
+
 		def self.parse_govern_subcommand( argv:, err: )
 			options = {
 				dry_run: false,
@@ -376,6 +387,8 @@ module Carson
 				runtime.review_gate!
 			when "review:sweep"
 				runtime.review_sweep!
+			when "repos"
+				runtime.repos!( json_output: parsed.fetch( :json, false ) )
 			when "govern"
 				runtime.govern!(
 					dry_run: parsed.fetch( :dry_run, false ),

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

@@ -229,11 +229,7 @@ module Carson
 				puts_line ""
 				puts_line "Carson at your service."
 
-				if self.in.respond_to?( :tty? ) && self.in.tty?
-					prompt_govern_registration!
-				else
-					puts_line "To register for portfolio governance: carson onboard (in a TTY)"
-				end
+				auto_register_govern!
 
 				puts_line ""
 				puts_line "Your repository is set up. Carson has placed files in your"

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

@@ -1,6 +1,7 @@
 # Safe worktree lifecycle management for coding agents.
-# Two operations: create and remove. Remove is safe by default — guards against
-# CWD-inside-worktree and unpushed commits. Use --force to override.
+# Two operations: create and remove. Create auto-syncs main before branching.
+# Remove is safe by default — guards against CWD-inside-worktree and unpushed
+# commits. Content-aware: allows removal after squash/rebase merge without --force.
 # Supports --json for machine-readable structured output with recovery commands.
 module Carson
 	class Runtime

data/lib/carson/runtime/repos.rb

@@ -0,0 +1,29 @@
+# Lists governed repositories from Carson's global config.
+# Portfolio-level query — not scoped to any single repository.
+require "json"
+
+module Carson
+	class Runtime
+		module Repos
+			def repos!( json_output: false )
+				repos = config.govern_repos
+
+				if json_output
+					out.puts JSON.pretty_generate( { command: "repos", repos: repos } )
+				else
+					if repos.empty?
+						puts_line "No governed repositories."
+						puts_line "  Run carson onboard in a repo to register it."
+					else
+						puts_line "Governed repositories (#{repos.length}):"
+						repos.each { |path| puts_line "  #{path}" }
+					end
+				end
+
+				EXIT_OK
+			end
+		end
+
+		include Repos
+	end
+end

data/lib/carson/runtime/setup.rb

@@ -368,24 +368,16 @@ module Carson
 				!path.empty? && File.file?( path )
 			end
 
-			# After onboard succeeds, offer to register the repo for portfolio governance.
-			def prompt_govern_registration!
+			# Automatically registers the repo for portfolio governance during onboard.
+			def auto_register_govern!
 				expanded = File.expand_path( repo_root )
 				if config.govern_repos.include?( expanded )
 					puts_verbose "govern_registration: already registered #{expanded}"
 					return
 				end
 
-				puts_line ""
-				puts_line "Portfolio governance"
-				puts_line "  Register this repo so carson refresh --all and carson govern include it?"
-				accepted = prompt_yes_no( default: true )
-				if accepted
-					append_govern_repo!( repo_path: expanded )
-					puts_line "Registered. Run carson refresh --all to keep all repos in sync."
-				else
-					puts_line "Skipped. Run carson onboard here again to register later."
-				end
+				append_govern_repo!( repo_path: expanded )
+				puts_line "Registered for portfolio governance."
 			end
 
 			# Reusable Y/n prompt following existing prompt_choice conventions.

data/lib/carson/runtime.rb

@@ -217,6 +217,7 @@ end
 
 require_relative "runtime/local"
 require_relative "runtime/audit"
+require_relative "runtime/repos"
 require_relative "runtime/review"
 require_relative "runtime/govern"
 require_relative "runtime/setup"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 3.13.2
+  version: 3.14.0
 platform: ruby
 authors:
 - Hailei Wang
@@ -61,6 +61,7 @@ files:
 - lib/carson/runtime/local/sync.rb
 - lib/carson/runtime/local/template.rb
 - lib/carson/runtime/local/worktree.rb
+- lib/carson/runtime/repos.rb
 - lib/carson/runtime/review.rb
 - lib/carson/runtime/review/data_access.rb
 - lib/carson/runtime/review/gate_support.rb