carson 3.22.1 → 3.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e8e1399ec6024845aecc0b88bd5549a2dc2c4f9a4b8a9852a725a718eb837d9
-  data.tar.gz: cc4e9c3b9fe55e238c394d2056a2fe25afe100bdf1191a7b58cfd9b9f05e0fc6
+  metadata.gz: 3b09da719cacfca1da3e00f8c542719283e0f1e0d73554371449fa01d3d1b331
+  data.tar.gz: 33d2ab2f5881e8f96934037f715893492b495354eda5c77c64b47ded8d1ee710
 SHA512:
-  metadata.gz: 63148df8fdf6cd881b4a63a9c3f330221a60481943e2ec97647242a791b0b672d86cc557fd38062e003d531c8ca2007390d0312731595cb24d115f806a73a6e0
-  data.tar.gz: 74df1a6e073a1c7d4cce7b227344295146d0a3d69c4941b3befe129660ab3eb50ccbbe5465cc35fbabaa7d56f6912ae2f9b6a38f6347e1b1ace2f9eae2e797ed
+  metadata.gz: d5c0dbbae4f9424054cbed42c0d6ed6430643a7f974252bf532f98c8aeeafb5e0962c9204e3e9d806752ac5ee063c98d005b4693d570c2b3d9699b2ac1808bef
+  data.tar.gz: d49e6eef6854bf55eb3fe788e6f549585806a03d9266ef5aefdd42b960b3ed9e9f8750d48c3d893d94415e43a56df685701989724d1ff8af439375218f5af743

data/API.md

@@ -15,7 +15,7 @@ carson <command> [subcommand] [arguments]
 
 | Command | Purpose |
 |---|---|
-| `carson setup` | Interactive quiz to configure remote, main branch, workflow, and merge method. Writes `~/.carson/config.json`. |
+| `carson setup` | Interactive quiz to configure remote, main branch, workflow, and canonical lint-policy path. Writes `~/.carson/config.json`. |
 | `carson onboard [repo_path]` | Apply one-command baseline setup for a target git repository. Auto-triggers `setup` on first run. Installs or refreshes Carson-managed global hooks. |
 | `carson refresh [repo_path]` | Re-apply hooks, templates, and audit after upgrading Carson. Auto-propagates template updates to the remote via worktree (branch workflow: PR on `carson/template-sync`; trunk workflow: push to main). |
 | `carson offboard [repo_path]` | Remove Carson-managed host artefacts, detach Carson hooks path, and deregister from `govern.repos`. |
@@ -25,11 +25,14 @@ 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 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. |
 | `carson template apply` | Write canonical managed template content into host `.github/*` files. |
-| `carson status` | Show repository state (branch, worktrees, PRs, governance). |
+| `carson status [--json]` | Show repository delivery state. Default output is Markdown/text; `--json` is the explicit machine contract. |
+| `carson worktree create <name>` | Create an isolated worktree and branch for a new stream of work. |
+| `carson worktree remove <path_or_name>` | Remove a worktree safely and clean up its branch when allowed. |
 
 ### Batch commands (Layer 2)
 
@@ -41,7 +44,7 @@ All batch commands operate across every governed repository registered in `gover
 | `carson audit --all` | Run governance audit across all governed repos. Reports pass/block/fail per repo. |
 | `carson sync --all` | Sync main branch across all governed repos. |
 | `carson prune --all` | Remove stale branches across all governed repos. |
-| `carson status --all [--json]` | Portfolio-wide status overview with branch, worktrees, and governance state per repo. |
+| `carson status --all [--json]` | Portfolio-wide delivery overview per governed repository. |
 | `carson template check --all` | Read-only template drift detection across all governed repos. |
 | `carson housekeep --all` | Sync, reap dead worktrees, and prune across all governed repos. |
 
@@ -49,11 +52,11 @@ All batch commands operate across every governed repository registered in `gover
 
 | Command | Purpose |
 |---|---|
-| `carson govern [--dry-run] [--json] [--loop SECONDS]` | Portfolio-level PR triage: classify, merge, dispatch agents, escalate. |
+| `carson govern [--dry-run] [--json] [--loop SECONDS]` | Portfolio-level delivery oversight: assess active deliveries, integrate ready branches, dispatch revisions, and escalate blocked work. |
 
 `--loop SECONDS` runs the govern cycle continuously, sleeping SECONDS between cycles. The loop isolates errors per cycle — a single failing cycle does not stop the daemon. `Ctrl-C` cleanly exits with a cycle count summary. SECONDS must be a positive integer.
 
-`govern.merge.method` accepts `squash`, `merge`, or `rebase` (default: `squash`). Squash keeps main linear — one PR, one commit. When the target repository enforces linear history via branch protection, both `squash` and `rebase` are accepted by GitHub — only `merge` is rejected.
+Governed integration is fixed to `squash`. Non-squash `govern.merge.method` values are rejected by config validation.
 
 ### Review commands
 
@@ -104,8 +107,7 @@ Environment overrides:
 - `CARSON_REVIEW_SWEEP_STATES`
 - `CARSON_WORKFLOW_STYLE`
 - `CARSON_GOVERN_REPOS`
-- `CARSON_GOVERN_AUTO_MERGE`
-- `CARSON_GOVERN_MERGE_METHOD`
+- `CARSON_GOVERN_AUTHORITY`
 - `CARSON_GOVERN_AGENT_PROVIDER`
 - `CARSON_GOVERN_CHECK_WAIT`
 
@@ -115,27 +117,29 @@ Environment overrides:
 {
   "govern": {
     "repos": ["~/Dev/project-a", "~/Dev/project-b"],
+    "authority": "remote",
     "agent": {
       "provider": "auto",
       "codex": {},
       "claude": {}
     },
     "check_wait": 30,
-    "auto_merge": true,
     "merge": {
       "method": "squash"
-    }
+    },
+    "state_path": "~/.carson/state.sqlite3"
   }
 }
 ```
 
 `govern` semantics:
 - `repos`: list of local repo paths to govern (empty = current repo only).
+- `authority`: `"remote"` (default) or `"local"`.
 - `agent.provider`: `"auto"`, `"codex"`, or `"claude"`.
 - `agent.codex` / `agent.claude`: provider-specific options (reserved).
 - `check_wait`: seconds to wait for CI checks before classifying (default: `30`).
-- `auto_merge`: `true` (default) — Carson may merge autonomously. Set to `false` to require explicit enablement.
-- `merge.method`: `"squash"` (default), `"merge"`, or `"rebase"`.
+- `merge.method`: `"squash"` only in governed mode.
+- `state_path`: SQLite ledger path for active deliveries and revisions.
 
 `template` schema:
 

data/MANUAL.md

@@ -48,7 +48,7 @@ On first run (no `~/.carson/config.json` exists), `onboard` launches `carson set
 carson setup
 ```
 
-Re-run the interactive setup quiz to change your remote, main branch, workflow style, or merge method. Choices are saved to `~/.carson/config.json`.
+Re-run the interactive setup quiz to change your remote, main branch, workflow style, or canonical lint-policy path. Choices are saved to `~/.carson/config.json`.
 
 ### Commit generated files
 
@@ -154,18 +154,26 @@ cd /path/to/.claude/worktrees/my-feature
 
 **2. Work** — make changes, commit, iterate.
 
-**3. Deliver and merge** — use Carson's landing path for the repo authority. In remote authority that means push, PR, and merge; in local authority that means integrate into local `main` and back it up by pushing `main`. Managed template drift is corrected and committed automatically before push (3.22.1+). After delivery, Carson prints the exact next command:
+**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+).
 
 ```bash
-carson deliver --merge
-# Output: Merged PR #N via squash.
-#   Next: cd /path/to/repo && carson worktree remove my-feature
+carson deliver
+# Output: PR #N, Delivery: queued|gated
+#   Next: carson status
 ```
 
-**4. Clean up** — follow the printed next step. After squash merge, Carson detects the content is on main and allows removal without `--force` (3.13.1+):
+**4. Monitor and advance** — `status` is the delivery surface. It shows the current branch plus active deliveries for the repository. Keep `govern` running to advance queued deliveries and revisions across governed repositories:
 
 ```bash
-cd /path/to/repo && carson worktree remove my-feature
+carson status
+carson govern --loop 300
+```
+
+**5. Clean up landed work** — once the delivery is integrated, use Carson cleanup commands from the main worktree:
+
+```bash
+cd /path/to/repo
+carson worktree remove my-feature
 carson prune
 ```
 
@@ -175,7 +183,7 @@ carson prune
 
 After squash or rebase merge, the content matches main — removal proceeds without `--force`.
 
-**Stale worktree recovery** — if a worktree directory is destroyed externally (e.g. by running `gh pr merge --delete-branch` from inside it), `worktree remove` and `prune` handle the stale entry gracefully: they clean up the git registration and delete the branch without error. Use `carson deliver --merge` instead of raw `gh pr merge --delete-branch` to avoid this situation — `deliver` deliberately omits `--delete-branch` so the worktree directory stays intact for orderly cleanup.
+**Stale worktree recovery** — if a worktree directory is destroyed externally (for example by a raw GitHub merge/delete flow), `worktree remove` and `prune` handle the stale entry gracefully: they clean up the git registration and delete the branch without error. Use Carson's `deliver` + `govern` flow instead of raw `gh pr merge --delete-branch` so the worktree directory stays intact for orderly cleanup.
 
 ### Carson vs Claude Code EnterWorktree
 
@@ -271,7 +279,7 @@ Use `--loop SECONDS` to run `carson govern` as a persistent daemon that cycles o
 
 ```bash
 carson govern --loop 300              # cycle every 5 minutes
-carson govern --loop 300 --dry-run    # observe mode, no merges or dispatches
+carson govern --loop 300 --dry-run    # observe mode, no integration or revision dispatch
 ```
 
 The loop is built-in and cross-platform — no cron, launchd, or Task Scheduler required. Run it in a terminal, tmux, screen, or as a system service.
@@ -280,25 +288,15 @@ Each cycle runs independently: if one cycle fails (network error, GitHub API tim
 
 ### Govern and Coding Agents
 
-`carson govern` dispatches coding agents (Codex or Claude) when a PR has failing CI checks. The agent receives the failure context and attempts to fix the issues in a follow-up commit. If the agent succeeds, the PR re-enters the governance pipeline. If it fails or times out, the PR is escalated for human attention.
+`carson govern` dispatches coding agents (Codex or Claude) when an active delivery is blocked by CI, review, or policy feedback. The agent receives the failure context and attempts a revision. If the agent succeeds, the delivery re-enters the governance pipeline. If it fails repeatedly or times out, the delivery is escalated for human attention.
 
 The agent provider is configurable via `govern.agent.provider` (`auto`, `codex`, or `claude`). In `auto` mode, Carson selects the first available provider.
 
-## Merge Method and Linear History
+## Governed Integration Policy
 
-Carson's `govern.merge.method` controls how `carson govern` merges ready PRs. The options are `squash`, `merge`, and `rebase` (default: `squash`). Set this in `~/.carson/config.json`:
+Governed integration is fixed to `squash`. Carson no longer exposes merge-method choice for governed delivery, and config validation rejects non-squash values.
 
-```json
-{
-  "govern": {
-    "merge": {
-      "method": "squash"
-    }
-  }
-}
-```
-
-**Why squash is the default.** Squash-to-main keeps history linear: one PR = one commit on main. Every commit on main corresponds to a reviewed, CI-passing unit of work. The benefits:
+**Why squash is fixed.** Squash-to-main keeps history linear: one delivered branch = one commit on main. Every commit on main corresponds to a reviewed, CI-passing unit of work. The benefits:
 
 - `git log --oneline` on main tells the full story without merge noise or work-in-progress commits.
 - Every commit is individually revertable — `git revert <sha>` undoes exactly one PR.
@@ -307,10 +305,7 @@ Carson's `govern.merge.method` controls how `carson govern` merges ready PRs. Th
 
 **When to use other methods:**
 
-- `rebase` — if you want to preserve individual commits from the branch on main. Both `squash` and `rebase` are compatible with GitHub's "Require linear history" branch protection — only `merge` is rejected.
-- `merge` — if you want explicit merge commits. This creates a non-linear graph but preserves branch topology.
-
-**Important:** Carson's merge method must match your GitHub repository's allowed merge types. If your repo only allows squash merges and Carson is set to `merge`, govern will fail when it tries to auto-merge. Check your repository settings under Settings > General > Pull Requests.
+There is no governed manual-final-merge mode. Repositories that require a human to perform the final merge are outside Carson's governed delivery contract.
 
 ## Defaults and Why
 
@@ -337,15 +332,13 @@ How code reaches main.
 
 Change: `carson setup` or `CARSON_WORKFLOW_STYLE`.
 
-#### Merge method
+#### Governed integration
 
-How `carson govern` merges ready PRs.
+How Carson lands ready deliveries.
 
-- **`squash`** (default) — one PR = one commit on main. Linear, bisectable history. Every commit is individually revertable. Branch commits are preserved in the PR on GitHub.
-- **`rebase`** — preserves individual branch commits on main. Linear history. Use when commit-level attribution matters.
-- **`merge`** — creates merge commits. Non-linear graph but preserves branch topology. Use when branch structure is meaningful.
+- **`squash`** (fixed) — one delivered branch = one commit on main. Linear, bisectable history. Branch commits remain visible in the PR on GitHub.
 
-Must match your GitHub repo's allowed merge types. Change: `carson setup` or `govern.merge.method` in config.
+This is part of Carson's governed contract, not a setup preference.
 
 #### Git remote
 
@@ -380,13 +373,14 @@ Whether reviewer findings require acknowledgement.
 
 Change: `CARSON_REVIEW_DISPOSITION`.
 
-#### Merge authority
+#### Delivery authority
 
-Whether `carson govern` can merge PRs autonomously.
+Where completed work rejoins shared truth.
 
-- Default: **enabled**. Carson merges PRs that pass all gates (CI green, review clean, audit clean). PRs that need human judgement are escalated, never silently merged.
+- **`remote`** (default) — the PR lands on remote `main`.
+- **`local`** — Carson integrates through local `main`, then pushes `main` as backup.
 
-Disable: `govern.auto_merge: false` in config or `CARSON_GOVERN_AUTO_MERGE=false`.
+Change: `govern.authority` in config.
 
 #### Output verbosity
 
@@ -415,7 +409,7 @@ Common environment overrides:
 | `CARSON_REVIEW_SWEEP_WINDOW_DAYS` | Lookback window for review sweep. |
 | `CARSON_REVIEW_SWEEP_STATES` | PR states to include in sweep. |
 | `CARSON_REVIEW_BOT_USERNAMES` | Comma-separated bot usernames to ignore in review gate and sweep. |
-| `CARSON_GOVERN_AUTO_MERGE` | Enable or disable autonomous PR merging. |
+| `CARSON_GOVERN_AUTHORITY` | Override delivery authority (`remote` or `local`). |
 | `CARSON_WORKFLOW_STYLE` | Workflow style override (`branch` or `trunk`). |
 | `CARSON_RUBY_INDENTATION` | Ruby indentation policy (`tabs`, `spaces`, or `either`). |
 

data/README.md

@@ -57,21 +57,18 @@ Prerequisites: Ruby `>= 3.4`, `git`, and `gem` in your `PATH`. `gh` (GitHub CLI)
 gem install carson
 carson onboard your/repo/path
 
-# Optional: switch from the default remote authority
-carson repo authority local
-
 carson worktree create your-worktree
 cd your/repo/path/.claude/worktrees/your-worktree
 
 # work, test, commit
-carson deliver --merge
+carson deliver
+carson status
 
-cd your/repo/path
-carson worktree remove your-worktree
-carson prune
+# keep govern running to advance queued deliveries
+carson govern --loop 300
 ```
 
-By default, repositories onboard as `remote`. In `remote`, `deliver` lands through remote `main`. In `local`, the same loop lands on local `main` and then pushes `main` to the remote as backup.
+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.
 
 ## Portfolio Layer
 
@@ -83,7 +80,7 @@ carson refresh --all
 carson govern --dry-run
 ```
 
-`carson govern` is the portfolio layer. It triages open PRs, merges what is ready, dispatches agents to fix what is failing, and reports what needs human judgement.
+`carson govern` is the portfolio layer. It advances queued deliveries, dispatches revision work for blocked branches, and surfaces what needs human judgement. Governed integration is squash-only and happens one repository at a time.
 
 ## Where to Read Next
 

data/RELEASE.md

@@ -5,6 +5,21 @@ 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.23.0
+
+### What changed
+
+- **Single-actor branch delivery redesign** — Carson is now the sole actor. Repository and branch state are recorded in a SQLite delivery ledger, `carson deliver` becomes the asynchronous branch handoff, and `carson govern` advances queued deliveries and revision cycles without blocking the caller process.
+- **Status redesigned around deliveries** — `carson status` now reports repository authority, the current branch, active deliveries, and stale-branch counts. `--json` exposes the same delivery-centred model explicitly for software consumers.
+- **Governed integration is squash-only** — Carson now enforces a single governed integration policy. Repository settings must allow squash merge, and Carson rejects governed configs that specify any other merge method.
+- **Setup and help contract simplified** — `carson setup` no longer offers merge-method choice for governed repositories, and `carson deliver --merge` is removed in favour of the single autonomous `carson deliver` path.
+
+### Migration required
+
+- Set governed repositories to allow squash merge before using Carson-governed integration.
+- Update Carson config so `govern.merge.method` is `squash`.
+- Stop using `carson deliver --merge`; use `carson deliver`.
+
 ## 3.22.1
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-3.22.1
+3.23.0

data/carson.gemspec

@@ -28,6 +28,7 @@ Gem::Specification.new do |spec|
 	spec.bindir = "exe"
 	spec.executables = [ "carson" ]
 	spec.require_paths = [ "lib" ]
+	spec.add_dependency "sqlite3", ">= 1.3", "< 3"
 	spec.files = Dir.glob( "{lib,exe,templates,hooks}/**/*", File::FNM_DOTMATCH ).select { |path| File.file?( path ) } + [
 		".github/workflows/carson_policy.yml",
 		"README.md",

data/lib/carson/adapters/agent.rb

@@ -2,14 +2,14 @@
 module Carson
 	module Adapters
 		module Agent
-			WorkOrder = Data.define( :repo, :branch, :pr_number, :objective, :context, :acceptance_checks )
+			WorkOrder = Struct.new( :repo, :branch, :pr_number, :objective, :context, :acceptance_checks, keyword_init: true )
 			# objective: "fix_ci" | "address_review" | "fix_audit"
 			# context: String (legacy — PR title) or Hash with structured evidence:
 			#   fix_ci:         { title:, ci_logs:, ci_run_url:, prior_attempt: { summary:, dispatched_at: } }
 			#   address_review: { title:, review_findings: [{ kind:, url:, body: }], prior_attempt: ... }
 			# acceptance_checks: what must pass for the fix to be accepted
 
-			Result = Data.define( :status, :summary, :evidence, :commit_sha )
+			Result = Struct.new( :status, :summary, :evidence, :commit_sha, keyword_init: true )
 			# status: "done" | "failed" | "timeout"
 		end
 	end

data/lib/carson/branch.rb

@@ -0,0 +1,38 @@
+# Passive branch record. Branch holds identity and current facts only.
+module Carson
+	class Branch
+		attr_reader :repository, :name, :purpose, :head, :worktree, :delivery
+
+		def initialize( repository:, name:, runtime:, purpose: nil, head: nil, worktree: nil, delivery: nil )
+			@repository = repository
+			@name = name
+			@runtime = runtime
+			@purpose = purpose
+			@head = head
+			@worktree = worktree
+			@delivery = delivery
+		end
+
+		# Re-reads the branch facts from git and Carson's ledger.
+		def reload
+			refreshed_head = runtime.git_capture!( "rev-parse", name ).strip
+			refreshed_worktree = runtime.worktree_list.find { |entry| entry.branch == name }&.path || worktree
+			refreshed_delivery = runtime.ledger.active_delivery( repo_path: repository.path, branch_name: name )
+			self.class.new(
+				repository: repository,
+				name: name,
+				runtime: runtime,
+				purpose: purpose,
+				head: refreshed_head,
+				worktree: refreshed_worktree,
+				delivery: refreshed_delivery
+			)
+		rescue StandardError
+			self
+		end
+
+	private
+
+		attr_reader :runtime
+	end
+end

data/lib/carson/cli.rb

@@ -61,11 +61,11 @@ module Carson
 				parser.separator "Repository governance and workflow automation for coding agents."
 				parser.separator ""
 				parser.separator "Commands:"
-				parser.separator "    status       Show repository state (branch, PRs, worktrees)"
+				parser.separator "    status       Show repository delivery state"
 				parser.separator "    setup        Initialise Carson configuration"
 				parser.separator "    audit        Run pre-commit health checks"
 				parser.separator "    sync         Sync local main with remote"
-				parser.separator "    deliver      Push, create PR, and optionally merge"
+				parser.separator "    deliver      Start autonomous branch delivery"
 				parser.separator "    prune        Remove stale local branches"
 				parser.separator "    worktree     Manage isolated coding worktrees"
 				parser.separator "    housekeep    Sync, reap worktrees, and prune branches"
@@ -138,7 +138,7 @@ module Carson
 		def self.parse_setup_command( arguments:, error: )
 			options = {}
 			setup_parser = OptionParser.new do |parser|
-				parser.banner = "Usage: carson setup [--remote NAME] [--main-branch NAME] [--workflow STYLE] [--merge METHOD] [--canonical PATH]"
+				parser.banner = "Usage: carson setup [--remote NAME] [--main-branch NAME] [--workflow STYLE] [--canonical PATH]"
 				parser.separator ""
 				parser.separator "Initialise Carson configuration for the current repository."
 				parser.separator "Detects git remote, main branch, and workflow style, then writes .carson.yml."
@@ -148,13 +148,11 @@ module Carson
 				parser.on( "--remote NAME", "Git remote name" ) { |value| options[ "git.remote" ] = value }
 				parser.on( "--main-branch NAME", "Main branch name" ) { |value| options[ "git.main_branch" ] = value }
 				parser.on( "--workflow STYLE", "Workflow style (branch or trunk)" ) { |value| options[ "workflow.style" ] = value }
-				parser.on( "--merge METHOD", "Merge method (squash, rebase, or merge)" ) { |value| options[ "govern.merge.method" ] = value }
 				parser.on( "--canonical PATH", "Canonical lint policy directory path" ) { |value| options[ "lint.canonical" ] = value }
 				parser.separator ""
 				parser.separator "Examples:"
 				parser.separator "    carson setup                            Auto-detect and write config"
 				parser.separator "    carson setup --remote github            Use 'github' as the git remote"
-				parser.separator "    carson setup --merge squash             Set squash as the merge method"
 			end
 			setup_parser.parse!( arguments )
 			unless arguments.empty?
@@ -547,22 +545,25 @@ module Carson
 		# --- deliver ---
 
 		def self.parse_deliver_command( arguments:, error: )
-			options = { merge: false, json: false, title: nil, body_file: nil }
+			if arguments.include?( "--merge" )
+				error.puts "#{BADGE} carson deliver --merge is no longer supported; use carson deliver"
+				return { command: :invalid }
+			end
+
+			options = { json: false, title: nil, body_file: nil }
 			deliver_parser = OptionParser.new do |parser|
-				parser.banner = "Usage: carson deliver [--merge] [--json] [--title TITLE] [--body-file PATH]"
+				parser.banner = "Usage: carson deliver [--json] [--title TITLE] [--body-file PATH]"
 				parser.separator ""
-				parser.separator "Push the current branch, create a pull request, and optionally merge."
-				parser.separator "Collapses the manual push → PR → merge flow into a single command."
+				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 ""
 				parser.separator "Options:"
-				parser.on( "--merge", "Also merge the PR if CI passes" ) { options[ :merge ] = true }
 				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.separator ""
 				parser.separator "Examples:"
-				parser.separator "    carson deliver               Push and open a PR"
-				parser.separator "    carson deliver --merge       Push, open a PR, and merge if CI passes"
+				parser.separator "    carson deliver               Push, open a PR, and register delivery state"
 			end
 			deliver_parser.parse!( arguments )
 			unless arguments.empty?
@@ -572,7 +573,6 @@ module Carson
 			end
 			{
 				command: "deliver",
-				merge: options.fetch( :merge ),
 				json: options.fetch( :json ),
 				title: options[ :title ],
 				body_file: options[ :body_file ]
@@ -761,7 +761,6 @@ module Carson
 				runtime.template_apply!( push_prep: parsed.fetch( :push_prep, false ) )
 			when "deliver"
 				runtime.deliver!(
-					merge: parsed.fetch( :merge, false ),
 					title: parsed.fetch( :title, nil ),
 					body_file: parsed.fetch( :body_file, nil ),
 					json_output: parsed.fetch( :json, false )

data/lib/carson/config.rb

@@ -30,8 +30,8 @@ module Carson
 			:review_tracking_issue_title, :review_tracking_issue_label, :review_bot_usernames,
 			:audit_advisory_check_names,
 			:workflow_style,
-			:govern_repos, :govern_auto_merge, :govern_merge_method,
-			:govern_agent_provider, :govern_dispatch_state_path,
+			:govern_repos, :govern_authority, :govern_merge_method,
+			:govern_agent_provider, :govern_state_path,
 			:govern_check_wait
 
 		def self.load( repo_root: )
@@ -83,7 +83,7 @@ module Carson
 				},
 				"govern" => {
 					"repos" => [],
-					"auto_merge" => true,
+					"authority" => "remote",
 					"merge" => {
 						"method" => "squash"
 					},
@@ -92,7 +92,7 @@ module Carson
 						"codex" => {},
 						"claude" => {}
 					},
-					"dispatch_state_path" => "~/.carson/govern/dispatch_state.json",
+					"state_path" => "~/.carson/state.sqlite3",
 					"check_wait" => 30
 				}
 			}
@@ -171,8 +171,8 @@ module Carson
 			govern = fetch_hash_section( data: copy, key: "govern" )
 			govern_repos = env_string_array( key: "CARSON_GOVERN_REPOS" )
 			govern[ "repos" ] = govern_repos unless govern_repos.empty?
-			govern_auto_merge = ENV.fetch( "CARSON_GOVERN_AUTO_MERGE", "" ).to_s.strip
-			govern[ "auto_merge" ] = ( govern_auto_merge == "true" ) unless govern_auto_merge.empty?
+			govern_authority = ENV.fetch( "CARSON_GOVERN_AUTHORITY", "" ).to_s.strip
+			govern[ "authority" ] = govern_authority unless govern_authority.empty?
 			govern_method = ENV.fetch( "CARSON_GOVERN_MERGE_METHOD", "" ).to_s.strip
 			unless govern_method.empty?
 				govern[ "merge" ] ||= {}
@@ -209,7 +209,10 @@ module Carson
 			@main_branch = fetch_string( hash: fetch_hash( hash: data, key: "git" ), key: "main_branch" )
 			@protected_branches = fetch_string_array( hash: fetch_hash( hash: data, key: "git" ), key: "protected_branches" )
 
-			@hooks_path = fetch_string( hash: fetch_hash( hash: data, key: "hooks" ), key: "path" )
+			@hooks_path = resolve_runtime_path(
+				path: fetch_string( hash: fetch_hash( hash: data, key: "hooks" ), key: "path" ),
+				fallback_leaf: "hooks"
+			)
 			@managed_hooks = fetch_string_array( hash: fetch_hash( hash: data, key: "hooks" ), key: "managed" )
 
 			template_hash = fetch_hash( hash: data, key: "template" )
@@ -240,13 +243,15 @@ module Carson
 
 			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_auto_merge = fetch_optional_boolean( hash: govern_hash, key: "auto_merge", default: true, key_path: "govern.auto_merge" )
+			@govern_authority = fetch_string( hash: govern_hash, key: "authority" ).downcase
 			govern_merge_hash = fetch_hash( hash: govern_hash, key: "merge" )
 			@govern_merge_method = fetch_string( hash: govern_merge_hash, key: "method" ).downcase
 			govern_agent_hash = fetch_hash( hash: govern_hash, key: "agent" )
 			@govern_agent_provider = fetch_string( hash: govern_agent_hash, key: "provider" ).downcase
-			dispatch_path = govern_hash.fetch( "dispatch_state_path" ).to_s
-			@govern_dispatch_state_path = safe_expand_path( dispatch_path )
+			@govern_state_path = resolve_runtime_path(
+				path: govern_hash.fetch( "state_path" ).to_s,
+				fallback_leaf: "state.sqlite3"
+			)
 			@govern_check_wait = fetch_non_negative_integer( hash: govern_hash, key: "check_wait" )
 
 			validate!
@@ -267,7 +272,8 @@ module Carson
 				raise ConfigError, "review.tracking_issue.title cannot be empty" if review_tracking_issue_title.empty?
 				raise ConfigError, "review.tracking_issue.label cannot be empty" if review_tracking_issue_label.empty?
 				raise ConfigError, "workflow.style must be one of trunk, branch" unless [ "trunk", "branch" ].include?( workflow_style )
-				raise ConfigError, "govern.merge.method must be one of merge, squash, rebase" unless [ "merge", "squash", "rebase" ].include?( govern_merge_method )
+				raise ConfigError, "govern.authority must be one of remote, local" unless [ "remote", "local" ].include?( govern_authority )
+				raise ConfigError, "govern.merge.method must be squash" unless govern_merge_method == "squash"
 				raise ConfigError, "govern.agent.provider must be one of auto, codex, claude" unless [ "auto", "codex", "claude" ].include?( govern_agent_provider )
 			end
 
@@ -319,13 +325,6 @@ module Carson
 			rescue ArgumentError, TypeError
 				raise ConfigError, "config key #{key} must be an integer"
 			end
-			def fetch_optional_boolean( hash:, key:, default:, key_path: nil )
-				value = hash.fetch( key, default )
-				return true if value == true
-				return false if value == false
-
-				raise ConfigError, "config key #{key_path || key} must be boolean"
-			end
 
 			def safe_expand_path( path )
 				return path unless path.start_with?( "~" )
@@ -335,6 +334,23 @@ module Carson
 				path
 			end
 
+			# Resolves Carson-owned runtime paths even when HOME is intentionally invalid.
+			# CI smoke uses that condition to verify TMPDIR and /tmp fallbacks.
+			def resolve_runtime_path( path:, fallback_leaf: )
+				expanded = safe_expand_path( path )
+				return expanded unless expanded.start_with?( "~" )
+
+				File.join( runtime_fallback_root, fallback_leaf )
+			end
+
+			# Shared fallback root for Carson-owned artefacts when HOME cannot be expanded.
+			def runtime_fallback_root
+				tmpdir = ENV.fetch( "TMPDIR", "" ).to_s.strip
+				return File.join( tmpdir, "carson" ) if tmpdir.start_with?( "/" )
+
+				"/tmp/carson"
+			end
+
 			# Returns an expanded path string, or nil when the value is absent/blank.
 			def fetch_optional_path( hash:, key: )
 				value = hash[ key ]