carson 3.22.1 → 3.23.1

data/lib/carson/runtime/status.rb

@@ -1,10 +1,8 @@
-# Agent briefing — one command to know the full state of the estate.
-# Gathers branch, worktrees, open PRs, stale branches,
-# governance health, and version. Supports human-readable and JSON output.
+# Agent-readable repository status centred on branch deliveries.
 module Carson
 	class Runtime
 		module Status
-			# Entry point for `carson status`. Collects estate state and reports.
+			# Entry point for `carson status`.
 			def status!( json_output: false )
 				data = gather_status
 
@@ -19,115 +17,78 @@ module Carson
 
 			# Portfolio-wide status overview across all governed repositories.
 			def status_all!( json_output: false )
-				repos = config.govern_repos
-				if repos.empty?
+				repositories = config.govern_repos
+				if repositories.empty?
 					puts_line "No governed repositories configured."
 					puts_line "  Run carson onboard in each repo to register."
 					return EXIT_ERROR
 				end
 
-				if json_output
-					results = []
-					repos.each do |repo_path|
-						repo_name = File.basename( repo_path )
-						unless Dir.exist?( repo_path )
-							results << { name: repo_name, status: "error", error: "path not found" }
-							next
-						end
+				results = repositories.map do |repo_path|
+					repo_name = File.basename( repo_path )
+					unless Dir.exist?( repo_path )
+						{ name: repo_name, status: "error", error: "not found" }
+					else
 						begin
 							scoped_runtime = build_scoped_runtime( repo_path: repo_path )
-							data = scoped_runtime.send( :gather_status )
-							results << { name: repo_name, status: "ok" }.merge( data )
+							{ name: repo_name, status: "ok" }.merge( scoped_runtime.send( :gather_status ) )
 						rescue StandardError => exception
-							results << { name: repo_name, status: "error", error: exception.message }
+							{ name: repo_name, status: "error", error: exception.message }
 						end
 					end
-					output.puts JSON.pretty_generate( { command: "status", repos: results } )
-					return EXIT_OK
 				end
 
-				puts_line "Carson #{Carson::VERSION} — Portfolio (#{repos.length} repo#{plural_suffix( count: repos.length )})"
-				puts_line ""
-
-				all_pending = load_batch_pending
-				repos.each do |repo_path|
-					repo_name = File.basename( repo_path )
-					unless Dir.exist?( repo_path )
-						puts_line "#{repo_name}: not found"
-						next
-					end
-
-					begin
-						scoped_runtime = build_scoped_runtime( repo_path: repo_path )
-						data = scoped_runtime.send( :gather_status )
-						branch = data.fetch( :branch )
-						dirty = format_dirty_marker( branch: branch )
-						worktrees = data.fetch( :worktrees )
-						gov = data.fetch( :governance )
-						parts = []
-						parts << branch.fetch( :name ) + dirty
-						parts << "#{worktrees.count} worktree#{plural_suffix( count: worktrees.count )}" if worktrees.any?
-						parts << "templates #{gov.fetch( :templates )}" unless gov.fetch( :templates ) == :in_sync
-						puts_line "#{repo_name}: #{parts.join( '  ' )}"
-
-						# Show pending operations for this repo.
-						repo_pending = status_pending_for_repo( all_pending: all_pending, repo_path: repo_path )
-						repo_pending.each { |description| puts_line "  pending: #{description}" }
-					rescue StandardError => exception
-						puts_line "#{repo_name}: could not read (#{exception.message})"
-					end
+				if json_output
+					output.puts JSON.pretty_generate( { command: "status", repos: results, repositories: results } )
+				else
+					puts_line "Carson #{Carson::VERSION} — Portfolio (#{repositories.length} repo#{plural_suffix( count: repositories.length )})"
+					puts_line ""
+					results.each { |result| print_portfolio_status( result: result ) }
 				end
 
 				EXIT_OK
 			end
 
-		# rubocop:disable Layout/AccessModifierIndentation -- tab-width calculation produces unfixable mixed tabs+spaces
 		private
-		# rubocop:enable Layout/AccessModifierIndentation
 
-			# Returns an array of human-readable pending descriptions for a repo.
-			def status_pending_for_repo( all_pending:, repo_path: )
-				descriptions = []
-				all_pending.each do |command, repos|
-					next unless repos.is_a?( Hash ) && repos.key?( repo_path )
-
-					info = repos[ repo_path ]
-					attempts = info.fetch( "attempts", 0 )
-					skipped_at = info.fetch( "skipped_at", nil )
-					time_part = skipped_at ? ", since #{skipped_at[ 11..15 ]}" : ""
-					descriptions << "#{command} (#{attempts} attempt#{attempts == 1 ? '' : 's'}#{time_part})"
-				end
-				descriptions
-			end
-
-			# Collects all status facets into a structured hash.
 			def gather_status
-				data = {
+				repository = repository_record
+				branch = branch_record
+				deliveries = ledger.active_deliveries( repo_path: repo_root )
+
+				{
 					version: Carson::VERSION,
-					branch: gather_branch_info,
-					worktrees: gather_worktree_info,
-					governance: gather_governance_info
+					repository: {
+						name: repository.name,
+						path: repository.path,
+						authority: repository.authority
+					},
+					branch: {
+						name: branch.name,
+						head: branch.head,
+						worktree: branch.worktree,
+						dirty: working_tree_dirty?,
+						dirty_reason: dirty_worktree_reason,
+						sync: remote_sync_status( branch: branch.name )
+					},
+					branches: deliveries.map { |delivery| status_branch_entry( delivery: delivery ) },
+					stale_branches: gather_stale_branch_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_reason = dirty_worktree_reason
-				sync = remote_sync_status( branch: branch )
-
-				{ name: branch, dirty: !dirty_reason.nil?, dirty_reason: dirty_reason, sync: sync }
+			def status_branch_entry( delivery: )
+				{
+					branch: delivery.branch,
+					worktree_path: delivery.worktree_path,
+					head: delivery.head,
+					pr_number: delivery.pull_request_number,
+					delivery_state: delivery.status,
+					revision_count: delivery.revision_count,
+					summary: delivery.summary,
+					updated_at: delivery.updated_at
+				}
 			end
 
-			# Returns true when the working tree has uncommitted changes.
 			def working_tree_dirty?
 				stdout, _, success, = git_run( "status", "--porcelain" )
 				return true unless success
@@ -145,92 +106,22 @@ module Carson
 				realpath_safe( repo_root ) == realpath_safe( main_worktree_root )
 			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
-
+				ahead, behind = ahead_behind.strip.split.map( &:to_i )
 				return :in_sync if ahead.zero? && behind.zero?
 				return :ahead if behind.zero?
 				return :behind if ahead.zero?
 				:diverged
 			end
 
-			# Lists all worktrees with branch name.
-			def gather_worktree_info
-				entries = worktree_list
-
-				# Filter output the main worktree (the repository root itself).
-				# Use realpath for comparison — git returns canonical paths that may differ from repo_root.
-				canonical_root = realpath_safe( repo_root )
-				entries.reject { it.path == canonical_root }.map do |worktree|
-					{
-						path: worktree.path,
-						name: File.basename( worktree.path ),
-						branch: worktree.branch
-					}
-				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 { it[ "conclusion" ].to_s.upcase }
-				return :fail if states.any? { it == "FAILURE" || it == "CANCELLED" || it == "TIMED_OUT" }
-				return :pending if states.any? { it == "" || it == "PENDING" || it == "QUEUED" || it == "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
@@ -239,91 +130,61 @@ module Carson
 				{ 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 ""
+				puts_line "Repository: #{data.dig( :repository, :name )}"
+				puts_line "Authority: #{data.dig( :repository, :authority )}"
 
-				# Branch
 				branch = data.fetch( :branch )
-				dirty_marker = format_dirty_marker( branch: branch )
-				sync_marker = format_sync( sync: branch.fetch( :sync ) )
-				puts_line "Branch: #{branch.fetch( :name )}#{dirty_marker}#{sync_marker}"
-				if branch.fetch( :dirty_reason, nil ) == "main_worktree"
-					puts_line "Governance: main working tree has uncommitted changes — create a worktree with `carson worktree create <name>`."
+				branch_line = "Branch: #{branch.fetch( :name )}"
+				branch_line += " (dirty #{branch.fetch( :dirty_reason )})" if branch.fetch( :dirty )
+				branch_line += " [#{format_sync( sync: branch.fetch( :sync ) )}]"
+				puts_line branch_line
+
+				deliveries = data.fetch( :branches )
+				if deliveries.empty?
+					puts_line "Deliveries: none"
+					return
 				end
 
-				# Worktrees
-				worktrees = data.fetch( :worktrees )
-				if worktrees.any?
-					puts_line ""
-					puts_line "Worktrees:"
-					worktrees.each do |worktree|
-						branch_label = worktree.fetch( :branch ) || "(detached)"
-						puts_line "  #{worktree.fetch( :name )}  #{branch_label}"
-					end
+				puts_line "Deliveries:"
+				deliveries.each do |delivery|
+					line = "- #{delivery.fetch( :delivery_state )}: #{delivery.fetch( :branch )}"
+					pr_number = delivery.fetch( :pr_number )
+					line += " (#{"PR ##{pr_number}"} )" if pr_number
+					puts_line line.gsub( " )", ")" )
+					puts_line "  #{delivery.fetch( :summary )}" unless delivery.fetch( :summary ).to_s.empty?
 				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
+			def print_portfolio_status( result: )
+				if result.fetch( :status ) == "error"
+					puts_line "#{result.fetch( :name )}: #{result.fetch( :error )}"
+					return
 				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 #{ count == 1 ? 'branch' : 'branches' } 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."
+				deliveries = Array( result.fetch( :branches, [] ) )
+				counts = deliveries.each_with_object( Hash.new( 0 ) ) { |delivery, memo| memo[ delivery.fetch( :delivery_state ) ] += 1 }
+				summary = if counts.empty?
+					"no active deliveries"
+				else
+					counts.map { |state, count| "#{count} #{state}" }.join( ", " )
 				end
+				puts_line "#{result.fetch( :name )}: #{result.dig( :repository, :authority )} — #{summary}"
 			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 ""
+				when :in_sync then "in sync"
+				when :ahead then "ahead"
+				when :behind then "behind"
+				when :diverged then "diverged"
+				when :no_remote then "no remote"
+				else "unknown"
 				end
 			end
+		end
 
-			def format_dirty_marker( branch: )
-				return "" unless branch.fetch( :dirty )
-				return " (dirty main worktree)" if branch.fetch( :dirty_reason, nil ) == "main_worktree"
-
-				" (dirty)"
-			end
-			end
-
-			include Status
+		include Status
 	end
 end

data/lib/carson/runtime.rb

@@ -33,15 +33,22 @@ module Carson
 			@config = Config.load( repo_root: repo_root )
 			@git_adapter = Adapters::Git.new( repo_root: repo_root )
 			@github_adapter = Adapters::GitHub.new( repo_root: repo_root )
+			@ledger = Ledger.new( path: @config.govern_state_path )
 			@template_sync_result = nil
 		end
 
-		attr_reader :template_sync_result
+		attr_reader :template_sync_result, :ledger
 
 	private
 
 		attr_reader :repo_root, :tool_root, :output, :error, :in, :config, :git_adapter, :github_adapter
 
+		# Ruby 2.6 treats bare `in` awkwardly because of pattern-matching parsing.
+		# Keep the original ivar/reader for compatibility, but expose a safe helper name.
+		def input_stream
+			instance_variable_get( :@in )
+		end
+
 		# Returns true when full diagnostic output is enabled via --verbose.
 		def verbose?
 			@verbose
@@ -74,6 +81,21 @@ module Carson
 			git_capture!( "rev-parse", "--abbrev-ref", "HEAD" ).strip
 		end
 
+		# Current branch head SHA for delivery identity.
+		def current_head
+			git_capture!( "rev-parse", "HEAD" ).strip
+		end
+
+		# Passive repository record for the current runtime context.
+		def repository_record
+			Repository.new( path: repo_root, authority: config.govern_authority, runtime: self )
+		end
+
+		# Passive branch record for the current checkout.
+		def branch_record( name: current_branch )
+			repository_record.branch( name ).reload
+		end
+
 		# Checks local branch existence before restore attempts in ensure blocks.
 		def branch_exists?( branch_name: )
 			_, _, success, = git_run( "show-ref", "--verify", "--quiet", "refs/heads/#{branch_name}" )
@@ -355,6 +377,7 @@ module Carson
 	class Runtime
 		public :config, :output, :verbose?, :puts_verbose, :puts_line,
 			:git_run, :git_capture!, :main_worktree_root, :realpath_safe,
-			:block_if_outsider_fingerprints!, :branch_absorbed_into_main?
+			:block_if_outsider_fingerprints!, :branch_absorbed_into_main?,
+			:ledger, :current_head, :repository_record, :branch_record
 	end
 end

data/lib/carson/worktree.rb

@@ -52,13 +52,13 @@ module Carson
 		# Compares using realpath to handle symlink differences.
 		def self.find( path:, runtime: )
 			canonical = runtime.realpath_safe( path )
-			list( runtime: runtime ).find { it.path == canonical }
+			list( runtime: runtime ).find { |worktree| worktree.path == canonical }
 		end
 
 		# Returns true if the path is a registered git worktree.
 		def self.registered?( path:, runtime: )
 			canonical = runtime.realpath_safe( path )
-			list( runtime: runtime ).any? { it.path == canonical }
+			list( runtime: runtime ).any? { |worktree| worktree.path == canonical }
 		end
 
 		# Creates a new worktree under .claude/worktrees/<name> with a fresh branch.
@@ -247,10 +247,10 @@ module Carson
 			main_root = runtime.main_worktree_root
 			worktrees = list( runtime: runtime )
 
-			agent_prefixes = AGENT_DIRS.filter_map do |dir|
+			agent_prefixes = AGENT_DIRS.map do |dir|
 				full = File.join( main_root, dir, "worktrees" )
 				File.join( runtime.realpath_safe( full ), "" ) if Dir.exist?( full )
-			end
+			end.compact
 			return if agent_prefixes.empty?
 
 			worktrees.each do |worktree|
@@ -454,7 +454,7 @@ module Carson
 			return canonical if registered?( path: canonical, runtime: runtime )
 
 			# Bare name didn't match flat layout — search registered worktrees by dirname.
-			matches = list( runtime: runtime ).select { File.basename( it.path ) == path }
+			matches = list( runtime: runtime ).select { |worktree| File.basename( worktree.path ) == path }
 			return matches.first.path if matches.size == 1
 
 			# No match or ambiguous — return the flat candidate and let the caller

data/lib/carson.rb

@@ -5,6 +5,11 @@ module Carson
 	BADGE = "\u29D3".freeze # ⧓ BLACK BOWTIE (U+29D3)
 end
 
+require_relative "carson/repository"
+require_relative "carson/branch"
+require_relative "carson/delivery"
+require_relative "carson/revision"
+require_relative "carson/ledger"
 require_relative "carson/worktree"
 require_relative "carson/config"
 require_relative "carson/adapters/git"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 3.22.1
+  version: 3.23.1
 platform: ruby
 authors:
 - Hailei Wang
@@ -10,7 +10,27 @@ authors:
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
 description: 'Carson is an autonomous git strategist and repositories governor that
   lives outside the repositories it governs — no Carson-owned artefacts in your repo.
   As strategist, Carson knows when to branch, how to isolate concurrent work, and
@@ -48,8 +68,13 @@ files:
 - lib/carson/adapters/git.rb
 - lib/carson/adapters/github.rb
 - lib/carson/adapters/prompt.rb
+- lib/carson/branch.rb
 - lib/carson/cli.rb
 - lib/carson/config.rb
+- lib/carson/delivery.rb
+- lib/carson/ledger.rb
+- lib/carson/repository.rb
+- lib/carson/revision.rb
 - lib/carson/runtime.rb
 - lib/carson/runtime/audit.rb
 - lib/carson/runtime/deliver.rb