carson 3.5.0 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8fc2b54698568aaec7d7f4ec39ecd32f56f44a395555a34099b24ec52a1d608
-  data.tar.gz: e3b0a5a14c733d6b2e9f5c08475d89a53f0a3d1faf8a2fb85ed72bcb76f662ef
+  metadata.gz: 43f5ee17800cad35a51d2aaaf6ce306197bf2823cc6b0de4858912213d06e01b
+  data.tar.gz: 51b3a3e91d84a98266b2bccee868e583c25609c5466e34c938b2fa2bcd6564fc
 SHA512:
-  metadata.gz: 9d3733f98a23dffdc69c1ebde71e94595c22e662f5ead86b97988fa3f5cf0e8daf56806deb82ceb1d034e0913640d9a8b7cafc26992f94e43dd96a3e304d6812
-  data.tar.gz: eb44eca84a943a461668b478e2bed295b3a73ee7e916cc5d85a837c52f5be09326b369e07a99812d4ffdc883914511d18c7f0489e151f3d4d66afe8ddaf97402
+  metadata.gz: c7bca3554a185fc1951292d62e0bfcfd6b63d77488d22013f14b93885e6b8d043d2d30e20e8e9725796d26bc3aaa031bcce8f0b28474ab3198bf77733c56f0c5
+  data.tar.gz: ce3240db72d7fb1c6a5aa9f590628d23e3533778cc492def9c73951a8f5b6772a347cb8d64c79e0063fb79f67f16fb663c9a8ecdc33db7f9af15e0204678adfd

data/RELEASE.md

@@ -5,6 +5,42 @@ 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.7.0 — Worktree JSON + Recovery
+
+### What changed
+
+- **`carson worktree --json create|done|remove`** — machine-readable JSON output for all three worktree commands. Each returns a structured envelope with `command`, `status`, `name`, `exit_code`, and context-specific fields (`path`, `branch`, `next_step`).
+- **Recovery-aware worktree errors** — every error and block path includes a `recovery` field with the exact command to run next. Dirty worktree, missing name, unregistered worktree, unpushed commits — all include actionable recovery.
+- **Unified `worktree_finish` / `print_worktree_human`** — consistent output pattern matching deliver, sync, and prune.
+
+### UX
+
+- Human output preserved unchanged when `--json` is not passed.
+- `worktree done` includes `next_step` in JSON output pointing to `carson worktree remove`.
+- `worktree remove` includes `branch_deleted` and `remote_deleted` booleans for complete lifecycle visibility.
+
+### Migration
+
+- No breaking changes. All worktree commands without `--json` behave identically to 3.6.0.
+
+## 3.6.0 — Prune JSON + Recovery
+
+### What changed
+
+- **`carson prune --json`** — machine-readable JSON output for the prune command. The JSON envelope includes `command`, `status`, `branches` (array of per-branch details), `deleted`, `skipped`, and `exit_code`. Each branch entry has `branch`, `upstream`, `type` (stale/orphan/absorbed), `action` (deleted/skipped), and `reason`.
+- **Recovery-aware prune errors** — outsider fingerprint blocks now include the specific recovery command in JSON output.
+- **Structured branch entries** — internal prune methods now return structured hashes instead of bare symbols, enabling per-branch detail collection for JSON mode.
+
+### UX
+
+- JSON output suppresses `git fetch` stdout to keep the JSON envelope clean.
+- Human output remains unchanged when `--json` is not passed.
+- All existing prune tests pass unchanged — human output behaviour is preserved.
+
+### Migration
+
+- No breaking changes. `carson prune` without `--json` behaves identically to 3.5.0.
+
 ## 3.5.0 — Sync JSON + Recovery
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-3.5.0
+3.7.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|audit [--json]|sync [--json]|deliver [--merge] [--json] [--title T] [--body-file F]|prune [--all]|worktree create|done|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|done|remove <name>|onboard|refresh [--all]|offboard|template check|apply|review gate|sweep|govern [--dry-run] [--json] [--loop SECONDS]|version]"
 			end
 		end
 
@@ -168,12 +168,14 @@ module Carson
 
 		def self.parse_prune_command( argv:, parser:, err: )
 			all_flag = argv.delete( "--all" ) ? true : false
+			json_flag = argv.delete( "--json" ) ? true : false
 			parser.parse!( argv )
-			return { command: "prune:all" } if all_flag
-			{ command: "prune" }
+			return { command: "prune:all", json: json_flag } if all_flag
+			{ command: "prune", json: json_flag }
 		end
 
 		def self.parse_worktree_subcommand( argv:, parser:, err: )
+			json_flag = argv.delete( "--json" ) ? true : false
 			action = argv.shift
 			if action.to_s.strip.empty?
 				err.puts "#{BADGE} Missing subcommand for worktree. Use: carson worktree create|done|remove <name>"
@@ -188,10 +190,10 @@ module Carson
 					err.puts "#{BADGE} Missing name for worktree create. Use: carson worktree create <name>"
 					return { command: :invalid }
 				end
-				{ command: "worktree:create", worktree_name: name }
+				{ command: "worktree:create", worktree_name: name, json: json_flag }
 			when "done"
 				name = argv.shift
-				{ command: "worktree:done", worktree_name: name }
+				{ command: "worktree:done", worktree_name: name, json: json_flag }
 			when "remove"
 				force = argv.delete( "--force" ) ? true : false
 				worktree_path = argv.shift
@@ -199,7 +201,7 @@ module Carson
 					err.puts "#{BADGE} Missing path for worktree remove. Use: carson worktree remove <name-or-path>"
 					return { command: :invalid }
 				end
-				{ command: "worktree:remove", worktree_path: worktree_path, force: force }
+				{ command: "worktree:remove", worktree_path: worktree_path, force: force, json: json_flag }
 			else
 				err.puts "#{BADGE} Unknown worktree subcommand: #{action}. Use: carson worktree create|done|remove <name>"
 				{ command: :invalid }
@@ -347,15 +349,15 @@ module Carson
 			when "sync"
 				runtime.sync!( json_output: parsed.fetch( :json, false ) )
 			when "prune"
-				runtime.prune!
+				runtime.prune!( json_output: parsed.fetch( :json, false ) )
 			when "prune:all"
 				runtime.prune_all!
 			when "worktree:create"
-				runtime.worktree_create!( name: parsed.fetch( :worktree_name ) )
+				runtime.worktree_create!( name: parsed.fetch( :worktree_name ), json_output: parsed.fetch( :json, false ) )
 			when "worktree:done"
-				runtime.worktree_done!( name: parsed.fetch( :worktree_name, nil ) )
+				runtime.worktree_done!( name: parsed.fetch( :worktree_name, nil ), json_output: parsed.fetch( :json, false ) )
 			when "worktree:remove"
-				runtime.worktree_remove!( worktree_path: parsed.fetch( :worktree_path ), force: parsed.fetch( :force, false ) )
+				runtime.worktree_remove!( worktree_path: parsed.fetch( :worktree_path ), force: parsed.fetch( :force, false ), json_output: parsed.fetch( :json, false ) )
 			when "onboard"
 				runtime.onboard!
 			when "refresh"

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

@@ -1,31 +1,74 @@
+# Removes stale local branches (gone upstream), orphan branches (no tracking) with merged PR evidence,
+# and absorbed branches (content already on main, no open PR).
+# Supports --json for machine-readable structured output with per-branch action details.
 module Carson
 	class Runtime
 		module Local
-			# Removes stale local branches (gone upstream), orphan branches (no tracking) with merged PR evidence,
-			# and absorbed branches (content already on main, no open PR).
-			def prune!
+			def prune!( json_output: false )
 				fingerprint_status = block_if_outsider_fingerprints!
-				return fingerprint_status unless fingerprint_status.nil?
+				unless fingerprint_status.nil?
+					if json_output
+						out.puts JSON.pretty_generate( {
+							command: "prune", status: "block",
+							error: "Carson-owned artefacts detected in host repository",
+							recovery: "remove Carson-owned files (.carson.yml, bin/carson, .tools/carson) then retry",
+							exit_code: EXIT_BLOCK
+						} )
+					end
+					return fingerprint_status
+				end
 
-				git_system!( "fetch", config.git_remote, "--prune" )
+				prune_git!( "fetch", config.git_remote, "--prune", json_output: json_output )
 				active_branch = current_branch
 				counters = { deleted: 0, skipped: 0 }
+				branches = []
 
 				stale_branches = stale_local_branches
-				prune_stale_branch_entries( stale_branches: stale_branches, active_branch: active_branch, counters: counters )
+				prune_stale_branch_entries( stale_branches: stale_branches, active_branch: active_branch, counters: counters, branches: branches )
 
 				orphan_branches = orphan_local_branches( active_branch: active_branch )
-				prune_orphan_branch_entries( orphan_branches: orphan_branches, counters: counters )
+				prune_orphan_branch_entries( orphan_branches: orphan_branches, counters: counters, branches: branches )
 
 				absorbed_branches = absorbed_local_branches( active_branch: active_branch )
-				prune_absorbed_branch_entries( absorbed_branches: absorbed_branches, counters: counters )
+				prune_absorbed_branch_entries( absorbed_branches: absorbed_branches, counters: counters, branches: branches )
+
+				prune_finish(
+					result: { command: "prune", status: "ok", branches: branches, deleted: counters.fetch( :deleted ), skipped: counters.fetch( :skipped ) },
+					exit_code: EXIT_OK, json_output: json_output, counters: counters
+				)
+			end
 
-				return prune_no_stale_branches if counters.fetch( :deleted ).zero? && counters.fetch( :skipped ).zero?
+		private
+
+			# Unified output for prune results — JSON or human-readable.
+			def prune_finish( result:, exit_code:, json_output:, counters: )
+				result[ :exit_code ] = exit_code
+
+				if json_output
+					out.puts JSON.pretty_generate( result )
+				else
+					print_prune_human( counters: counters )
+				end
 
-				puts_verbose "prune_summary: deleted=#{counters.fetch( :deleted )} skipped=#{counters.fetch( :skipped )}"
+				exit_code
+			end
+
+			# Human-readable output for prune results.
+			def print_prune_human( counters: )
+				deleted_count = counters.fetch( :deleted )
+				skipped_count = counters.fetch( :skipped )
+
+				if deleted_count.zero? && skipped_count.zero?
+					if verbose?
+						puts_line "OK: no stale or orphan branches to prune."
+					else
+						puts_line "No stale branches."
+					end
+					return
+				end
+
+				puts_verbose "prune_summary: deleted=#{deleted_count} skipped=#{skipped_count}"
 				unless verbose?
-					deleted_count = counters.fetch( :deleted )
-					skipped_count = counters.fetch( :skipped )
 					message = if deleted_count > 0 && skipped_count > 0
 						"Pruned #{deleted_count}, skipped #{skipped_count} (--verbose for details)."
 					elsif deleted_count > 0
@@ -35,24 +78,23 @@ module Carson
 					end
 					puts_line message
 				end
-				EXIT_OK
 			end
 
-		private
-
-			def prune_no_stale_branches
-				if verbose?
-					puts_line "OK: no stale or orphan branches to prune."
+			# Runs a git command, suppressing stdout in JSON mode to keep output clean.
+			def prune_git!( *args, json_output: false )
+				if json_output
+					_, stderr_text, success, = git_run( *args )
+					raise "git #{args.join( ' ' )} failed: #{stderr_text.to_s.strip}" unless success
 				else
-					puts_line "No stale branches."
+					git_system!( *args )
 				end
-				EXIT_OK
 			end
 
-			def prune_stale_branch_entries( stale_branches:, active_branch:, counters: { deleted: 0, skipped: 0 } )
+			def prune_stale_branch_entries( stale_branches:, active_branch:, counters: { deleted: 0, skipped: 0 }, branches: [] )
 				stale_branches.each do |entry|
-					outcome = prune_stale_branch_entry( entry: entry, active_branch: active_branch )
-					counters[ outcome ] += 1
+					result = prune_stale_branch_entry( entry: entry, active_branch: active_branch )
+					counters[ result.fetch( :action ) ] += 1
+					branches << result
 				end
 				counters
 			end
@@ -67,9 +109,10 @@ module Carson
 			end
 
 			def prune_skip_stale_branch( type:, branch:, upstream: )
+				reason = type == :protected ? "protected branch" : "current branch"
 				status = type == :protected ? "skip_protected_branch" : "skip_current_branch"
 				puts_verbose "#{status}: #{branch} (upstream=#{upstream})"
-				:skipped
+				{ action: :skipped, branch: branch, upstream: upstream, type: "stale", reason: reason }
 			end
 
 			def prune_delete_stale_branch( branch:, upstream: )
@@ -87,7 +130,7 @@ module Carson
 			def prune_safe_delete_success( branch:, upstream:, stdout_text: )
 				out.print stdout_text if verbose? && !stdout_text.empty?
 				puts_verbose "deleted_local_branch: #{branch} (upstream=#{upstream})"
-				:deleted
+				{ action: :deleted, branch: branch, upstream: upstream, type: "stale", reason: "upstream gone" }
 			end
 
 			def prune_force_delete_stale_branch( branch:, upstream:, delete_error_text: )
@@ -106,19 +149,19 @@ module Carson
 			def prune_force_delete_success( branch:, upstream:, merged_pr:, force_stdout: )
 				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
+				{ action: :deleted, branch: branch, upstream: upstream, type: "stale", reason: "force deleted with PR evidence" }
 			end
 
 			def prune_force_delete_failed( branch:, upstream:, force_stderr: )
 				force_error_text = normalise_branch_delete_error( error_text: force_stderr )
 				puts_verbose "fail_force_delete_branch: #{branch} (upstream=#{upstream}) reason=#{force_error_text}"
-				:skipped
+				{ action: :skipped, branch: branch, upstream: upstream, type: "stale", reason: force_error_text }
 			end
 
 			def prune_force_delete_skipped( branch:, upstream:, delete_error_text:, force_error: )
 				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
+				{ action: :skipped, branch: branch, upstream: upstream, type: "stale", reason: delete_error_text }
 			end
 
 			def normalise_branch_delete_error( error_text: )
@@ -229,13 +272,14 @@ module Carson
 			end
 
 			# Processes absorbed branches: verifies no open PR exists before deleting local and remote.
-			def prune_absorbed_branch_entries( absorbed_branches:, counters: )
+			def prune_absorbed_branch_entries( absorbed_branches:, counters:, branches: [] )
 				return counters if absorbed_branches.empty?
 				return counters unless gh_available?
 
 				absorbed_branches.each do |entry|
-					outcome = prune_absorbed_branch_entry( branch: entry.fetch( :branch ), upstream: entry.fetch( :upstream ) )
-					counters[ outcome ] += 1
+					result = prune_absorbed_branch_entry( branch: entry.fetch( :branch ), upstream: entry.fetch( :upstream ) )
+					counters[ result.fetch( :action ) ] += 1
+					branches << result
 				end
 				counters
 			end
@@ -244,14 +288,14 @@ module Carson
 			def prune_absorbed_branch_entry( branch:, upstream: )
 				if branch_has_open_pr?( branch: branch )
 					puts_verbose "skip_absorbed_branch: #{branch} reason=open PR exists"
-					return :skipped
+					return { action: :skipped, branch: branch, upstream: upstream, type: "absorbed", reason: "open PR exists" }
 				end
 
 				force_stdout, force_stderr, force_success = force_delete_local_branch( branch: branch )
 				unless force_success
 					error_text = normalise_branch_delete_error( error_text: force_stderr )
 					puts_verbose "fail_delete_absorbed_branch: #{branch} reason=#{error_text}"
-					return :skipped
+					return { action: :skipped, branch: branch, upstream: upstream, type: "absorbed", reason: error_text }
 				end
 
 				out.print force_stdout if verbose? && !force_stdout.empty?
@@ -260,7 +304,7 @@ module Carson
 				git_run( "push", config.git_remote, "--delete", remote_branch )
 
 				puts_verbose "deleted_absorbed_branch: #{branch} (upstream=#{upstream})"
-				:deleted
+				{ action: :deleted, branch: branch, upstream: upstream, type: "absorbed", reason: "content already on main" }
 			end
 
 			# Returns true if the branch has at least one open PR.
@@ -282,13 +326,14 @@ module Carson
 			end
 
 			# Processes orphan branches: verifies merged PR evidence via GitHub API before deleting.
-			def prune_orphan_branch_entries( orphan_branches:, counters: )
+			def prune_orphan_branch_entries( orphan_branches:, counters:, branches: [] )
 				return counters if orphan_branches.empty?
 				return counters unless gh_available?
 
 				orphan_branches.each do |branch|
-					outcome = prune_orphan_branch_entry( branch: branch )
-					counters[ outcome ] += 1
+					result = prune_orphan_branch_entry( branch: branch )
+					counters[ result.fetch( :action ) ] += 1
+					branches << result
 				end
 				counters
 			end
@@ -300,12 +345,12 @@ module Carson
 					error_text = tip_sha_error.to_s.strip
 					error_text = "unable to read local branch tip sha" if error_text.empty?
 					puts_verbose "skip_orphan_branch: #{branch} reason=#{error_text}"
-					return :skipped
+					return { action: :skipped, branch: branch, upstream: "", type: "orphan", reason: error_text }
 				end
 				branch_tip_sha = tip_sha_text.to_s.strip
 				if branch_tip_sha.empty?
 					puts_verbose "skip_orphan_branch: #{branch} reason=unable to read local branch tip sha"
-					return :skipped
+					return { action: :skipped, branch: branch, upstream: "", type: "orphan", reason: "unable to read local branch tip sha" }
 				end
 
 				merged_pr, error = merged_pr_for_branch( branch: branch, branch_tip_sha: branch_tip_sha )
@@ -313,19 +358,19 @@ module Carson
 					reason = error.to_s.strip
 					reason = "no merged PR evidence for branch tip into #{config.main_branch}" if reason.empty?
 					puts_verbose "skip_orphan_branch: #{branch} reason=#{reason}"
-					return :skipped
+					return { action: :skipped, branch: branch, upstream: "", type: "orphan", reason: reason }
 				end
 
 				force_stdout, force_stderr, force_success = force_delete_local_branch( branch: branch )
 				if force_success
 					out.print force_stdout if verbose? && !force_stdout.empty?
 					puts_verbose "deleted_orphan_branch: #{branch} merged_pr=#{merged_pr.fetch( :url )}"
-					return :deleted
+					return { action: :deleted, branch: branch, upstream: "", type: "orphan", reason: "merged PR evidence found" }
 				end
 
 				force_error_text = normalise_branch_delete_error( error_text: force_stderr )
 				puts_verbose "fail_delete_orphan_branch: #{branch} reason=#{force_error_text}"
-				:skipped
+				{ action: :skipped, branch: branch, upstream: "", type: "orphan", reason: force_error_text }
 			end
 
 			# Safe delete can fail after squash merges because branch tip is no longer an ancestor.

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

@@ -1,19 +1,23 @@
+# Safe worktree lifecycle management for coding agents.
+# Three operations: create, done (mark completed), remove (batch cleanup).
+# The deferred deletion model: worktrees persist after use, cleaned up later.
+# Supports --json for machine-readable structured output with recovery commands.
 module Carson
 	class Runtime
 		module Local
-			# Safe worktree lifecycle management for coding agents.
-			# 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: )
+			def worktree_create!( name:, json_output: false )
 				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
+					return worktree_finish(
+						result: { command: "worktree create", status: "error", name: name, path: wt_path,
+							error: "worktree already exists: #{name}",
+							recovery: "carson worktree remove #{name}, then retry" },
+						exit_code: EXIT_ERROR, json_output: json_output
+					)
 				end
 
 				# Determine the base branch (main branch from config).
@@ -25,38 +29,51 @@ module Carson
 				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
+					return worktree_finish(
+						result: { command: "worktree create", status: "error", name: name,
+							error: error_text },
+						exit_code: EXIT_ERROR, json_output: json_output
+					)
 				end
 
-				puts_line "Worktree created: #{name}"
-				puts_line "  Path: #{wt_path}"
-				puts_line "  Branch: #{name}"
-				EXIT_OK
+				worktree_finish(
+					result: { command: "worktree create", status: "ok", name: name, path: wt_path, branch: name },
+					exit_code: EXIT_OK, json_output: json_output
+				)
 			end
 
 			# Marks a worktree as completed without deleting it.
 			# Verifies all changes are committed. Deferred deletion — cleanup happens later.
-			def worktree_done!( name: nil )
+			def worktree_done!( name: nil, json_output: false )
 				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
+					return worktree_finish(
+						result: { command: "worktree done", status: "error",
+							error: "missing worktree name",
+							recovery: "carson worktree done <name>" },
+						exit_code: EXIT_ERROR, json_output: json_output
+					)
 				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
+					return worktree_finish(
+						result: { command: "worktree done", status: "error", name: name,
+							error: "#{name} is not a registered worktree",
+							recovery: "git worktree list" },
+						exit_code: EXIT_ERROR, json_output: json_output
+					)
 				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
+					return worktree_finish(
+						result: { command: "worktree done", status: "block", name: name,
+							error: "worktree has uncommitted changes",
+							recovery: "git -C #{resolved_path} add -A && git -C #{resolved_path} commit, then carson worktree done #{name}" },
+						exit_code: EXIT_BLOCK, json_output: json_output
+					)
 				end
 
 				# Check for unpushed commits.
@@ -66,39 +83,54 @@ module Carson
 					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
+						return worktree_finish(
+							result: { command: "worktree done", status: "block", name: name, branch: branch,
+								error: "worktree has unpushed commits",
+								recovery: "git -C #{resolved_path} push #{remote} #{branch}" },
+							exit_code: EXIT_BLOCK, json_output: json_output
+						)
 					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
+				worktree_finish(
+					result: { command: "worktree done", status: "ok", name: name, branch: branch || "(detached)",
+						next_step: "carson worktree remove #{name}" },
+					exit_code: EXIT_OK, json_output: json_output
+				)
 			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 )
+			def worktree_remove!( worktree_path:, force: false, json_output: false )
 				fingerprint_status = block_if_outsider_fingerprints!
-				return fingerprint_status unless fingerprint_status.nil?
+				unless fingerprint_status.nil?
+					if json_output
+						out.puts JSON.pretty_generate( {
+							command: "worktree remove", status: "block",
+							error: "Carson-owned artefacts detected in host repository",
+							recovery: "remove Carson-owned files (.carson.yml, bin/carson, .tools/carson) then retry",
+							exit_code: EXIT_BLOCK
+						} )
+					end
+					return fingerprint_status
+				end
 
 				resolved_path = resolve_worktree_path( worktree_path: worktree_path )
 
 				unless worktree_registered?( path: resolved_path )
-					puts_line "ERROR: #{resolved_path} is not a registered worktree."
-					puts_line "  Registered worktrees:"
-					worktree_list.each { |wt| puts_line "  - #{wt.fetch( :path )} [#{wt.fetch( :branch )}]" }
-					return EXIT_ERROR
+					return worktree_finish(
+						result: { command: "worktree remove", status: "error", name: File.basename( resolved_path ),
+							error: "#{resolved_path} is not a registered worktree",
+							recovery: "git worktree list" },
+						exit_code: EXIT_ERROR, json_output: json_output
+					)
 				end
 
 				branch = worktree_branch( path: resolved_path )
 				puts_verbose "worktree_remove: path=#{resolved_path} branch=#{branch} force=#{force}"
 
 				# Step 1: remove the worktree (directory + git registration).
-				# Try safe removal first. Only use --force if the user explicitly requested it.
 				rm_args = [ "worktree", "remove" ]
 				rm_args << "--force" if force
 				rm_args << resolved_path
@@ -107,40 +139,96 @@ module Carson
 					error_text = rm_stderr.to_s.strip
 					error_text = "unable to remove worktree" if error_text.empty?
 					if !force && ( error_text.downcase.include?( "untracked" ) || error_text.downcase.include?( "modified" ) )
-						puts_line "Worktree has uncommitted changes: #{File.basename( resolved_path )}"
-						puts_line "  Commit or discard changes first, or use --force to override."
-					else
-						puts_line "ERROR: #{error_text}"
+						return worktree_finish(
+							result: { command: "worktree remove", status: "error", name: File.basename( resolved_path ),
+								error: "worktree has uncommitted changes",
+								recovery: "commit or discard changes first, or use --force to override" },
+							exit_code: EXIT_ERROR, json_output: json_output
+						)
 					end
-					return EXIT_ERROR
+					return worktree_finish(
+						result: { command: "worktree remove", status: "error", name: File.basename( resolved_path ),
+							error: error_text },
+						exit_code: EXIT_ERROR, json_output: json_output
+					)
 				end
 				puts_verbose "worktree_removed: #{resolved_path}"
 
 				# Step 2: delete the local branch.
+				branch_deleted = false
 				if branch && !config.protected_branches.include?( branch )
 					_, del_stderr, del_success, = git_run( "branch", "-D", branch )
 					if del_success
 						puts_verbose "branch_deleted: #{branch}"
+						branch_deleted = true
 					else
 						puts_verbose "branch_delete_skipped: #{branch} reason=#{del_stderr.to_s.strip}"
 					end
 				end
 
 				# Step 3: delete the remote branch (best-effort).
+				remote_deleted = false
 				if branch && !config.protected_branches.include?( branch )
 					remote_branch = branch
-					git_run( "push", config.git_remote, "--delete", remote_branch )
-					puts_verbose "remote_branch_deleted: #{config.git_remote}/#{remote_branch}"
+					_, _, rd_success, = git_run( "push", config.git_remote, "--delete", remote_branch )
+					if rd_success
+						puts_verbose "remote_branch_deleted: #{config.git_remote}/#{remote_branch}"
+						remote_deleted = true
+					end
 				end
 
-				unless verbose?
-					puts_line "Worktree removed: #{File.basename( resolved_path )}"
-				end
-				EXIT_OK
+				worktree_finish(
+					result: { command: "worktree remove", status: "ok", name: File.basename( resolved_path ),
+						branch: branch, branch_deleted: branch_deleted, remote_deleted: remote_deleted },
+					exit_code: EXIT_OK, json_output: json_output
+				)
 			end
 
 		private
 
+			# Unified output for worktree results — JSON or human-readable.
+			def worktree_finish( result:, exit_code:, json_output: )
+				result[ :exit_code ] = exit_code
+
+				if json_output
+					out.puts JSON.pretty_generate( result )
+				else
+					print_worktree_human( result: result )
+				end
+
+				exit_code
+			end
+
+			# Human-readable output for worktree results.
+			def print_worktree_human( result: )
+				command = result[ :command ]
+				status = result[ :status ]
+
+				case status
+				when "ok"
+					case command
+					when "worktree create"
+						puts_line "Worktree created: #{result[ :name ]}"
+						puts_line "  Path: #{result[ :path ]}"
+						puts_line "  Branch: #{result[ :branch ]}"
+					when "worktree done"
+						puts_line "Worktree done: #{result[ :name ]}"
+						puts_line "  Branch: #{result[ :branch ]}"
+						puts_line "  Cleanup later with `#{result[ :next_step ]}` or `carson housekeep`."
+					when "worktree remove"
+						unless verbose?
+							puts_line "Worktree removed: #{result[ :name ]}"
+						end
+					end
+				when "error"
+					puts_line "ERROR: #{result[ :error ]}"
+					puts_line "  Recovery: #{result[ :recovery ]}" if result[ :recovery ]
+				when "block"
+					puts_line "#{result[ :error ]&.capitalize || 'Blocked'}: #{result[ :name ]}"
+					puts_line "  Recovery: #{result[ :recovery ]}" if result[ :recovery ]
+				end
+			end
+
 			# Resolves a worktree path: if it's a bare name, look under .claude/worktrees/.
 			def resolve_worktree_path( worktree_path: )
 				return File.expand_path( worktree_path ) if worktree_path.include?( "/" )

metadata

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