carson 2.33.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83e70e6824d3de6da2d444aa9d0b2859f3710e357f87cdcf65cecc512ff63fee
-  data.tar.gz: 6c09bd64199ab8ee6f7fa14722b670a123c7cb051ea2937c1e2bbfddb696fded
+  metadata.gz: 20f9db167969ae68e42a19efcc96c40108f4f3ab3f8b460369283457c9449e4b
+  data.tar.gz: 7e94bf5adcafdbd532bd6e789304e04c2a555b7adcbce441363e681a27493c25
 SHA512:
-  metadata.gz: 3a6570b397a73c27aab1d33e044bd28f56d1f643e57e76b40d3bbd5cdd1ff5da2779467980c9f595c6a25cbe2524cf5ff6508050a2736677ebb94079434eb749
-  data.tar.gz: 33d29172314ab043a5a38122b91fac3c150b3d846ef113cff953fefec5f56f8c35af1290a48ef951fe1154de4caf749cd779daf98c09c939518c0e64f7a72ecd
+  metadata.gz: 7bdc870e0ae003717b5e624d61386a41a89b5dcd20ec0e0c6fa5106b26791b53106bc43f763ca6199e79ca2bac8e76efcbff21d1ebbb126996550b009848f79f
+  data.tar.gz: 19dce95ec2fd4fc5a89de09f8e26b814e6b077285159d425639e68e635eda195d52171c7e388ce27efd27b685f7486e2fc6f8fcf0e7005407cdf672bb9c9f7a2

data/RELEASE.md

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

data/VERSION

@@ -1 +1 @@
-2.33.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
@@ -228,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,
@@ -266,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"

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.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