carson 2.33.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83e70e6824d3de6da2d444aa9d0b2859f3710e357f87cdcf65cecc512ff63fee
-  data.tar.gz: 6c09bd64199ab8ee6f7fa14722b670a123c7cb051ea2937c1e2bbfddb696fded
+  metadata.gz: 046c14a614687e668eae6d9f3df0eadbe02fcb103a1c93f25657791a0d72962c
+  data.tar.gz: 26ebca4203a0a9b3df1e38795580188bcf6951049304ae0eb4899deda35106f8
 SHA512:
-  metadata.gz: 3a6570b397a73c27aab1d33e044bd28f56d1f643e57e76b40d3bbd5cdd1ff5da2779467980c9f595c6a25cbe2524cf5ff6508050a2736677ebb94079434eb749
-  data.tar.gz: 33d29172314ab043a5a38122b91fac3c150b3d846ef113cff953fefec5f56f8c35af1290a48ef951fe1154de4caf749cd779daf98c09c939518c0e64f7a72ecd
+  metadata.gz: 38cb7ebf2e65293d5ea26bfb527314d86f7889949db033649fc49822b65feb7b7ea0e8fa5f35b6d959024ff4d280691432efde50dc15c37bf223665cd7d908b7
+  data.tar.gz: d05902ee1637919dd0a9781fa2de46e4370d2806df83c02c730584095f18811baea6168f3614d81900229dd5ec3c141ffb2ce6a40a8c338f233aa1a88a2a9b81

data/RELEASE.md

@@ -5,6 +5,46 @@ 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
+
+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

data/VERSION

@@ -1 +1 @@
-2.33.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 [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
 
@@ -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
@@ -168,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
@@ -183,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
@@ -228,6 +240,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,
@@ -266,6 +287,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,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 )

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.33.0
+  version: 3.1.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