carson 3.22.0 → 3.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e75b6729cf0c977beb1ace5da390f41ae20d80208d7470c97b145b76e44cb3ad
-  data.tar.gz: 24d85c37e66498731b9d980b39017a4d73c06c93acd1dd8018e74b33e951d4df
+  metadata.gz: 3b09da719cacfca1da3e00f8c542719283e0f1e0d73554371449fa01d3d1b331
+  data.tar.gz: 33d2ab2f5881e8f96934037f715893492b495354eda5c77c64b47ded8d1ee710
 SHA512:
-  metadata.gz: df4ff4c103415e7ff448ee5c8d7bbd60b4259afa15f522d840519b420e0202dc8cb7e86af7d27df0174c8df963eb57cf13fd578678e3c960b669f94e81089d6b
-  data.tar.gz: fcc758b8416931f303dbd72bcabac9f703b844c79b1dd37eec4572b43abe455bca81ca0f8f9871c09a2ee27f086f70c3e977b78b5c078d6820d8f8d770fb74c2
+  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
 
@@ -84,12 +87,7 @@ Blocked Carson artefacts in host repositories:
 - `.tools/carson/*`
 
 Allowed Carson-managed persistence in host repositories:
-- `.github/carson.md` — governance baseline (source of truth)
-- `.github/copilot-instructions.md` — agent discovery pointer for Copilot
-- `.github/CLAUDE.md` — agent discovery pointer for Claude Code
-- `.github/AGENTS.md` — agent discovery pointer for Codex
-- `.github/pull_request_template.md` — PR template
-- Any file discovered from `template.canonical` — user's canonical `.github/` files
+- Any file discovered from `lint.canonical` — user's canonical GitHub and lint-policy files
 
 ## Configuration interface
 
@@ -109,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`
 
@@ -120,40 +117,42 @@ 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:
 
 ```json
 {
-  "template": {
+  "lint": {
     "canonical": "~/AI/CODING/LINT"
   }
 }
 ```
 
-`template` semantics:
-- `canonical`: path to a directory of canonical `.github/` files. Carson discovers files in this directory and syncs them to governed repos alongside its own governance files. The directory mirrors `.github/` structure — `workflows/lint.yml` deploys to `.github/workflows/lint.yml`. Default: `nil` (no canonical files).
+`lint` semantics:
+- `canonical`: path to a directory of canonical GitHub and lint-policy files. Carson discovers files in this directory and syncs them to governed repos. Explicit GitHub paths stay under `.github/` (`workflows/lint.yml` → `.github/workflows/lint.yml`, `.github/labeler.yml` → `.github/labeler.yml`); flat policy files default to `.github/linters/` (`rubocop.yml` → `.github/linters/rubocop.yml`). Legacy root lint configs become stale and are removed on apply. Default: `nil` (no canonical files). The deprecated alias `template.canonical` is still accepted when loading config.
 
 ## Output interface
 

data/MANUAL.md

@@ -39,7 +39,7 @@ On first run (no `~/.carson/config.json` exists), `onboard` launches `carson set
 - Hook installation under `~/.carson/hooks/<version>/`.
 - Repository `core.hooksPath` alignment to Carson global hooks.
 - Commit-time governance gate via managed `pre-commit` hook.
-- Managed `.github/*` template synchronisation.
+- Canonical `.github/*` template synchronisation (when `lint.canonical` is configured).
 - Initial governance audit.
 
 ### Reconfigure later
@@ -48,11 +48,11 @@ 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
 
-After `onboard`, commit the generated `.github/*` changes in your repository. From this point the repository is governed.
+After `onboard`, commit any `.github/*` changes in your repository. From this point the repository is governed.
 
 ## CI Setup
 
@@ -82,37 +82,70 @@ Notes:
 
 ### Canonical Templates
 
-Carson manages 5 governance files (carson.md, CLAUDE.md, AGENTS.md, copilot-instructions.md, pull_request_template.md). Beyond those, you can tell Carson about your own canonical `.github/` files — CI workflows, linter configs, labeller rules, anything that belongs in `.github/`.
+Carson has no built-in template files. Instead, you tell Carson about your own canonical GitHub and lint-policy files via `lint.canonical`.
 
-Set `template.canonical` in `~/.carson/config.json`:
+Set `lint.canonical` in `~/.carson/config.json`:
 
 ```json
 {
-  "template": {
+  "lint": {
     "canonical": "~/AI/CODING/LINT"
   }
 }
 ```
 
-That directory mirrors the `.github/` structure:
+Flat lint-policy directories default to `.github/linters/`, while explicit GitHub paths stay under `.github/`:
 
 ```
 ~/AI/CODING/LINT/
+├── rubocop.yml           → deployed to .github/linters/rubocop.yml
+├── ruff.toml             → deployed to .github/linters/ruff.toml
 ├── workflows/
 │   └── lint.yml          → deployed to .github/workflows/lint.yml
-├── .mega-linter.yml      → deployed to .github/.mega-linter.yml
-└── labeler.yml           → deployed to .github/labeler.yml
+└── .github/
+    └── labeler.yml       → deployed to .github/labeler.yml
 ```
 
-Carson discovers files in this directory and syncs them to governed repos alongside its own governance files. `carson template check` detects drift, `carson template apply` writes them, and `carson refresh` propagates them to the remote.
+Carson discovers files in this directory and syncs them to governed repos. Root files that are not recognised GitHub artefacts are treated as lint policy and written under `.github/linters/`; legacy root lint configs become stale and are removed on apply. `carson template check` detects drift, `carson template apply` writes them, and `carson refresh` propagates them to the remote. Carson still reads the deprecated `template.canonical` key for backwards compatibility, but new setup writes `lint.canonical`.
 
 **Why this design.** Lint, CI, and tooling config are personal decisions — not governance decisions. Carson's job is to deliver your canonical files reliably, not to decide what they should contain.
 
+## Operating Strategies
+
+These strategies are the audit lens for Carson. If behaviour departs from them, either the product model or the implementation needs attention.
+
+### Git Strategist
+
+- **Worktree-first discipline** — substantive work happens in worktrees, never on the main working tree. This keeps concurrent agent work isolated and makes cleanup explicit.
+- **Deterministic base selection** — new work starts from the repo's chosen integration authority, not from whatever branch state happens to be lying around.
+- **Single landing path per authority** — in `remote`, completed work rejoins through remote `main`; in `local`, completed work rejoins through local `main` and then pushes `main` as backup.
+- **Content-aware merge detection** — Carson proves whether a branch's content is already on `main` without relying on commit SHAs, so squash and rebase merges are handled correctly.
+- **Worktree-aware delivery** — Carson lands work without assuming `main` can be checked out in the active worktree, and cleanup is deferred to the correct context.
+- **Exact post-merge guidance** — after a successful landing, Carson tells the caller the next clean-up command instead of leaving the lifecycle half-finished.
+
+### Repo Governor
+
+- **Outsider boundary** — Carson governs repositories without writing Carson-specific config, scripts, or runtime payloads into them.
+- **Command ownership** — in governed repositories, Carson owns worktree and delivery operations so agents do not mix raw git flows with governed ones.
+- **Authority enforcement** — every governed repo has one integration authority at a time. That authority determines how work starts and how it returns to shared truth.
+- **Active review gating** — when the repo uses PR-based delivery, review findings must be acknowledged before merge. Feedback is never silently buried.
+- **Portfolio triage** — `carson govern` applies the same discipline across multiple repositories: classify, merge, dispatch, or escalate.
+- **Template propagation** — Carson treats canonical policy files as managed infrastructure and keeps them consistent across repos.
+
+### Safety Strategies
+
+- **Process-aware worktree removal** — Carson checks whether the current shell or another process has its CWD inside a worktree before attempting removal.
+- **Stale worktree sweep** — Carson removes worktrees whose content has already been absorbed into `main` so dead state does not block later maintenance.
+- **Protected branch preservation** — Carson never deletes protected branches and does not prune branches that are still held by active worktrees.
+- **Hook bypass only for managed operations** — Carson uses controlled bypasses such as `--no-verify` only for its own managed flows, not as a general escape hatch.
+- **Self-diagnosing errors** — blocks and failures must explain the condition and prescribe the exact recovery command.
+- **Self-configuring guardrails** — running Carson should install and refresh its own safeguards rather than expecting manual post-install housekeeping.
+
 ## Agent Worktree Workflow
 
 The core workflow for coding agents using Carson. One command per step, full lifecycle.
 
-**1. Create a worktree** — Carson auto-syncs main before branching (3.13.0+), so the worktree always starts from the latest code:
+**1. Create a worktree** — Carson starts new work from the repo's chosen integration authority rather than from the caller's current HEAD. When that authority requires sync, Carson checks it before branching:
 
 ```bash
 carson worktree create my-feature
@@ -121,18 +154,26 @@ cd /path/to/.claude/worktrees/my-feature
 
 **2. Work** — make changes, commit, iterate.
 
-**3. Deliver and merge** — push, create PR, merge when CI passes. After merge, Carson prints the exact next command (3.13.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. Managed template drift is corrected and committed automatically before push (3.23.0+).
+
+```bash
+carson deliver
+# Output: PR #N, Delivery: queued|gated
+#   Next: carson status
+```
+
+**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
-carson deliver --merge
-# Output: Merged PR #N via squash.
-#   Next: cd /path/to/repo && carson worktree remove my-feature
+carson status
+carson govern --loop 300
 ```
 
-**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+):
+**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
+cd /path/to/repo
+carson worktree remove my-feature
 carson prune
 ```
 
@@ -142,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
 
@@ -152,7 +193,7 @@ Claude Code has a built-in `EnterWorktree` tool. Both create a git worktree unde
 
 | Concern | EnterWorktree | Carson |
 |---|---|---|
-| Auto-sync main before branching | No — branches from current HEAD, which may be stale | Yes — `git pull --ff-only` before branch creation |
+| Governed baseline before branching | No — branches from current HEAD, which may be stale | Yes — branches from the repo's governed baseline rather than the caller's current HEAD |
 | CWD guard on removal | No | Yes — blocks if shell is inside the worktree |
 | Unpushed-commits guard | No | Yes — blocks if work hasn't been pushed |
 | Content-aware squash/rebase detection | No | Yes — compares tree content, not SHAs |
@@ -238,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.
@@ -247,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
-
-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 Policy
 
-```json
-{
-  "govern": {
-    "merge": {
-      "method": "squash"
-    }
-  }
-}
-```
+Governed integration is fixed to `squash`. Carson no longer exposes merge-method choice for governed delivery, and config validation rejects non-squash values.
 
-**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.
@@ -274,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
 
@@ -304,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
 
@@ -347,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
 
@@ -362,22 +389,6 @@ How much Carson prints.
 - Default: **concise**. A healthy audit prints one line. Problems print actionable summaries with cause and fix.
 - `--verbose` restores full diagnostic key-value output for debugging.
 
-## Agent Discovery
-
-Carson writes managed files that help interactive agents (Claude Code, Codex, Copilot) discover the governance system when they work in a governed repository.
-
-**How it works:**
-
-- `.github/AGENTS.md` — full governance baseline; read by Codex and other agents. Points to `carson.md`.
-- `.github/CLAUDE.md` — read by Claude Code at session start. Points to `AGENTS.md`.
-- `.github/copilot-instructions.md` — read by GitHub Copilot. Points to `AGENTS.md`.
-
-Each agent reads its own expected filename and follows the reference to the shared baseline. One file to maintain, zero drift across agents.
-
-All four files are managed templates — `carson template check` detects drift, `carson template apply` writes them, and `carson offboard` removes them.
-
-**Why this matters:** without discovery, agents working in governed repos hit Carson's hooks blindly and don't understand the governance contract. With discovery, agents know to run `carson audit` before committing, `carson review gate` before recommending a merge, and to respect protected refs.
-
 ## Configuration
 
 Default global config path: `~/.carson/config.json`.
@@ -398,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

@@ -2,97 +2,89 @@
 
 # ⧓ Carson
 
-*Carson at your service.*
+Named after the butler of Downton Abbey, Carson is a strategic governor for multiple agents working in one repo.
 
-Named after the head of household in Downton Abbey, Carson is your repositories' autonomous governance runtime — you write the code, Carson manages everything else. From commit-time checks through PR triage, agent dispatch, merge, and cleanup, Carson runs the household with discipline and professional standards. Carson itself has no intelligence — it follows a deterministic decision tree. The intelligence comes from the coding agents it dispatches (Codex, Claude) to fix problems.
+Carson is deterministic infrastructure for concurrent agent work. It governs how work starts, how it rejoins shared truth, and how the repo is cleaned up afterwards so agents can code without trampling each other. The agents provide the intelligence; Carson provides the discipline.
+
+Carson was built in real work. Its strategies come from scars: more than ten agents running across multiple projects at once, with each repeated failure turned into a rule, guardrail, or recovery path.
 
 ## The Problem
 
-Managing a growing portfolio of repositories is rewarding work — but the operational overhead scales faster than the code itself. PR templates go stale, reviewer feedback gets quietly buried, and what passes on a developer's laptop fails in CI. When coding agents start producing PRs across multiple projects, the coordination load multiplies: checking results, dispatching fixes, clicking merge, cleaning up branches.
+When several agents work on one repository, plain Git leaves too much to habit. Branches start from different bases, work lands back on `main` through inconsistent paths, old worktrees linger, and one clean-up step can disrupt another session.
 
-Carson exists so you can focus on what matters — building — while governance runs itself.
+Carson solves that single-repo concurrency problem first, then extends the same discipline across multiple repositories.
 
 ## What Carson Does
 
-Carson is an autonomous governance runtime that lives on your workstation and in CI, never inside the repositories it governs. It operates at two levels:
+Carson lives on your workstation and in CI, never inside the repositories it governs. Two roles, one tool:
 
-**Per-commit governance** — Carson gates merges on unresolved review comments, synchronises templates, and keeps your local branches clean. Every commit triggers `carson audit` through managed hooks; the same checks run in GitHub Actions.
+**Git strategist** — Carson decides how new work begins, which base it uses, how it returns to shared truth, and how cleanup happens safely.
 
-**Portfolio-level autonomy** — `carson govern` is a triage loop that scans your registered repositories, classifies every open PR, and acts: merge what's ready, dispatch coding agents (Codex or Claude) to fix what's failing, and escalate what needs human judgement. One command, all your projects, unmanned.
+**Repo governor** — Carson enforces the repo's operating contract: worktree-first flow, Carson-owned delivery operations, policy checks, and exact recovery guidance when work cannot proceed.
 
 ```
   ~/.carson/                     ← Carson lives here, never inside your repos
        │
-       ├─ hooks ──────────────►  commit gates      (every governed repo)
-       └─ govern ─────────────►  PR triage → merge | dispatch agent | escalate
+       ├─ hooks ──────────────►  commit gates and command guards
+       ├─ worktree flow ──────►  create → work → deliver → clean up
+       └─ portfolio layer ────►  status --all | refresh --all | govern
 ```
 
-This separation is Carson's defining trait — the **outsider boundary**: no Carson scripts, config files, or governance payloads are ever placed inside a governed repository.
-
-**Agent workspace management** — `carson worktree create` and `carson worktree remove` give coding agents safe, isolated workspaces. Unlike Claude Code's built-in `EnterWorktree`, Carson auto-syncs main before branching, guards against removing worktrees with unpushed work or an active shell inside, detects squash/rebase merges so removal doesn't falsely block, and cleans up the local and remote branch in one step. The two tools are complementary — see `MANUAL.md § Carson vs Claude Code EnterWorktree` for the full comparison.
-
-### The Governance Loop
-
-Carson orchestrates a closed governance loop across two layers:
-
-1. **CI enforcement** — Carson's `audit` gates on CI check status reported by GitHub. The actual CI runs are delegated to GitHub Actions.
-2. **Autonomous triage** — `carson govern` reads CI status, review disposition, and audit health for every open PR. Ready PRs are merged. Failing PRs get a coding agent (Codex or Claude) dispatched to fix them. Stuck PRs are escalated.
+The outsider boundary still matters: Carson governs repositories without becoming a runtime dependency inside them.
 
-Carson's role is governance orchestration — gating on results and dispatching action. The actual CI runs and code fixes are delegated to specialised tools: GitHub Actions for CI and coding agents for remediation.
+## Two Authorities
 
-### Principles
+Each governed repo chooses one integration authority.
 
-Carson is opinionated about governance. These are non-negotiable principles, not configurable defaults:
+**Remote** — remote `main` is the integration authority. Agents still work in local worktrees, but completed work rejoins through remote `main`.
 
-- **Outsider boundary** — Carson lives outside your repo, never inside. No Carson-owned artefacts in your repository. Offboarding leaves no trace.
-- **Active review** — undisposed reviewer findings block merge. Feedback must be acknowledged, not buried.
-- **Self-diagnosing output** — every warning and error names what went wrong, why, and what to do next. If you have to read source code to understand a message, that message is a bug.
-- **Transparent governance** — Carson prepares everything for merge but never oversteps. It does not make decisions for you without telling you.
+**Local** — local `main` is the integration authority. Agents still work in local worktrees, but completed work rejoins through local `main`, then `main` is pushed to the remote as backup.
 
-Everything else bends to your preference. Which branch is main, how PRs are merged, which repositories to govern, which coding agent to dispatch — Carson asks during setup and remembers. Sensible defaults are provided; you only change what matters to you. See `MANUAL.md` for the full list.
+This is about where completed work rejoins shared truth, not about team size. Both authorities use worktrees. The authority changes how work lands, not whether Carson is needed.
 
-## When to Use Carson
+## Principles
 
-- **You run coding agents across multiple repositories** and need a single command that triages every open PR, merges what's ready, dispatches agents to fix what's broken, and reports what needs your attention.
-- **Your PR feedback gets buried.** Carson blocks merge until every reviewer comment is explicitly acknowledged — accepted, rejected, or deferred — so nothing is silently ignored.
-- **CI breaks and nobody notices.** `carson audit` runs on every commit via managed hooks, and `carson govern` watches CI status across your portfolio continuously.
-- **You onboard new repositories often** and want consistent hooks, templates, and governance from the first commit without manual setup.
-- **You want agent-safe worktree management.** `carson worktree create` auto-syncs, branches, and isolates; `carson worktree remove` guards against unpushed work and active shells before cleanup.
+- **Worktree-first** — substantive work happens in worktrees, not on `main`.
+- **Carson-owned operations** — Carson owns worktree and delivery operations in governed repositories.
+- **Self-diagnosing output** — every block should say what happened and the exact next command.
+- **Outsider boundary** — Carson governs repositories without becoming a host-repository runtime dependency.
 
 ## Quickstart
 
-Prerequisites: Ruby `>= 3.4`, `git`, and `gem` in your PATH. `gh` (GitHub CLI) is recommended for full review governance features.
+Prerequisites: Ruby `>= 3.4`, `git`, and `gem` in your `PATH`. `gh` (GitHub CLI) is recommended for review governance features.
 
 ```bash
 gem install carson
-```
+carson onboard your/repo/path
 
-**Onboard a repository:**
+carson worktree create your-worktree
+cd your/repo/path/.claude/worktrees/your-worktree
 
-```bash
-carson onboard /path/to/your-repo
-```
+# work, test, commit
+carson deliver
+carson status
 
-On first run, Carson walks you through setup — remote, main branch, workflow style, merge method — then installs hooks, syncs templates, and runs an initial audit.
+# keep govern running to advance queued deliveries
+carson govern --loop 300
+```
 
-After `carson onboard`, your repository has:
-- Git hooks that run `carson audit` on every commit.
-- Managed `.github/*` templates synchronised from Carson.
-- An initial governance audit report.
+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.
 
-Commit the generated `.github/*` changes, and the repository is governed.
+## Portfolio Layer
 
-**Govern your portfolio.** Once repositories are onboarded, `carson govern` is your recurring command. Run it whenever you want Carson to triage open PRs, enforce review policy, and dispatch coding agents across all governed repos:
+Single-repo depth comes first. Once multiple repositories are onboarded, the same discipline scales out across them:
 
 ```bash
-carson govern --dry-run     # preview what Carson would do, change nothing
-carson govern               # triage PRs, merge ready ones, dispatch agents
-carson govern --loop 300    # run continuously, cycling every 5 minutes
+carson status --all
+carson refresh --all
+carson govern --dry-run
 ```
 
+`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
 
-- **MANUAL.md** — installation, first-time setup, CI configuration, daily operations, full command reference, troubleshooting.
+- **MANUAL.md** — installation, setup, operating strategies, daily workflows, command reference, troubleshooting.
 - **API.md** — formal interface contract: commands, exit codes, configuration schema.
 
 ## Support

data/RELEASE.md

@@ -5,6 +5,29 @@ 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
+
+- **Template sync moved into deliver** — `deliver!` now runs `template_apply!` before push, restoring template drift detection that was lost when 3.21.0 added `--no-verify` to `push_branch!`. The pre-push hook's `template apply --push-prep` block was silently skipped; managed files with drifted content could reach the remote undetected. Canonical content is now written and committed automatically before the push.
+
+### No migration required
+
 ## 3.22.0
 
 ### What changed
@@ -31,7 +54,7 @@ Release-note scope rule:
 ### What changed
 
 - **Command guard for governed repositories** — Carson now detects and blocks raw `git push` and `gh pr create/merge` commands in governed repos, redirecting agents to `carson deliver` instead. Three enforcement layers:
-  - **Pre-push hook** — blocks raw `git push` in governed repos. Carson sets `CARSON_PUSH=1` internally so its own pushes pass through.
+  - **Pre-push hook** — blocks raw `git push` unconditionally in governed repos. Carson uses `--no-verify` internally to skip its own hook. *(Side effect: `--no-verify` also skips the hook's `template apply --push-prep` block — template sync moved into `deliver!` in a later release to restore coverage.)*
   - **Command guard script** — a Claude Code `PreToolUse` hook that intercepts `gh pr create` and `gh pr merge` Bash commands in governed repos.
   - **Existing pre-push guard** — the main/master branch push block now uses the same `BLOCKED` message format with explicit recovery guidance.
 - **`with_env_var` helper** — new Runtime utility for temporarily setting environment variables with guaranteed cleanup.

data/SKILL.md

@@ -1,6 +1,6 @@
 # Carson Skill
 
-You are working in a repository governed by Carson — a deterministic governance runtime. Carson handles git hooks, PR triage, agent dispatch, merge, and cleanup. You provide the intelligence; Carson provides the infrastructure.
+You are working in a repository governed by Carson — an autonomous git strategist and repositories governor. Carson handles git hooks, PR triage, agent dispatch, merge, and cleanup. You provide the intelligence; Carson provides the infrastructure.
 
 ## When to use Carson commands
 

data/VERSION

@@ -1 +1 @@
-3.22.0
+3.23.0