carson 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20f9db167969ae68e42a19efcc96c40108f4f3ab3f8b460369283457c9449e4b
-  data.tar.gz: 7e94bf5adcafdbd532bd6e789304e04c2a555b7adcbce441363e681a27493c25
+  metadata.gz: 046c14a614687e668eae6d9f3df0eadbe02fcb103a1c93f25657791a0d72962c
+  data.tar.gz: 26ebca4203a0a9b3df1e38795580188bcf6951049304ae0eb4899deda35106f8
 SHA512:
-  metadata.gz: 7bdc870e0ae003717b5e624d61386a41a89b5dcd20ec0e0c6fa5106b26791b53106bc43f763ca6199e79ca2bac8e76efcbff21d1ebbb126996550b009848f79f
-  data.tar.gz: 19dce95ec2fd4fc5a89de09f8e26b814e6b077285159d425639e68e635eda195d52171c7e388ce27efd27b685f7486e2fc6f8fcf0e7005407cdf672bb9c9f7a2
+  metadata.gz: 38cb7ebf2e65293d5ea26bfb527314d86f7889949db033649fc49822b65feb7b7ea0e8fa5f35b6d959024ff4d280691432efde50dc15c37bf223665cd7d908b7
+  data.tar.gz: d05902ee1637919dd0a9781fa2de46e4370d2806df83c02c730584095f18811baea6168f3614d81900229dd5ec3c141ffb2ce6a40a8c338f233aa1a88a2a9b81

data/RELEASE.md

@@ -5,6 +5,24 @@ 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.1.0 — Worktree Lifecycle
+
+### What changed
+
+- **`carson worktree create <name>`** — creates a worktree under `.claude/worktrees/<name>` with a new branch based on main. One command, one result: path and branch name reported.
+- **`carson worktree done <name>`** — marks a worktree as completed without deleting it. Verifies all changes are committed and pushed. Blocks with actionable guidance if uncommitted changes or unpushed commits exist. The worktree directory persists for batch cleanup later.
+- **Deferred deletion model.** The full worktree lifecycle is now: create → work → done → batch cleanup. No worktree is deleted during an active session. Cleanup happens later via `carson worktree remove` or `carson housekeep`.
+
+### UX
+
+- `carson worktree create` reports path and branch — ready to `cd` into immediately.
+- `carson worktree done` gives recovery commands when changes are uncommitted or unpushed.
+- Error messages across worktree subcommands now show `create|done|remove` in usage hints.
+
+### Migration
+
+- No breaking changes. `carson worktree remove` continues to work as before.
+
 ## 3.0.0 — Agent-Oriented Carson
 
 ### Theme

data/VERSION

@@ -1 +1 @@
-3.0.0
+3.1.0

data/lib/carson/cli.rb

@@ -53,7 +53,7 @@ module Carson
 
 		def self.build_parser
 			OptionParser.new do |opts|
-				opts.banner = "Usage: carson [status [--json]|setup [--remote NAME] [--main-branch NAME] [--workflow STYLE] [--merge METHOD] [--canonical PATH]|audit|sync|prune [--all]|worktree remove <name-or-path>|onboard [repo_path]|refresh [--all|repo_path]|offboard [repo_path]|template check|template apply|review gate|review sweep|govern [--dry-run] [--json] [--loop SECONDS]|version]"
+				opts.banner = "Usage: carson [status [--json]|setup|audit|sync|prune [--all]|worktree create|done|remove <name>|onboard|refresh [--all]|offboard|template check|apply|review gate|sweep|govern [--dry-run] [--json] [--loop SECONDS]|version]"
 			end
 		end
 
@@ -170,12 +170,22 @@ module Carson
 		def self.parse_worktree_subcommand( argv:, parser:, err: )
 			action = argv.shift
 			if action.to_s.strip.empty?
-				err.puts "#{BADGE} Missing subcommand for worktree. Use: carson worktree remove <name-or-path>"
+				err.puts "#{BADGE} Missing subcommand for worktree. Use: carson worktree create|done|remove <name>"
 				err.puts parser
 				return { command: :invalid }
 			end
 
 			case action
+			when "create"
+				name = argv.shift
+				if name.to_s.strip.empty?
+					err.puts "#{BADGE} Missing name for worktree create. Use: carson worktree create <name>"
+					return { command: :invalid }
+				end
+				{ command: "worktree:create", worktree_name: name }
+			when "done"
+				name = argv.shift
+				{ command: "worktree:done", worktree_name: name }
 			when "remove"
 				force = argv.delete( "--force" ) ? true : false
 				worktree_path = argv.shift
@@ -185,7 +195,7 @@ module Carson
 				end
 				{ command: "worktree:remove", worktree_path: worktree_path, force: force }
 			else
-				err.puts "#{BADGE} Unknown worktree subcommand: #{action}. Use: carson worktree remove <name-or-path>"
+				err.puts "#{BADGE} Unknown worktree subcommand: #{action}. Use: carson worktree create|done|remove <name>"
 				{ command: :invalid }
 			end
 		end
@@ -289,6 +299,10 @@ module Carson
 				runtime.prune!
 			when "prune:all"
 				runtime.prune_all!
+			when "worktree:create"
+				runtime.worktree_create!( name: parsed.fetch( :worktree_name ) )
+			when "worktree:done"
+				runtime.worktree_done!( name: parsed.fetch( :worktree_name, nil ) )
 			when "worktree:remove"
 				runtime.worktree_remove!( worktree_path: parsed.fetch( :worktree_path ), force: parsed.fetch( :force, false ) )
 			when "onboard"

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

@@ -2,7 +2,83 @@ module Carson
 	class Runtime
 		module Local
 			# Safe worktree lifecycle management for coding agents.
-			# Enforces the teardown order: exit worktree → git worktree remove → branch cleanup.
+			# Three operations: create, done (mark completed), remove (batch cleanup).
+			# The deferred deletion model: worktrees persist after use, cleaned up later.
+
+			# Creates a new worktree under .claude/worktrees/<name> with a fresh branch.
+			def worktree_create!( name: )
+				worktrees_dir = File.join( repo_root, ".claude", "worktrees" )
+				wt_path = File.join( worktrees_dir, name )
+
+				if Dir.exist?( wt_path )
+					puts_line "ERROR: worktree already exists: #{name}"
+					puts_line "  Path: #{wt_path}"
+					return EXIT_ERROR
+				end
+
+				# Determine the base branch (main branch from config).
+				base = config.main_branch
+
+				# Create the worktree with a new branch based on the main branch.
+				FileUtils.mkdir_p( worktrees_dir )
+				_, wt_stderr, wt_success, = git_run( "worktree", "add", wt_path, "-b", name, base )
+				unless wt_success
+					error_text = wt_stderr.to_s.strip
+					error_text = "unable to create worktree" if error_text.empty?
+					puts_line "ERROR: #{error_text}"
+					return EXIT_ERROR
+				end
+
+				puts_line "Worktree created: #{name}"
+				puts_line "  Path: #{wt_path}"
+				puts_line "  Branch: #{name}"
+				EXIT_OK
+			end
+
+			# Marks a worktree as completed without deleting it.
+			# Verifies all changes are committed. Deferred deletion — cleanup happens later.
+			def worktree_done!( name: nil )
+				if name.to_s.strip.empty?
+					# Try to detect current worktree from CWD.
+					puts_line "ERROR: missing worktree name. Use: carson worktree done <name>"
+					return EXIT_ERROR
+				end
+
+				resolved_path = resolve_worktree_path( worktree_path: name )
+
+				unless worktree_registered?( path: resolved_path )
+					puts_line "ERROR: #{name} is not a registered worktree."
+					return EXIT_ERROR
+				end
+
+				# Check for uncommitted changes in the worktree.
+				wt_status, _, status_success, = Open3.capture3( "git", "status", "--porcelain", chdir: resolved_path )
+				if status_success && !wt_status.strip.empty?
+					puts_line "Worktree has uncommitted changes: #{name}"
+					puts_line "  Commit your changes first, then run `carson worktree done #{name}` again."
+					return EXIT_BLOCK
+				end
+
+				# Check for unpushed commits.
+				branch = worktree_branch( path: resolved_path )
+				if branch
+					remote = config.git_remote
+					remote_ref = "#{remote}/#{branch}"
+					ahead, _, ahead_ok, = Open3.capture3( "git", "rev-list", "--count", "#{remote_ref}..#{branch}", chdir: resolved_path )
+					if ahead_ok && ahead.strip.to_i > 0
+						puts_line "Worktree has unpushed commits: #{name}"
+						puts_line "  Push with `git -C #{resolved_path} push #{remote} #{branch}` first."
+						return EXIT_BLOCK
+					end
+				end
+
+				puts_line "Worktree done: #{name}"
+				puts_line "  Branch: #{branch || '(detached)'}"
+				puts_line "  Cleanup later with `carson worktree remove #{name}` or `carson housekeep`."
+				EXIT_OK
+			end
+
+			# Removes a worktree: directory, git registration, and branch.
 			# Never forces removal — if the worktree has uncommitted changes, refuses unless
 			# the user explicitly passes force: true via CLI --force flag.
 			def worktree_remove!( worktree_path:, force: false )

metadata

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