carson 3.23.2 → 3.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b22f115d99fffc1ed689ceb214523b8a33da08fc84a955fcc766d778be21e40c
-  data.tar.gz: 6a270c175cb8affabba0d6d747e08701a50c61124a4c5486525113ff350cedbf
+  metadata.gz: 92803422cb09be4d2f4b31cf6c0b0f98796373c2a6a403af55c0e09361d0e951
+  data.tar.gz: 36f06f845aca0878e2d18de009e661c662baf08675ce3b3331e08f4f2907cc58
 SHA512:
-  metadata.gz: 00ac0ad1897f1d04520f4653aec941e6d9c0dfeb7d13656a4ecb1eff6a3cffe24af0b839447f1324ac11c6eb6c40e00b01e1cba6c3fa86a5d21871576b4bb2d2
-  data.tar.gz: fad5645c4a8befb085b4617db5542117bf593f1475cc5a65ccbf29b207e4c5ea9fd938bb503d2fa35e66b652ecc01fae269d68c5c60f2e895055cd8c3b0190b3
+  metadata.gz: 356bdf1b684829c5d506d00d303db0473f1cacdfd70d7831c21db201d465dd51fd3c03aa7a63f1cebc5658f6fe98321d6cc2bbc99c6f049753325f8898bb7479
+  data.tar.gz: ecad319106eb238264d3155740c36960521a70448183946c1ed1646d8b1b5291345d7eef8c0463a68e5cc55b0efe5d7687574d1ac2d869eeaaac08b73bafed81

data/API.md

@@ -25,7 +25,7 @@ carson <command> [subcommand] [arguments]
 | Command | Purpose |
 |---|---|
 | `carson audit` | Evaluate governance status and generate report output. |
-| `carson deliver` | Start autonomous branch delivery for the current checkout: push, create or refresh PR, record delivery state, and return immediately. |
+| `carson deliver [--commit MESSAGE]` | Start autonomous branch delivery for the current checkout. Plain `deliver` transports existing commits only; `--commit` creates one all-dirty delivery commit first, then pushes, creates or refreshes the PR, records delivery state, and returns immediately. |
 | `carson sync` | Fast-forward local `main` from configured remote when tree is clean. |
 | `carson prune` | Remove stale local branches whose upstream refs no longer exist. |
 | `carson template check` | Detect drift between managed templates and host `.github/*` files. |

data/MANUAL.md

@@ -152,12 +152,14 @@ carson worktree create my-feature
 cd /path/to/.claude/worktrees/my-feature
 ```
 
-**2. Work** — make changes, commit, iterate.
+**2. Work** — make changes, test them, and either commit normally or let Carson create the delivery commit.
 
-**3. Hand the branch to Carson** — `deliver` is the asynchronous branch handoff. In remote authority Carson pushes the branch, creates or refreshes the PR, records delivery state, and returns immediately. Managed template drift is corrected and committed automatically before push (3.23.0+).
+**3. Hand the branch to Carson** — `deliver` is the asynchronous branch handoff. In remote authority Carson pushes the branch, creates or refreshes the PR, records delivery state, and returns immediately. Plain `carson deliver` transports existing commits and blocks if the worktree is dirty. `carson deliver --commit "..."` creates one all-dirty agent-authored commit first, then continues the same delivery flow. Managed template drift is still corrected in a separate Carson-managed commit before push.
 
 ```bash
 carson deliver
+# or, if the worktree is still dirty:
+carson deliver --commit "fix: describe this delivery"
 # Output: PR #N, Delivery: queued|gated
 #   Next: carson status
 ```

data/README.md

@@ -60,15 +60,15 @@ carson onboard your/repo/path
 carson worktree create your-worktree
 cd your/repo/path/.claude/worktrees/your-worktree
 
-# work, test, commit
-carson deliver
+# work and test, then either commit yourself or let Carson create the delivery commit
+carson deliver --commit "fix: describe this delivery"
 carson status
 
 # keep govern running to advance queued deliveries
 carson govern --loop 300
 ```
 
-By default, repositories onboard as `remote`. `carson deliver` is the branch handoff: it pushes the branch, creates or refreshes the PR, records delivery state, and returns immediately. `carson status` shows the active branch deliveries, and `carson govern` advances queued work across the governed portfolio.
+By default, repositories onboard as `remote`. `carson deliver` is the branch handoff: it pushes the branch, creates or refreshes the PR, records delivery state, and returns immediately. Use plain `carson deliver` when the branch is already committed. Use `carson deliver --commit "..."` when the worktree is dirty and Carson should create one all-dirty delivery commit first. `carson status` shows the active branch deliveries, and `carson govern` advances queued work across the governed portfolio.
 
 ## Portfolio Layer
 

data/RELEASE.md

@@ -5,6 +5,23 @@ 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.24.0
+
+### What changed
+
+- **Govern now finds worktree-created deliveries** — `repository_record` stored the worktree CWD as `repo_path` in the ledger, but `govern` looked up deliveries by the main tree path from config. The SQL query never matched, so `carson govern` always reported "no active deliveries" for worktree-created PRs. Now `repository_record` uses `main_worktree_root` so the ledger key is always the canonical main tree path. Also fixed the govern fallback path, `reconcile_delivery!`, `housekeep_repo!`, and `review_evidence` for the same mismatch.
+- **Status shows canonical repository name** — `carson status` from a worktree displayed the worktree folder name (e.g. `feature-branch`) as `Repository:` instead of the actual repository name. Now correctly shows the canonical name.
+
+### No migration required
+
+## 3.23.3
+
+### What changed
+
+- **Fix: review gate failed with "accepts at most 1 arg(s), received 3"** — `current_pull_request_for_branch` placed `--json` after the `--` end-of-options separator, causing `gh pr view` to treat it as a positional argument instead of a flag. Flags now precede `--`.
+
+### No migration required
+
 ## 3.23.2
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-3.23.2
+3.24.0

data/lib/carson/cli.rb

@@ -550,22 +550,29 @@ module Carson
 				return { command: :invalid }
 			end
 
-			options = { json: false, title: nil, body_file: nil }
+			options = { json: false, title: nil, body_file: nil, commit_message: nil }
 			deliver_parser = OptionParser.new do |parser|
-				parser.banner = "Usage: carson deliver [--json] [--title TITLE] [--body-file PATH]"
+				parser.banner = "Usage: carson deliver [--json] [--title TITLE] [--body-file PATH] [--commit MESSAGE]"
 				parser.separator ""
 				parser.separator "Push the current branch, create or refresh the pull request, and hand the branch to Carson."
-				parser.separator "Carson records delivery state and continues from there."
+				parser.separator "Use --commit to create one all-dirty delivery commit before Carson pushes and opens the PR."
 				parser.separator ""
 				parser.separator "Options:"
 				parser.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
 				parser.on( "--title TITLE", "PR title (defaults to branch name)" ) { |value| options[ :title ] = value }
 				parser.on( "--body-file PATH", "File containing PR body text" ) { |value| options[ :body_file ] = value }
+				parser.on( "--commit MESSAGE", "Commit all dirty user changes before delivery" ) { |value| options[ :commit_message ] = value }
 				parser.separator ""
 				parser.separator "Examples:"
-				parser.separator "    carson deliver               Push, open a PR, and register delivery state"
+				parser.separator "    carson deliver                               Deliver existing commits"
+				parser.separator "    carson deliver --commit \"fix: harden flow\"   Commit dirty changes, then deliver"
 			end
 			deliver_parser.parse!( arguments )
+			if options.fetch( :commit_message, nil ).to_s.strip.empty? && !options.fetch( :commit_message, nil ).nil?
+				error.puts "#{BADGE} --commit requires a non-empty message"
+				error.puts deliver_parser
+				return { command: :invalid }
+			end
 			unless arguments.empty?
 				error.puts "#{BADGE} Unexpected arguments for deliver: #{arguments.join( ' ' )}"
 				error.puts deliver_parser
@@ -575,7 +582,8 @@ module Carson
 				command: "deliver",
 				json: options.fetch( :json ),
 				title: options[ :title ],
-				body_file: options[ :body_file ]
+				body_file: options[ :body_file ],
+				commit_message: options[ :commit_message ]
 			}
 		rescue OptionParser::ParseError => exception
 			error.puts "#{BADGE} #{exception.message}"
@@ -763,6 +771,7 @@ module Carson
 				runtime.deliver!(
 					title: parsed.fetch( :title, nil ),
 					body_file: parsed.fetch( :body_file, nil ),
+					commit_message: parsed.fetch( :commit_message, nil ),
 					json_output: parsed.fetch( :json, false )
 				)
 			when "review:gate"

data/lib/carson/runtime/deliver.rb

@@ -5,7 +5,8 @@ module Carson
 		module Deliver
 			# Entry point for `carson deliver`.
 			# Pushes the current branch, ensures a PR exists, records delivery state, and returns.
-			def deliver!( title: nil, body_file: nil, json_output: false )
+			# When --commit is supplied, Carson creates one all-dirty agent-authored commit first.
+			def deliver!( title: nil, body_file: nil, commit_message: nil, json_output: false )
 				branch_name = current_branch
 				main_branch = config.main_branch
 				remote_name = config.git_remote
@@ -17,11 +18,38 @@ module Carson
 					return deliver_finish( result: result, exit_code: EXIT_BLOCK, json_output: json_output )
 				end
 
+				initial_dirty = working_tree_dirty?
+				if initial_dirty && commit_message.to_s.strip.empty?
+					result[ :error ] = "working tree is dirty"
+					result[ :recovery ] = "carson deliver --commit \"describe this delivery\""
+					return deliver_finish( result: result, exit_code: EXIT_BLOCK, json_output: json_output )
+				end
+
+				if !initial_dirty && !commit_message.to_s.strip.empty?
+					result[ :commit ] = blocked_commit_payload(
+						message: commit_message,
+						summary: "blocked — working tree is already clean"
+					)
+					result[ :error ] = "working tree is already clean"
+					result[ :recovery ] = "carson deliver"
+					return deliver_finish( result: result, exit_code: EXIT_BLOCK, json_output: json_output )
+				end
+
 				sync_exit, sync_diagnostics = deliver_template_sync
 				if sync_exit == EXIT_ERROR
 					result[ :error ] = sync_diagnostics.to_s.strip.empty? ? "template sync failed" : sync_diagnostics.strip
 					return deliver_finish( result: result, exit_code: sync_exit, json_output: json_output )
 				end
+				template_sync_committed = sync_exit == EXIT_BLOCK
+
+				unless commit_message.to_s.strip.empty?
+					commit_exit = prepare_delivery_commit!(
+						commit_message: commit_message,
+						template_sync_committed: template_sync_committed,
+						result: result
+					)
+					return deliver_finish( result: result, exit_code: commit_exit, json_output: json_output ) unless commit_exit == EXIT_OK
+				end
 
 				push_exit = push_branch!( branch: branch_name, remote: remote_name, result: result )
 				return deliver_finish( result: result, exit_code: push_exit, json_output: json_output ) unless push_exit == EXIT_OK
@@ -61,6 +89,93 @@ module Carson
 
 		private
 
+			def prepare_delivery_commit!( commit_message:, template_sync_committed:, result: )
+				if working_tree_dirty?
+					return create_delivery_commit!( commit_message: commit_message, result: result )
+				end
+
+				if template_sync_committed
+					result[ :commit ] = skipped_commit_payload(
+						message: commit_message,
+						summary: "skipped — template sync committed all pending changes"
+					)
+					return EXIT_OK
+				end
+
+				# The caller blocks the ordinary clean-tree case before template sync.
+				# Keep this branch as a post-sync safety net so future sequencing changes
+				# do not silently turn a clean tree into a successful no-op commit request.
+				result[ :commit ] = blocked_commit_payload(
+					message: commit_message,
+					summary: "blocked — working tree is already clean"
+				)
+				result[ :error ] = "working tree is already clean"
+				result[ :recovery ] = "carson deliver"
+				EXIT_BLOCK
+			end
+
+			def create_delivery_commit!( commit_message:, result: )
+				_, add_stderr, add_success, = git_run( "add", "-A" )
+				unless add_success
+					error_text = add_stderr.to_s.strip
+					error_text = "git add failed" if error_text.empty?
+					result[ :commit ] = blocked_commit_payload(
+						message: commit_message,
+						summary: "blocked — #{error_text}"
+					)
+					result[ :error ] = error_text
+					result[ :recovery ] = "git status"
+					return EXIT_ERROR
+				end
+
+				commit_stdout, commit_stderr, commit_success, = git_run( "commit", "-m", commit_message )
+				unless commit_success
+					error_text = [ commit_stderr.to_s.strip, commit_stdout.to_s.strip ].reject( &:empty? ).join( " | " )
+					error_text = "git commit failed" if error_text.empty?
+					result[ :commit ] = blocked_commit_payload(
+						message: commit_message,
+						summary: "blocked — #{error_text}"
+					)
+					result[ :error ] = error_text
+					result[ :recovery ] = "git status"
+					return EXIT_ERROR
+				end
+
+				result[ :commit ] = created_commit_payload(
+					message: commit_message,
+					head: current_head,
+					summary: "created agent-authored commit"
+				)
+				EXIT_OK
+			end
+
+			def created_commit_payload( message:, head:, summary: )
+				{
+					status: "created",
+					message: message,
+					head: head,
+					summary: summary
+				}
+			end
+
+			def skipped_commit_payload( message:, summary: )
+				{
+					status: "skipped",
+					message: message,
+					head: nil,
+					summary: summary
+				}
+			end
+
+			def blocked_commit_payload( message:, summary: )
+				{
+					status: "blocked",
+					message: message,
+					head: nil,
+					summary: summary
+				}
+			end
+
 			def deliver_template_sync
 				saved_output, saved_error = @output, @error
 				captured_out = StringIO.new
@@ -135,6 +250,9 @@ module Carson
 					return
 				end
 
+				if result[ :commit ]
+					puts_line "Commit: #{result.dig( :commit, :summary )}"
+				end
 				puts_line "PR: ##{result[ :pr_number ]} #{result[ :pr_url ]}" if result[ :pr_number ]
 				if result[ :delivery ]
 					puts_line "Delivery: #{result.dig( :delivery, :status )}"

data/lib/carson/runtime/govern.rb

@@ -18,7 +18,7 @@ module Carson
 			def govern_cycle!( dry_run:, json_output: )
 				print_header "Carson Govern"
 				repositories = governed_repo_paths
-				repositories = [ repo_root ] if repositories.empty?
+				repositories = [ repository_record.path ] if repositories.empty?
 				puts_line "governing #{repositories.length} repo#{plural_suffix( count: repositories.length )}"
 
 				report = {
@@ -64,7 +64,7 @@ module Carson
 			end
 
 			def govern_repo!( repo_path:, dry_run: )
-				scoped_runtime = repo_path == repo_root ? self : build_scoped_runtime( repo_path: repo_path )
+				scoped_runtime = repo_runtime_for( repo_path: repo_path )
 				repository = Repository.new( path: repo_path, authority: scoped_runtime.config.govern_authority, runtime: scoped_runtime )
 				deliveries = scoped_runtime.ledger.active_deliveries( repo_path: repo_path )
 
@@ -108,7 +108,7 @@ module Carson
 			end
 
 			def reconcile_delivery!( delivery: )
-				branch = Repository.new( path: repo_root, authority: config.govern_authority, runtime: self ).branch( delivery.branch ).reload
+				branch = repository_record.branch( delivery.branch ).reload
 				if branch.head && branch.head != delivery.head
 					return ledger.update_delivery(
 						delivery: delivery,
@@ -288,7 +288,7 @@ module Carson
 			end
 
 			def housekeep_repo!( repo_path: )
-				scoped_runtime = repo_path == repo_root ? self : build_scoped_runtime( repo_path: repo_path )
+				scoped_runtime = repo_runtime_for( repo_path: repo_path )
 				sync_status = scoped_runtime.sync!
 				scoped_runtime.prune! if sync_status == EXIT_OK
 			end
@@ -373,7 +373,7 @@ module Carson
 			end
 
 			def review_evidence( delivery:, repo_path: )
-				repo_runtime = repo_path == repo_root ? self : build_scoped_runtime( repo_path: repo_path )
+				repo_runtime = repo_runtime_for( repo_path: repo_path )
 				owner, repo = repo_runtime.send( :repository_coordinates )
 				details = repo_runtime.send( :pull_request_details, owner: owner, repo: repo, pr_number: delivery.pull_request_number )
 				pr_author = details.dig( :author, :login ).to_s
@@ -399,6 +399,10 @@ module Carson
 				{ summary: revision.summary.to_s, dispatched_at: revision.started_at.to_s }
 			end
 
+			def repo_runtime_for( repo_path: )
+				realpath_safe( repo_path ) == realpath_safe( repo_root ) ? self : build_scoped_runtime( repo_path: repo_path )
+			end
+
 			def thread_body( details:, url: )
 				Array( details[ :review_threads ] ).each do |thread|
 					thread[ :comments ].each do |comment|

data/lib/carson/runtime/review/gate_support.rb

@@ -121,7 +121,7 @@ module Carson
 
 				# Pull request selected by current branch; nil is returned when no PR exists.
 				def current_pull_request_for_branch( branch_name: )
-					stdout_text, stderr_text, success, = gh_run( "pr", "view", "--", branch_name, "--json", "number,title,url,state" )
+					stdout_text, stderr_text, success, = gh_run( "pr", "view", "--json", "number,title,url,state", "--", branch_name )
 					unless success
 						error_text = gh_error_text( stdout_text: stdout_text, stderr_text: stderr_text, fallback: "unable to read PR for branch #{branch_name}" )
 						return nil if error_text.downcase.include?( "no pull requests found" )

data/lib/carson/runtime/status.rb

@@ -54,7 +54,7 @@ module Carson
 			def gather_status
 				repository = repository_record
 				branch = branch_record
-				deliveries = ledger.active_deliveries( repo_path: repo_root )
+				deliveries = ledger.active_deliveries( repo_path: repository.path )
 
 				{
 					version: Carson::VERSION,

data/lib/carson/runtime.rb

@@ -87,8 +87,11 @@ module Carson
 		end
 
 		# Passive repository record for the current runtime context.
+		# Uses main_worktree_root so the repo_path stored in the ledger is always the
+		# canonical main tree path, regardless of which worktree the command runs from.
+		# This ensures govern (which looks up by main tree path) finds worktree deliveries.
 		def repository_record
-			Repository.new( path: repo_root, authority: config.govern_authority, runtime: self )
+			Repository.new( path: main_worktree_root, authority: config.govern_authority, runtime: self )
 		end
 
 		# Passive branch record for the current checkout.

metadata

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