carson 3.13.2 → 3.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d49ac2582d874ea7b4a25a9d71401fd8424b33ef8740ef8c9d1588d81616b00a
-  data.tar.gz: 37d5ba4ebe4c7455eb1751a55cff6724f073bcce37463080fa3324db86c42fac
+  metadata.gz: 83272d790537e52d22639bbf4831f772496b9ffa5938b23da6d2865ae73d8e38
+  data.tar.gz: ff4d8db79fc54bcd12d74a4c6c74332861ea58dc3fef78f93b3188237d27c772
 SHA512:
-  metadata.gz: 33498b92e55ab4caab2ddb9935ca1ce2b1965e61f03898849720cedbd24e878d981662fa1acad7312addb08d7bb90e83ab72e2f55658087f2af2c3f3d9c37f2c
-  data.tar.gz: 01ee3460c17e00db79f9216592bda4171cc135ceb90ff88d3c83fa8925653f50ad1b3b8ea98e1f6ef37bce1a4f0f2e868d06968d7788e466f54d7d21e99b842b
+  metadata.gz: 655f2cb1f8caa036e96dc17e4e360ced9256840ee5f2050d33e9f72f4187a2f0d8fefbe27d82ff2da8e3bd21f5c8bb460886bf31af922818fa74efeb3fe9d59f
+  data.tar.gz: 44490df6057142b3f58745ac24041e501207599684d9a10816ee505ed192c681661fd4e23003d637a6ccf69f4a86efbd6d754ada2d6079ee99db89b431133495

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,32 @@ 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.15.0
+
+### What changed
+
+- **`carson housekeep` command** — sync + prune for repositories. Carson knocks each gate humbly:
+  - `carson housekeep` — serve the repo you are standing in.
+  - `carson housekeep <repo>` — serve a named governed repo (resolved by basename, case-insensitive).
+  - `carson housekeep --all` — knock each governed repo's gate in turn.
+- Supports `--json` for machine-readable output in all three modes.
+
+### UX improvement
+
+- Fixed double-badge display when housekeep summarises prune results.
+- JSON mode suppresses human-readable lines cleanly.
+
+## 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.
+- **Auto-register on onboard** — `carson onboard` now automatically registers the repository for portfolio governance. No more TTY-only Y/n prompt — onboard means govern.
+
+### UX improvement
+
+- Onboarding is now one step: `carson onboard` sets up hooks, templates, and portfolio registration in a single pass. Works identically in TTY and non-TTY (agent) sessions.
+
 ## 3.13.2
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-3.13.2
+3.15.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 housekeep:all housekeep:target].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>|housekeep [repo] [--json]|repos [--json]|onboard|refresh [--all]|offboard|template check|apply|review gate|sweep|govern [--dry-run] [--json] [--loop SECONDS]|version]"
 			end
 		end
 
@@ -86,6 +86,10 @@ 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 "housekeep"
+				parse_housekeep_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 +303,37 @@ 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_housekeep_command( argv:, err: )
+			all_flag = argv.delete( "--all" ) ? true : false
+			json_flag = argv.delete( "--json" ) ? true : false
+
+			if all_flag && !argv.empty?
+				err.puts "#{BADGE} --all and repo target are mutually exclusive. Use: carson housekeep --all OR carson housekeep [repo]"
+				return { command: :invalid }
+			end
+
+			return { command: "housekeep:all", json: json_flag } if all_flag
+
+			if argv.length > 1
+				err.puts "#{BADGE} Too many arguments for housekeep. Use: carson housekeep [repo]"
+				return { command: :invalid }
+			end
+
+			target = argv.shift
+			return { command: "housekeep:target", target: target, json: json_flag } if target
+
+			{ command: "housekeep", json: json_flag }
+		end
+
 		def self.parse_govern_subcommand( argv:, err: )
 			options = {
 				dry_run: false,
@@ -376,6 +411,14 @@ module Carson
 				runtime.review_gate!
 			when "review:sweep"
 				runtime.review_sweep!
+			when "repos"
+				runtime.repos!( json_output: parsed.fetch( :json, false ) )
+			when "housekeep"
+				runtime.housekeep!( json_output: parsed.fetch( :json, false ) )
+			when "housekeep:target"
+				runtime.housekeep_target!( target: parsed.fetch( :target ), json_output: parsed.fetch( :json, false ) )
+			when "housekeep:all"
+				runtime.housekeep_all!( json_output: parsed.fetch( :json, false ) )
 			when "govern"
 				runtime.govern!(
 					dry_run: parsed.fetch( :dry_run, false ),

data/lib/carson/runtime/housekeep.rb

@@ -0,0 +1,120 @@
+# Housekeeping — sync + prune for a repository.
+# carson housekeep <repo>  — serve one repo by name or path.
+# carson housekeep         — serve the repo you are standing in.
+# carson housekeep --all   — serve all governed repos.
+require "json"
+require "stringio"
+
+module Carson
+	class Runtime
+		module Housekeep
+			# Serves the current repo: sync + prune.
+			def housekeep!( json_output: false )
+				housekeep_one( repo_path: repo_root, json_output: json_output )
+			end
+
+			# Resolves a target name to a governed repo, then serves it.
+			def housekeep_target!( target:, json_output: false )
+				repo_path = resolve_governed_repo( target: target )
+				unless repo_path
+					result = { command: "housekeep", status: "error", error: "Not a governed repository: #{target}", recovery: "Run carson repos to see governed repositories." }
+					return housekeep_finish( result: result, exit_code: EXIT_ERROR, json_output: json_output )
+				end
+
+				housekeep_one( repo_path: repo_path, json_output: json_output )
+			end
+
+			# Knocks each governed repo's gate in turn.
+			def housekeep_all!( json_output: false )
+				repos = config.govern_repos
+				if repos.empty?
+					result = { command: "housekeep", status: "error", error: "No governed repositories configured.", recovery: "Run carson onboard in each repo to register." }
+					return housekeep_finish( result: result, exit_code: EXIT_ERROR, json_output: json_output )
+				end
+
+				results = []
+				repos.each { |repo_path| results << housekeep_one_entry( repo_path: repo_path, silent: json_output ) }
+
+				succeeded = results.count { |r| r[ :status ] == "ok" }
+				failed = results.count { |r| r[ :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
+
+		private
+
+			# Runs sync + prune on one repo and returns the exit code directly.
+			def housekeep_one( repo_path:, json_output: false )
+				entry = housekeep_one_entry( repo_path: repo_path, silent: json_output )
+				ok = entry[ :status ] == "ok"
+				result = { command: "housekeep", status: ok ? "ok" : "error", repos: [ entry ], succeeded: ok ? 1 : 0, failed: ok ? 0 : 1 }
+				housekeep_finish( result: result, exit_code: ok ? EXIT_OK : EXIT_ERROR, json_output: json_output, results: [ entry ], succeeded: result[ :succeeded ], failed: result[ :failed ] )
+			end
+
+			# Runs sync + prune on a single repository. Returns a result hash.
+			def housekeep_one_entry( repo_path:, silent: false )
+				repo_name = File.basename( repo_path )
+				unless Dir.exist?( repo_path )
+					puts_line "#{repo_name}: SKIP (path not found)" unless silent
+					return { name: repo_name, path: repo_path, status: "error", error: "path not found" }
+				end
+
+				buf = verbose? ? out : StringIO.new
+				err_buf = verbose? ? err : StringIO.new
+				rt = Runtime.new( repo_root: repo_path, tool_root: tool_root, out: buf, err: err_buf, verbose: verbose? )
+
+				sync_status = rt.sync!
+				prune_status = rt.prune! if sync_status == EXIT_OK
+
+				ok = sync_status == EXIT_OK && prune_status == EXIT_OK
+				unless verbose? || silent
+					summary = strip_badge( buf.string.lines.last.to_s.strip )
+					puts_line "#{repo_name}: #{summary.empty? ? 'OK' : summary}"
+				end
+
+				{ name: repo_name, path: repo_path, status: ok ? "ok" : "error" }
+			rescue StandardError => e
+				puts_line "#{repo_name}: FAIL (#{e.message})" unless silent
+				{ name: repo_name, path: repo_path, status: "error", error: e.message }
+			end
+
+			# Strips the Carson badge prefix from a message to avoid double-badging.
+			def strip_badge( text )
+				text.sub( /\A#{Regexp.escape( BADGE )}\s*/, "" )
+			end
+
+			# Resolves a user-supplied target to a governed repository path.
+			# Accepts: exact path, expandable path, or basename match (case-insensitive).
+			def resolve_governed_repo( target: )
+				repos = config.govern_repos
+				expanded = File.expand_path( target )
+				return expanded if repos.include?( expanded )
+
+				downcased = File.basename( target ).downcase
+				repos.find { |r| File.basename( r ).downcase == downcased }
+			end
+
+			# Unified output — JSON or human-readable.
+			def housekeep_finish( result:, exit_code:, json_output:, results: nil, succeeded: nil, failed: nil )
+				result[ :exit_code ] = exit_code
+
+				if json_output
+					out.puts JSON.pretty_generate( result )
+				else
+					if results && ( succeeded || failed )
+						total = ( succeeded || 0 ) + ( failed || 0 )
+						puts_line ""
+						puts_line "Housekeep complete: #{succeeded} cleaned, #{failed} failed (#{total} repo#{plural_suffix( count: total )})."
+					elsif result[ :error ]
+						puts_line result[ :error ]
+						puts_line "  #{result[ :recovery ]}" if result[ :recovery ]
+					end
+				end
+
+				exit_code
+			end
+		end
+
+		include Housekeep
+	end
+end

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,8 @@ end
 
 require_relative "runtime/local"
 require_relative "runtime/audit"
+require_relative "runtime/housekeep"
+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.15.0
 platform: ruby
 authors:
 - Hailei Wang
@@ -54,6 +54,7 @@ files:
 - lib/carson/runtime/audit.rb
 - lib/carson/runtime/deliver.rb
 - lib/carson/runtime/govern.rb
+- lib/carson/runtime/housekeep.rb
 - lib/carson/runtime/local.rb
 - lib/carson/runtime/local/hooks.rb
 - lib/carson/runtime/local/onboard.rb
@@ -61,6 +62,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