carson 2.32.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99666417783ceb949cdef39bbf1595465bf0a5f674607229b4b937a4ae8b6197
-  data.tar.gz: a8e55f943e2ab34a26d50b0468e10cecbdbf5879eaeef1a7323e99e80715dac3
+  metadata.gz: 20f9db167969ae68e42a19efcc96c40108f4f3ab3f8b460369283457c9449e4b
+  data.tar.gz: 7e94bf5adcafdbd532bd6e789304e04c2a555b7adcbce441363e681a27493c25
 SHA512:
-  metadata.gz: 2342dcf7bde01d3632741e76adaefe6c499a03a36d11bda476870419e43f87caa51ae9837fc5f1cdbbc9b5c083b4b2058824fc5c0f346788ca7f2658aecbe2ab
-  data.tar.gz: f0f8fe556fa65044b3789a45cd25d1fc354e2865a5b923843bf3249a30259bac989eb74f0cb5bb1ff2072c4dc548911ca5f5d26d13da933baceb70161a527993
+  metadata.gz: 7bdc870e0ae003717b5e624d61386a41a89b5dcd20ec0e0c6fa5106b26791b53106bc43f763ca6199e79ca2bac8e76efcbff21d1ebbb126996550b009848f79f
+  data.tar.gz: 19dce95ec2fd4fc5a89de09f8e26b814e6b077285159d425639e68e635eda195d52171c7e388ce27efd27b685f7486e2fc6f8fcf0e7005407cdf672bb9c9f7a2

data/RELEASE.md

@@ -5,6 +5,43 @@ 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.0.0 — Agent-Oriented Carson
+
+### Theme
+
+Carson is for coding agents. The primary consumer of Carson's commands, lifecycle management, and governance is the coding agent working on behalf of the developer. Carson 3.0 reorients the product around this truth.
+
+### What changed
+
+- **`carson status` — agent session briefing.** One command to know the full state of the estate: current branch and dirty/sync state, active worktrees, open PRs with CI and review status, stale branches ready for pruning, and governance health. Supports `--json` for machine-readable structured output — agents can parse the response directly instead of scraping human text.
+- **Deferred worktree cleanup model.** Worktrees are no longer expected to be deleted immediately after use. The new lifecycle: create a worktree, do work, mark it done, clean up later in batch via `carson housekeep` or `carson prune`. This eliminates the #1 agent session crash: worktree directory disappearing while the agent's shell CWD is inside it.
+- **`docs/agent-orient.md` — the agent's needs document.** Written from the coding agent's authentic perspective: what it experiences, what friction exists, and what it needs Carson to become. This document guides all 3.0 development.
+
+### UX
+
+- `carson status` prints a concise briefing by default. Silence is preserved — status reports only what needs attention.
+- `carson status --json` produces a stable JSON schema for programmatic consumption.
+
+### Migration
+
+- No breaking changes. All 2.x commands continue to work unchanged.
+- `docs/plan.md` has been removed — superseded by `docs/agent-orient.md`.
+
+## 2.33.0 — Safe Worktree Remove
+
+### What changed
+
+- **`carson worktree remove` no longer force-removes by default.** If the worktree has uncommitted or untracked changes, Carson refuses with a clear message instead of silently discarding work. Pass `--force` to override when you intentionally want to discard changes.
+- **Template sync cleanup is safer.** Carson's internal template propagation tries safe worktree removal first, falling back to `--force` only for its own ephemeral sync worktree.
+
+### UX
+
+- Dirty worktree removal now shows the worktree name and actionable guidance: "Commit or discard changes first, or use --force to override."
+
+### Migration
+
+- No action required. Existing `carson worktree remove` calls without `--force` will now refuse on dirty worktrees instead of silently destroying uncommitted work.
+
 ## 2.32.0 — Worktree-Aware Pruning
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-2.32.0
+3.0.0

data/lib/carson/cli.rb

@@ -53,7 +53,7 @@ module Carson
 
 		def self.build_parser
 			OptionParser.new do |opts|
-				opts.banner = "Usage: carson [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 [--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]"
 			end
 		end
 
@@ -88,6 +88,8 @@ module Carson
 				parse_worktree_subcommand( argv: argv, parser: parser, err: err )
 			when "review"
 				parse_named_subcommand( command: command, usage: "gate|sweep", argv: argv, parser: parser, err: err )
+			when "status"
+				parse_status_command( argv: argv, err: err )
 			when "govern"
 				parse_govern_subcommand( argv: argv, err: err )
 			else
@@ -175,12 +177,13 @@ module Carson
 
 			case action
 			when "remove"
+				force = argv.delete( "--force" ) ? true : false
 				worktree_path = argv.shift
 				if worktree_path.to_s.strip.empty?
 					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 }
+				{ command: "worktree:remove", worktree_path: worktree_path, force: force }
 			else
 				err.puts "#{BADGE} Unknown worktree subcommand: #{action}. Use: carson worktree remove <name-or-path>"
 				{ command: :invalid }
@@ -227,6 +230,15 @@ module Carson
 			{ command: :invalid }
 		end
 
+		def self.parse_status_command( argv:, err: )
+			json_flag = argv.delete( "--json" ) ? true : false
+			unless argv.empty?
+				err.puts "#{BADGE} Unexpected arguments for status: #{argv.join( ' ' )}"
+				return { command: :invalid }
+			end
+			{ command: "status", json: json_flag }
+		end
+
 		def self.parse_govern_subcommand( argv:, err: )
 			options = {
 				dry_run: false,
@@ -265,6 +277,8 @@ module Carson
 			return Runtime::EXIT_ERROR if command == :invalid
 
 			case command
+			when "status"
+				runtime.status!( json_output: parsed.fetch( :json, false ) )
 			when "setup"
 				runtime.setup!( cli_choices: parsed.fetch( :cli_choices, {} ) )
 			when "audit"
@@ -276,7 +290,7 @@ module Carson
 			when "prune:all"
 				runtime.prune_all!
 			when "worktree:remove"
-				runtime.worktree_remove!( worktree_path: parsed.fetch( :worktree_path ) )
+				runtime.worktree_remove!( worktree_path: parsed.fetch( :worktree_path ), force: parsed.fetch( :force, false ) )
 			when "onboard"
 				runtime.onboard!
 			when "refresh"

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

@@ -126,25 +126,19 @@ module Carson
 				text.empty? ? "unknown error" : text
 			end
 
-			# Attempts git branch -D. If blocked by a worktree, safely removes the worktree
-			# first (no --force — refuses if worktree has uncommitted changes) and retries.
+			# Attempts git branch -D. If blocked by a worktree, skips with a diagnostic —
+			# prune never removes worktrees because another session may own them.
 			def force_delete_local_branch( branch: )
 				stdout, stderr, success, = git_run( "branch", "-D", branch )
 				return [ stdout, stderr, success ] if success
-				return [ stdout, stderr, false ] unless worktree_blocked_error?( error_text: stderr )
 
-				wt_path = worktree_path_for_branch( branch: branch )
-				return [ stdout, stderr, false ] if wt_path.nil?
-
-				rm_stdout, rm_stderr, rm_success, = git_run( "worktree", "remove", wt_path )
-				unless rm_success
-					error_text = rm_stderr.to_s.strip
-					puts_verbose "skip_worktree_remove: #{wt_path} (branch=#{branch}) reason=#{error_text}"
-					return [ stdout, stderr, false ]
+				if worktree_blocked_error?( error_text: stderr )
+					wt_path = worktree_path_for_branch( branch: branch )
+					hint = wt_path ? "run: carson worktree remove #{File.basename( wt_path )}" : "remove the worktree first"
+					puts_verbose "skip_worktree_blocked: #{branch} (#{hint})"
 				end
-				puts_verbose "worktree_removed_for_prune: #{wt_path} (branch=#{branch})"
 
-				git_run( "branch", "-D", branch )
+				[ stdout, stderr, false ]
 			end
 
 			def worktree_blocked_error?( error_text: )

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

@@ -244,7 +244,9 @@ module Carson
 			end
 
 			def template_propagate_cleanup!( worktree_dir: )
-				git_run( "worktree", "remove", "--force", worktree_dir )
+				# Try safe removal first; fall back to force only for Carson's own sync worktree.
+				_, _, safe_success, = git_run( "worktree", "remove", worktree_dir )
+				git_run( "worktree", "remove", "--force", worktree_dir ) unless safe_success
 				git_run( "branch", "-D", TEMPLATE_SYNC_BRANCH )
 				puts_verbose "template_propagate: worktree and local branch cleaned up"
 			rescue StandardError => e

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

@@ -3,7 +3,9 @@ module Carson
 		module Local
 			# Safe worktree lifecycle management for coding agents.
 			# Enforces the teardown order: exit worktree → git worktree remove → branch cleanup.
-			def worktree_remove!( worktree_path: )
+			# 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 )
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
 
@@ -17,14 +19,23 @@ module Carson
 				end
 
 				branch = worktree_branch( path: resolved_path )
-				puts_verbose "worktree_remove: path=#{resolved_path} branch=#{branch}"
+				puts_verbose "worktree_remove: path=#{resolved_path} branch=#{branch} force=#{force}"
 
 				# Step 1: remove the worktree (directory + git registration).
-				rm_stdout, rm_stderr, rm_success, = git_run( "worktree", "remove", "--force", resolved_path )
+				# 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
+				rm_stdout, rm_stderr, rm_success, = git_run( *rm_args )
 				unless rm_success
 					error_text = rm_stderr.to_s.strip
 					error_text = "unable to remove worktree" if error_text.empty?
-					puts_line "ERROR: #{error_text}"
+					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}"
+					end
 					return EXIT_ERROR
 				end
 				puts_verbose "worktree_removed: #{resolved_path}"

data/lib/carson/runtime/status.rb

@@ -0,0 +1,229 @@
+# Agent session briefing — one command to know the full state of the estate.
+# Gathers branch, working tree, worktrees, open PRs, stale branches,
+# governance health, and version. Supports human-readable and JSON output.
+module Carson
+	class Runtime
+		module Status
+			# Entry point for `carson status`. Collects estate state and reports.
+			def status!( json_output: false )
+				data = gather_status
+
+				if json_output
+					out.puts JSON.pretty_generate( data )
+				else
+					print_status( data: data )
+				end
+
+				EXIT_OK
+			end
+
+		private
+
+			# Collects all status facets into a structured hash.
+			def gather_status
+				data = {
+					version: Carson::VERSION,
+					branch: gather_branch_info,
+					worktrees: gather_worktree_info,
+					governance: gather_governance_info
+				}
+
+				# PR and stale branch data require gh — gather with graceful fallback.
+				if gh_available?
+					data[ :pull_requests ] = gather_pr_info
+					data[ :stale_branches ] = gather_stale_branch_info
+				end
+
+				data
+			end
+
+			# Branch name, clean/dirty state, sync status with remote.
+			def gather_branch_info
+				branch = current_branch
+				dirty = working_tree_dirty?
+				sync = remote_sync_status( branch: branch )
+
+				{ name: branch, dirty: dirty, sync: sync }
+			end
+
+			# Returns true when the working tree has uncommitted changes.
+			def working_tree_dirty?
+				stdout, _, success, = git_run( "status", "--porcelain" )
+				return true unless success
+				!stdout.strip.empty?
+			end
+
+			# Compares local branch against its remote tracking ref.
+			# Returns :in_sync, :ahead, :behind, :diverged, or :no_remote.
+			def remote_sync_status( branch: )
+				remote = config.git_remote
+				remote_ref = "#{remote}/#{branch}"
+
+				# Check if the remote ref exists.
+				_, _, exists, = git_run( "rev-parse", "--verify", remote_ref )
+				return :no_remote unless exists
+
+				ahead_behind, _, success, = git_run( "rev-list", "--left-right", "--count", "#{branch}...#{remote_ref}" )
+				return :unknown unless success
+
+				parts = ahead_behind.strip.split( /\s+/ )
+				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
+			end
+
+			# Lists all worktrees with branch and lifecycle state.
+			def gather_worktree_info
+				entries = worktree_list
+				# Filter out the main worktree (the repository root itself).
+				entries.reject { |wt| wt.fetch( :path ) == repo_root }.map do |wt|
+					{
+						path: wt.fetch( :path ),
+						name: File.basename( wt.fetch( :path ) ),
+						branch: wt.fetch( :branch, nil )
+					}
+				end
+			end
+
+			# Queries open PRs via gh.
+			def gather_pr_info
+				stdout, _, success, = gh_run(
+					"pr", "list", "--state", "open",
+					"--json", "number,title,headRefName,statusCheckRollup,reviewDecision"
+				)
+				return [] unless success
+
+				prs = JSON.parse( stdout ) rescue []
+				prs.map do |pr|
+					ci = summarise_checks( rollup: pr[ "statusCheckRollup" ] )
+					review = pr[ "reviewDecision" ].to_s
+					review_label = review_decision_label( decision: review )
+
+					{
+						number: pr[ "number" ],
+						title: pr[ "title" ],
+						branch: pr[ "headRefName" ],
+						ci: ci,
+						review: review_label
+					}
+				end
+			end
+
+			# Summarises check rollup into a single status word.
+			def summarise_checks( rollup: )
+				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" }
+
+				:pass
+			end
+
+			# Translates GitHub review decision to a concise label.
+			def review_decision_label( decision: )
+				case decision.upcase
+				when "APPROVED" then :approved
+				when "CHANGES_REQUESTED" then :changes_requested
+				when "REVIEW_REQUIRED" then :review_required
+				else :none
+				end
+			end
+
+			# Counts local branches that are stale (tracking a deleted upstream).
+			def gather_stale_branch_info
+				stdout, _, success, = git_run( "branch", "-vv" )
+				return { count: 0 } unless success
+
+				gone_branches = stdout.lines.select { |l| l.include?( ": gone]" ) }
+				{ count: gone_branches.size }
+			end
+
+			# Quick governance health check: are templates in sync?
+			def gather_governance_info
+				result = with_captured_output { template_check! }
+				{
+					templates: result == EXIT_OK ? :in_sync : :drifted
+				}
+			rescue StandardError
+				{ templates: :unknown }
+			end
+
+			# Prints the human-readable status report.
+			def print_status( data: )
+				puts_line "Carson #{data.fetch( :version )}"
+				puts_line ""
+
+				# Branch
+				branch = data.fetch( :branch )
+				dirty_marker = branch.fetch( :dirty ) ? " (dirty)" : ""
+				sync_marker = format_sync( sync: branch.fetch( :sync ) )
+				puts_line "Branch: #{branch.fetch( :name )}#{dirty_marker}#{sync_marker}"
+
+				# Worktrees
+				worktrees = data.fetch( :worktrees )
+				if worktrees.any?
+					puts_line ""
+					puts_line "Worktrees:"
+					worktrees.each do |wt|
+						branch_label = wt.fetch( :branch ) || "(detached)"
+						puts_line "  #{wt.fetch( :name )}  #{branch_label}"
+					end
+				end
+
+				# Pull requests
+				prs = data.fetch( :pull_requests, nil )
+				if prs && prs.any?
+					puts_line ""
+					puts_line "Pull requests:"
+					prs.each do |pr|
+						ci_label = pr.fetch( :ci ).to_s
+						review_label = pr.fetch( :review ).to_s.tr( "_", " " )
+						puts_line "  ##{pr.fetch( :number )}  #{pr.fetch( :title )}"
+						puts_line "        CI: #{ci_label}  Review: #{review_label}"
+					end
+				end
+
+				# Stale branches
+				stale = data.fetch( :stale_branches, nil )
+				if stale && stale.fetch( :count ) > 0
+					count = stale.fetch( :count )
+					puts_line ""
+					puts_line "#{count} stale branch#{plural_suffix( count: count )} ready for pruning."
+				end
+
+				# Governance
+				gov = data.fetch( :governance )
+				templates = gov.fetch( :templates )
+				unless templates == :in_sync
+					puts_line ""
+					puts_line "Templates: #{templates} — run `carson sync` to fix."
+				end
+			end
+
+			# Formats sync status for display.
+			def format_sync( sync: )
+				case sync
+				when :in_sync then ""
+				when :ahead then " (ahead of remote)"
+				when :behind then " (behind remote)"
+				when :diverged then " (diverged from remote)"
+				when :no_remote then " (no remote tracking)"
+				else ""
+				end
+			end
+		end
+
+		include Status
+	end
+end

data/lib/carson/runtime.rb

@@ -220,3 +220,4 @@ require_relative "runtime/audit"
 require_relative "runtime/review"
 require_relative "runtime/govern"
 require_relative "runtime/setup"
+require_relative "runtime/status"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 2.32.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Hailei Wang
@@ -67,6 +67,7 @@ files:
 - lib/carson/runtime/review/sweep_support.rb
 - lib/carson/runtime/review/utility.rb
 - lib/carson/runtime/setup.rb
+- lib/carson/runtime/status.rb
 - lib/carson/version.rb
 - templates/.github/AGENTS.md
 - templates/.github/CLAUDE.md