carson 4.2.1 → 4.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 251588ff2b1c952538965ea349b498e424c9646f6c57965dd516e7729e002035
-  data.tar.gz: 2fee9945faa9fbace57ef59dfd77cf5fb9c38992f4e573e796daeef8b1972017
+  metadata.gz: 5d25d50d20c3cc3244b3ab246ca7f5b661e097146993fee1cc5b8dd66f978938
+  data.tar.gz: 1d2f6a26fc79dc62688c409557f2b74328f593f2e582af17c4a6fa020bb1b75b
 SHA512:
-  metadata.gz: 3981e6facd927beb517b18151eb0d4804863e6adab4d4d39039e6e9313e644f57caae09e0b292e1e33d49b383e1f3f7975decfe3d0672dc372f3582b757bc513
-  data.tar.gz: 55175ac0b094290e602d79854e65208fb5f1baa23753ed05c786c48ddda562b2015de76fb7244dc90c12a2495b2d84269e40c3f9521077d646776eeab843c760
+  metadata.gz: 234de9b2d4bad297af4b7bf24bd396629690bde5925fa743d9438316dcbb146f88e444b0aed61a72c022de32e34ba09aeedfb078afc4711973437eb5a38e6279
+  data.tar.gz: 2d3438c23a8146367289413e28d756eee5cb303c58c5820273f471482a83f351d0fc379a3db01a6edbbcdd5f13afbce508b8f999344d0e295dfb6fd74c816f88

data/RELEASE.md

@@ -7,6 +7,29 @@ Release-note scope rule:
 
 ## Unreleased
 
+## 4.3.0
+
+### New
+
+- **Local-centred workstyle** — Carson now supports two workstyles. Local-centred (the new default) merges parcels directly into the local vault (main) and pushes to the remote as backup. No PR, no CI gate, no waiting. Remote-centred remains available for projects that need Bureau oversight. Set `workstyle: remote` in `.carson.yml` to use the old behaviour.
+- **`Warehouse::Vault` concern** — the vault is local main, where accepted parcels live. `warehouse.accept!( parcel )` merges a branch into main via fast-forward. If the branch has diverged, the agent must rebase first.
+- **`warehouse.prepare!( parcel, message: )`** — the delivery prep phase: pack, fetch latest standard, check freshness, auto-rebase if behind. No compliance gate in local workstyle — agents handle linting and testing themselves.
+
+### Changed
+
+- **Courier is workstyle-aware** — `courier.deliver( parcel )` uses different gestures per workstyle. Local: push main to backup vault. Remote: the existing Bureau trip (unchanged). One verb, two gestures. The Courier doesn't know if it's doing "backup" or "primary" — it just delivers.
+- **CLI orchestrates local delivery** — `carson deliver` in local workstyle follows the checkin/checkout pattern: CLI builds Warehouse + Courier, orchestrates `prepare!` → `accept!` → `courier.deliver`. No Runtime in the local path.
+
+### UX
+
+- `carson deliver` output (local workstyle): `⧓ <branch> merged into main.` / `⧓ Pushed to remote.`
+- On failure: clear recovery instructions (`Rebase onto main and deliver again.`)
+- On backup failure: `⧓ Backup failed.` with recovery.
+
+### Why
+
+The 2026-03-24 retrospective clarified that for a solo developer with agents, the remote-centred machinery (PR → CI → Bureau polling → merge) added latency, cost, and complexity without serving a need. The vault (local main) is the source of truth. GitHub is the backup vault. The Courier's job is simpler and faster.
+
 ## 4.2.1
 
 ### Fixed

data/VERSION

@@ -1 +1 @@
-4.2.1
+4.3.0

data/lib/carson/config.rb

@@ -33,7 +33,8 @@ module Carson
 			:govern_repos, :govern_merge_method,
 			:govern_agent_provider, :govern_state_path,
 			:govern_check_wait,
-			:poll_interval_at_bureau
+			:poll_interval_at_bureau,
+			:workstyle
 
 		def self.load( repo_root: )
 			base_data = default_data
@@ -85,6 +86,7 @@ module Carson
 				"deliver" => {
 				"poll_interval_at_bureau" => 30
 			},
+			"workstyle" => "local",
 			"govern" => {
 					"repos" => [],
 					"merge" => {
@@ -247,6 +249,9 @@ module Carson
 			deliver_hash = fetch_hash( hash: data, key: "deliver" )
 			@poll_interval_at_bureau = fetch_non_negative_integer( hash: deliver_hash, key: "poll_interval_at_bureau" )
 
+			workstyle_raw = data.fetch( "workstyle", "local" ).to_s.downcase
+			@workstyle = [ "local", "remote" ].include?( workstyle_raw ) ? workstyle_raw.to_sym : :local
+
 			govern_hash = fetch_hash( hash: data, key: "govern" )
 			@govern_repos = fetch_optional_string_array( hash: govern_hash, key: "repos" ).map { |path| safe_expand_path( path ) }
 			govern_merge_hash = fetch_hash( hash: govern_hash, key: "merge" )

data/lib/carson/courier.rb

@@ -1,6 +1,8 @@
 # Carson Co.
+require "open3"
+
 module Carson
-	# The delivery person — picks up parcels and delivers them to the bureau.
+	# The delivery worker — waits at the gate, picks up parcels, delivers them.
 	#
 	# The courier is a Carson employee assigned to a warehouse. They pick up
 	# a parcel, ask the warehouse to ship it, file a waybill, and wait at
@@ -59,11 +61,14 @@ module Carson
 	# answer, the courier reports "filed" — the parcel is still at the bureau
 	# and the shelf stays sealed.
 	#
-	# == Future: destination modes
+	# == Workstyle
+	#
+	# The courier's gesture depends on the workstyle:
+	# - :local — push main to backup vault (simple, no PR, no waiting)
+	# - :remote — ship → waybill → bureau → acceptance (complex Bureau trip)
 	#
-	# Currently remote-centred (ship → waybill → bureau → acceptance).
-	# A future local-centred mode merges locally; remote is a synced backup.
-	# The destination mode should be injectable, not baked in.
+	# The courier doesn't know whether it's doing "backup" or "primary" —
+	# it just delivers to wherever the workstyle dictates.
 	class Courier
 		# Exit codes — shared contract between Carson employees and the CLI.
 		OK = 0
@@ -75,17 +80,21 @@ module Carson
 		# The courier checks the bureau up to 6 times before leaving.
 		MAX_CHECKS_AT_BUREAU = 6
 
-		def initialize( warehouse, ledger: nil, merge_method: "rebase", poll_interval_at_bureau: 30, output: $stdout )
+		def initialize( warehouse, workstyle: :local, ledger: nil, merge_method: "rebase", poll_interval_at_bureau: 30, output: $stdout )
 			@warehouse = warehouse
+			@workstyle = workstyle
 			@ledger = ledger
 			@merge_method = merge_method
 			@poll_interval_at_bureau = poll_interval_at_bureau
 			@output = output
 		end
 
-		# Deliver a parcel to the registry.
-		# Ships it, files a waybill, seals the shelf, waits at the bureau.
+		# Deliver a parcel.
+		# Local gesture: push main to backup vault.
+		# Remote gesture: ship to Bureau, file waybill, poll, register.
 		def deliver( parcel, title: nil, body_file: nil, commit_message: nil )
+			return deliver_locally( parcel ) if @workstyle == :local
+
 			result = {
 				command: "deliver",
 				label: parcel.label,
@@ -246,6 +255,41 @@ module Carson
 			result[ :diagnostic ] = waybill.ci_diagnostic
 		end
 
+		# Local gesture: push main to the backup vault.
+		# The parcel is already in the vault (accepted by the Warehouse).
+		# The courier's job is to push the vault state to the remote backup.
+		def deliver_locally( parcel )
+			result = {
+				command: "deliver",
+				label: parcel.label,
+				remote_main: "#{@warehouse.bureau_address}/#{@warehouse.main_label}"
+			}
+
+			remote = @warehouse.bureau_address
+			main = @warehouse.main_label
+			root = @warehouse.main_worktree_root
+
+			# --no-verify bypasses the pre-push hook that blocks direct pushes
+			# to main in governed repos. This IS Carson's delivery — the vault
+			# accepted the parcel, now the courier backs it up.
+			_, stderr, status = Open3.capture3(
+				"git", "-C", root, "push", "--no-verify", remote, main
+			)
+
+			if status.success?
+				result[ :exit ] = OK
+				result[ :outcome ] = "delivered"
+				result[ :synced ] = true
+			else
+				result[ :exit ] = OK
+				result[ :outcome ] = "delivered"
+				result[ :synced ] = false
+				result[ :backup_error ] = stderr.strip
+			end
+
+			result
+		end
+
 		# Is the waybill blocked by something that won't resolve by waiting?
 		# CI failure, merge conflict, policy block — the courier should take
 		# the parcel back immediately.

data/lib/carson/runtime/deliver.rb

@@ -20,6 +20,7 @@ module Carson
 					head: current_head
 				)
 				courier = Courier.new( warehouse,
+				workstyle: :remote,
 				ledger: ledger,
 				merge_method: config.govern_merge_method,
 				poll_interval_at_bureau: config.poll_interval_at_bureau,

data/lib/carson/warehouse/vault.rb

@@ -0,0 +1,76 @@
+# The warehouse's vault concern.
+# The vault is local main — where accepted parcels live.
+# In local-centred workstyle, the vault is the source of truth.
+# In remote-centred workstyle, the vault is the backup (receives
+# the standard from the bureau's registry after acceptance).
+require "open3"
+
+module Carson
+	class Warehouse
+		module Vault
+
+			# Accept a parcel into the vault.
+			# Fast-forwards local main to include the parcel's branch.
+			# Runs from the main worktree root where main is checked out.
+			#
+			# Precondition: the parcel's branch must be a fast-forward of main.
+			# If not, the agent must rebase first.
+			#
+			# Returns a result hash:
+			#   { status: "ok", branch: ..., head: ... }
+			#   { status: "block", error: ..., recovery: ... }
+			#   { status: "error", error: ..., recovery: ... }
+			def accept!( parcel )
+				root = main_worktree_root
+
+				# Verify main is checked out in the main worktree.
+				unless main_checked_out_at?( root )
+					return {
+						status: "error",
+						error: "#{@main_label} is not checked out in the main worktree.",
+						recovery: "Check the main worktree state at #{root}."
+					}
+				end
+
+				# Fast-forward main to include the parcel's branch.
+				_, stderr, status = Open3.capture3(
+					"git", "-C", root, "merge", "--ff-only", parcel.label
+				)
+
+				return vault_accepted( parcel, root ) if status.success?
+
+				vault_blocked( parcel, stderr )
+			end
+
+		private
+
+			# Check whether main is the checked-out branch at a given path.
+			def main_checked_out_at?( root )
+				head_ref, _, status = Open3.capture3(
+					"git", "-C", root, "rev-parse", "--abbrev-ref", "HEAD"
+				)
+				status.success? && head_ref.strip == @main_label
+			end
+
+			# Build the success result after vault acceptance.
+			def vault_accepted( parcel, root )
+				new_head, = Open3.capture3( "git", "-C", root, "rev-parse", "HEAD" )
+				{
+					status: "ok",
+					branch: parcel.label,
+					head: new_head.strip
+				}
+			end
+
+			# Build the blocked/error result when vault acceptance fails.
+			def vault_blocked( parcel, stderr )
+				{
+					status: "block",
+					error: "#{parcel.label} cannot be fast-forwarded into #{@main_label}.",
+					recovery: "Rebase onto #{@main_label} and deliver again."
+				}
+			end
+
+		end
+	end
+end

data/lib/carson/warehouse.rb

@@ -6,6 +6,7 @@ require "fileutils"
 require "open3"
 
 require_relative "warehouse/workbench"
+require_relative "warehouse/vault"
 require_relative "warehouse/seal"
 require_relative "warehouse/bureau"
 
@@ -16,6 +17,7 @@ module Carson
 	# managing workbenches, and sweeping up.
 	class Warehouse
 		include Workbench
+		include Vault
 		include Seal
 		include Bureau
 
@@ -140,6 +142,49 @@ module Carson
 			end
 		end
 
+		# --- Delivery prep ---
+
+		# Prepare a parcel for delivery.
+		# Orchestrates the prep phase: pack, fetch, standard check, auto-rebase.
+		# Returns { status: "ok" } or { status: "block"/"error", error:, recovery: }.
+		def prepare!( parcel, message: nil )
+			registry = "#{bureau_address}/#{main_label}"
+
+			# Pack if the agent provided a commit message.
+			if message
+				unless pack!( message: message )
+					return { status: "error", error: "Nothing to commit.", recovery: "Stage changes first." }
+				end
+				# Update the parcel's head after packing.
+				parcel = Parcel.new( label: parcel.label, head: current_head )
+			end
+
+			# Fetch the latest standard.
+			unless fetch_latest
+				return {
+					status: "block",
+					error: "Cannot fetch latest standard.",
+					recovery: "Check network and remote config, then deliver again."
+				}
+			end
+
+			# Check if the parcel is based on the latest standard.
+			unless based_on_latest_standard?( parcel, registry: registry )
+				# Auto-rebase onto the latest standard.
+				unless rebase_on_latest_standard!( registry: registry )
+					return {
+						status: "block",
+						error: "#{parcel.label} conflicts with #{@main_label}.",
+						recovery: "Rebase onto #{@main_label}, resolve conflicts, deliver again."
+					}
+				end
+				# Update the parcel's head after rebase.
+				parcel = Parcel.new( label: parcel.label, head: current_head )
+			end
+
+			{ status: "ok", parcel: parcel }
+		end
+
 		# --- Inventory ---
 
 		# All labels (branch names).

data/lib/cli.rb

@@ -1023,12 +1023,16 @@ module Carson
 			when "template:apply"
 				runtime.template_apply!( push_prep: parsed.fetch( :push_prep, false ) )
 			when "deliver"
-				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 )
-				)
+				if runtime.config.workstyle == :local
+					dispatch_deliver_locally( parsed: parsed, runtime: runtime )
+				else
+					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 )
+					)
+				end
 			when "recover"
 				runtime.recover!(
 					check_name: parsed.fetch( :check_name ),
@@ -1081,6 +1085,81 @@ module Carson
 			report_workbench( result: result, json: parsed.fetch( :json, false ), output: runtime.output )
 		end
 
+		# --- Local-centred delivery ---
+		# CLI orchestrates: prepare → accept → courier.deliver.
+		# No Runtime — follows the checkin/checkout pattern.
+
+		def self.dispatch_deliver_locally( parsed:, runtime: )
+			# The warehouse must be at the current worktree (where the agent works),
+			# not the main worktree root. The agent's branch and head live here.
+			warehouse = Warehouse.new(
+				path: runtime.send( :work_dir ),
+				main_label: runtime.config.main_branch,
+				bureau_address: runtime.config.git_remote
+			)
+			parcel = Parcel.new( label: warehouse.current_label, head: warehouse.current_head )
+			message = parsed.fetch( :commit_message, nil )
+			json = parsed.fetch( :json, false )
+			output = runtime.output
+
+			# Step 1: Prepare.
+			prep = warehouse.prepare!( parcel, message: message )
+			unless prep[ :status ] == "ok"
+				prep[ :command ] = "deliver"
+				return report_deliver( result: prep, json: json, output: output )
+			end
+
+			# Update parcel if prepare rebased or packed.
+			parcel = prep[ :parcel ] || parcel
+
+			# Step 2: Accept into vault.
+			accept = warehouse.accept!( parcel )
+			accept[ :command ] = "deliver"
+			unless accept[ :status ] == "ok"
+				return report_deliver( result: accept, json: json, output: output )
+			end
+
+			# Step 3: Courier delivers backup.
+			courier = Courier.new( warehouse, workstyle: :local, output: output )
+			backup = courier.deliver( parcel )
+
+			# Combine results.
+			result = accept.merge( backup.slice( :outcome, :synced, :backup_error ) )
+			result[ :command ] = "deliver"
+			result[ :outcome ] ||= "delivered"
+			report_deliver( result: result, json: json, output: output )
+		end
+
+		# Render a local delivery result.
+		def self.report_deliver( result:, json:, output: )
+			status = result[ :status ]
+			exit_code = case status
+				when "ok" then Runtime::EXIT_OK
+				when "block" then Runtime::EXIT_BLOCK
+				else Runtime::EXIT_ERROR
+			end
+
+			if json
+				output.puts JSON.pretty_generate( result )
+			else
+				case status
+				when "ok"
+					output.puts "#{BADGE} #{result[ :branch ]} merged into main."
+					if result[ :synced ]
+						output.puts "#{BADGE} Pushed to #{result.fetch( :remote_main, "remote" )}."
+					elsif result[ :backup_error ]
+						output.puts "#{BADGE} Backup failed."
+						output.puts "  \u2192 git push"
+					end
+				when "block", "error"
+					output.puts "#{BADGE} #{result[ :error ]}"
+					output.puts "  \u2192 #{result[ :recovery ]}" if result[ :recovery ]
+				end
+			end
+
+			exit_code
+		end
+
 		# Build a Warehouse rooted at the main worktree.
 		# Uses runtime's resolved root and config for remote/branch names.
 		def self.build_warehouse( runtime: )

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 4.2.1
+  version: 4.3.0
 platform: ruby
 authors:
 - Hailei Wang
@@ -84,6 +84,7 @@ files:
 - lib/carson/warehouse.rb
 - lib/carson/warehouse/bureau.rb
 - lib/carson/warehouse/seal.rb
+- lib/carson/warehouse/vault.rb
 - lib/carson/warehouse/workbench.rb
 - lib/carson/waybill.rb
 - lib/carson/worktree.rb