carson 3.24.0 → 3.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92803422cb09be4d2f4b31cf6c0b0f98796373c2a6a403af55c0e09361d0e951
-  data.tar.gz: 36f06f845aca0878e2d18de009e661c662baf08675ce3b3331e08f4f2907cc58
+  metadata.gz: e71c18b520bc6869f6f22cff8593d59b7e4d38a58b7c9f7648d75252fdd8691c
+  data.tar.gz: 468b1b132620b3844ccd5df01907c149ddce5bf987bf2aa4fee6a17f3301cea7
 SHA512:
-  metadata.gz: 356bdf1b684829c5d506d00d303db0473f1cacdfd70d7831c21db201d465dd51fd3c03aa7a63f1cebc5658f6fe98321d6cc2bbc99c6f049753325f8898bb7479
-  data.tar.gz: ecad319106eb238264d3155740c36960521a70448183946c1ed1646d8b1b5291345d7eef8c0463a68e5cc55b0efe5d7687574d1ac2d869eeaaac08b73bafed81
+  metadata.gz: 6a3842a3fdb48ede44c4def41b1533ae43f68b5267a8d1280f1cdf7685b161406f58365002e20b34bb4dfa5a9fc2e788a970cf6c406dd877087844197114148d
+  data.tar.gz: 8ee70fb5f5f06bfc417ae39634f9277a07ca5aaa867a57b14960987a12cbe66a44ea193fc167831645025cd573d599f8cf385e8849c2a40d94ff0c6c43eb5967

data/API.md

@@ -25,13 +25,17 @@ carson <command> [subcommand] [arguments]
 | Command | Purpose |
 |---|---|
 | `carson audit` | Evaluate governance status and generate report output. |
-| `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 deliver [--commit MESSAGE]` | Run Carson-owned branch delivery for the current checkout. Plain `deliver` transports existing commits only; `--commit` creates one all-dirty delivery commit first, then Carson pushes, creates or refreshes the PR, waits for merge readiness, merges when clear, and syncs local `main`. |
+| `carson recover --check NAME [--json]` | Run the exceptional governed recovery path when one governance-owned required check is already red on the default branch. Carson proves the named baseline failure, keeps every other gate intact, merges through the recovery path, and records a machine-readable audit event. |
 | `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 housekeep [--json] [--dry-run]` | Attempt to sync the current repo, then reap dead worktrees, reconcile integrated delivery worktree records from the ledger, and prune stale branches. Safe cleanup still runs when sync is blocked. |
 | `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 [--json]` | Show repository delivery state. Default output is Markdown/text; `--json` is the explicit machine contract. |
+| `carson status [--json]` | Show repository delivery state, including the next queued delivery and blocked-delivery summaries. Default output is Markdown/text; `--json` is the explicit machine contract. |
+| `carson abandon <pr_number\|pr_url\|branch> [--json]` | Close abandoned delivery work and clean up its PR, worktree, and branch when safe. |
 | `carson worktree create <name>` | Create an isolated worktree and branch for a new stream of work. |
+| `carson worktree list [--json]` | Show every registered worktree with PR state and Carson's cleanup recommendation. |
 | `carson worktree remove <path_or_name>` | Remove a worktree safely and clean up its branch when allowed. |
 
 ### Batch commands (Layer 2)
@@ -46,7 +50,9 @@ All batch commands operate across every governed repository registered in `gover
 | `carson prune --all` | Remove stale branches across all governed repos. |
 | `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. |
+| `carson housekeep --all [--loop SECONDS]` | Attempt sync, then reap dead worktrees, reconcile integrated delivery worktree records from the ledger, and prune across all governed repos. Safe cleanup still runs when sync is blocked. |
+
+`--loop SECONDS` runs the housekeep cycle continuously, sleeping SECONDS between cycles. It requires `--all`, accepts only positive integers, and exits cleanly on `Ctrl-C` with a cycle count summary.
 
 ### Govern commands
 
@@ -58,6 +64,12 @@ All batch commands operate across every governed repository registered in `gover
 
 Governed integration is fixed to `squash`. Non-squash `govern.merge.method` values are rejected by config validation.
 
+After a live integration attempt, govern reports the actual outcome. Failed merges stay held at gate instead of being reported as integrated.
+
+After CI and review pass, Carson still checks GitHub mergeability. Conflicting PRs stay held at gate with an explicit merge-conflict summary, while `BEHIND` PRs remain eligible under Carson's current squash policy.
+
+After a successful govern merge, Carson runs the same cleanup path as `housekeep`: sync, reap safe worktrees, then prune.
+
 ### Review commands
 
 | Command | Purpose |
@@ -79,6 +91,15 @@ Governed integration is fixed to `squash`. Non-squash `govern.merge.method` valu
 
 Automation and CI integrations should treat exit `2` as an expected policy failure signal.
 
+## Governance guard contract
+
+In a Carson-governed repository:
+- Raw `git worktree add` and `git worktree remove` are blocked. Use `carson worktree create` and `carson worktree remove`.
+- Raw `git pull --rebase` is blocked. Use `carson sync`.
+- Raw `gh pr create` and `gh pr merge` are blocked. Use `carson deliver`.
+- Bootstrap repair for a baseline-red governance check uses `carson recover --check NAME`, not raw `gh api`.
+- On the governed main working tree, raw `git add` and `git commit` are blocked until a Carson worktree exists for the task.
+
 ## Repository boundary contract
 
 Blocked Carson artefacts in host repositories:
@@ -107,7 +128,6 @@ Environment overrides:
 - `CARSON_REVIEW_SWEEP_STATES`
 - `CARSON_WORKFLOW_STYLE`
 - `CARSON_GOVERN_REPOS`
-- `CARSON_GOVERN_AUTHORITY`
 - `CARSON_GOVERN_AGENT_PROVIDER`
 - `CARSON_GOVERN_CHECK_WAIT`
 
@@ -117,7 +137,6 @@ Environment overrides:
 {
   "govern": {
     "repos": ["~/Dev/project-a", "~/Dev/project-b"],
-    "authority": "remote",
     "agent": {
       "provider": "auto",
       "codex": {},
@@ -127,19 +146,18 @@ Environment overrides:
     "merge": {
       "method": "squash"
     },
-    "state_path": "~/.carson/state.sqlite3"
+    "state_path": "~/.carson/state.json"
   }
 }
 ```
 
 `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`).
 - `merge.method`: `"squash"` only in governed mode.
-- `state_path`: SQLite ledger path for active deliveries and revisions.
+- `state_path`: JSON file path for active deliveries and revisions.
 
 `template` schema:
 

data/MANUAL.md

@@ -117,8 +117,8 @@ These strategies are the audit lens for Carson. If behaviour departs from them,
 ### 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.
+- **Deterministic base selection** — new work starts from a synced remote baseline, not from whatever branch state happens to be lying around.
+- **Single landing path** — completed work rejoins through remote `main` via PR-based delivery.
 - **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.
@@ -127,7 +127,8 @@ These strategies are the audit lens for Carson. If behaviour departs from them,
 
 - **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.
+- **Main-tree protection** — on the governed main working tree, Carson blocks `git add` and `git commit` until the agent creates a Carson worktree for the task.
+- **Governed delivery** — completed work returns to shared truth through remote `main` via PR-based delivery. Carson owns the landing path.
 - **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.
@@ -145,47 +146,76 @@ These strategies are the audit lens for Carson. If behaviour departs from them,
 
 The core workflow for coding agents using Carson. One command per step, full lifecycle.
 
-**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:
+**1. Create a worktree** — Carson syncs remote `main` and starts new work from that baseline rather than from the caller's current HEAD:
 
 ```bash
 carson worktree create my-feature
 cd /path/to/.claude/worktrees/my-feature
 ```
 
+On the governed main working tree, Carson blocks raw `git add` / `git commit` and blocks raw `git worktree add/remove`, raw `git pull --rebase`, and raw `gh pr create/merge`. Use `carson worktree create`, `carson sync`, and `carson deliver` instead.
+
 **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. 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.
+**3. Hand the branch to Carson** — `deliver` is the synchronous happy path. Carson pushes the branch, creates or refreshes the PR, waits for the CI and review signals it can observe, merges when the path is clear, and syncs local `main`. 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
+# Output: merged into main, or held at gate with the next command
 ```
 
-**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:
+**4. Inspect or wait when needed** — when `deliver` cannot merge immediately, `status` shows the current branch, the next queued delivery, and any blocked-delivery summaries for the repository. Keep `govern` running when you want unattended portfolio reassessment and revision dispatch across governed repositories:
 
 ```bash
 carson status
 carson govern --loop 300
 ```
 
-**5. Clean up landed work** — once the delivery is integrated, use Carson cleanup commands from the main worktree:
+### Recover a baseline-red governance check
+
+When a governance-owned required check is already red on the default branch, the PR that repairs it can deadlock behind that same gate. Use the explicit recovery path instead of reaching for raw `gh api`:
+
+```bash
+carson recover --check "Carson governance"
+```
+
+Recovery is narrow. Carson proves that the named check is red on the default branch, verifies that the current branch is repairing the governance surface, requires every other required check and the review gate to pass, then records a machine-readable audit event before reporting success.
+
+If Carson refuses recovery, the message explains the exact missing proof or remaining gate and tells you what to do next.
+
+**5. Clean up landed work** — once the delivery is integrated, use Carson cleanup commands from the main worktree. `worktree list` shows every registered worktree with PR state, absorbed-into-main detection, and Carson's cleanup recommendation:
 
 ```bash
 cd /path/to/repo
-carson worktree remove my-feature
-carson prune
+carson worktree list
+carson housekeep
 ```
 
+`housekeep` still performs safe reaping and branch pruning when `sync` cannot complete. A blocked sync no longer prevents cleanup work that has its own safety evidence.
+
+`housekeep` also reconciles integrated delivery worktree records from the ledger. If the recorded worktree is already gone, Carson clears the stale ledger path. If the worktree still points at the integrated head and is safe to remove, Carson reaps it and clears the ledger path in the same pass.
+
+When you need to abandon a stale branch or PR instead of landing it:
+
+```bash
+carson abandon 291
+# or:
+carson abandon https://github.com/owner/repo/pull/291
+# or:
+carson abandon feature/stale-work
+```
+
+`abandon` closes the PR when it is still open, removes the matching worktree when safe, deletes the local and remote branch refs when allowed, and marks the delivery as failed in Carson's ledger.
+
 **Safety guards** — `worktree remove` blocks when:
 - Shell CWD is inside the worktree (prevents session crash).
 - Branch has unpushed commits with content that differs from main (prevents data loss).
 
 After squash or rebase merge, the content matches main — removal proceeds without `--force`.
 
-**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.
+**Stale worktree recovery** — if a worktree directory is destroyed externally (for example by a raw GitHub merge/delete flow), `worktree remove`, `worktree list`, `housekeep`, and `prune` handle the stale entry gracefully: they clean up the git registration and delete the branch without error when Carson has enough evidence. Use Carson's delivery and cleanup commands instead of raw `gh pr merge --delete-branch` so the worktree directory stays intact for orderly cleanup.
 
 ### Carson vs Claude Code EnterWorktree
 
@@ -264,10 +294,13 @@ carson audit --all             # governance audit across all repos
 carson prune --all             # remove stale branches across all repos
 carson template check --all    # detect template drift across all repos
 carson housekeep --all         # full maintenance cycle across all repos
+carson housekeep --all --loop 300   # housekeep every 5 minutes
 ```
 
 `refresh --all` checks each repo for safety before operating: repos with active worktrees or uncommitted changes are skipped with clear reasons. Other batch commands attempt each repo and report failures without stopping.
 
+`housekeep --all --loop SECONDS` runs the full housekeep cycle continuously, sleeping SECONDS between passes. It requires `--all`, accepts only positive integers, and exits cleanly on `Ctrl-C` with a cycle count summary.
+
 **Periodic maintenance:**
 
 ```bash
@@ -292,6 +325,12 @@ Each cycle runs independently: if one cycle fails (network error, GitHub API tim
 
 `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.
 
+After a live merge attempt, govern reports the actual outcome. Failed merges stay held at gate instead of being reported as integrated.
+
+After CI and review pass, Carson still checks GitHub mergeability. Conflicting PRs stay held at gate with an explicit merge-conflict summary, while `BEHIND` PRs remain eligible under Carson's current squash policy.
+
+After a successful govern merge, Carson runs the same cleanup path as `carson housekeep`: sync, reap safe worktrees, then prune.
+
 The agent provider is configurable via `govern.agent.provider` (`auto`, `codex`, or `claude`). In `auto` mode, Carson selects the first available provider.
 
 ## Governed Integration Policy
@@ -375,15 +414,6 @@ Whether reviewer findings require acknowledgement.
 
 Change: `CARSON_REVIEW_DISPOSITION`.
 
-#### Delivery authority
-
-Where completed work rejoins shared truth.
-
-- **`remote`** (default) — the PR lands on remote `main`.
-- **`local`** — Carson integrates through local `main`, then pushes `main` as backup.
-
-Change: `govern.authority` in config.
-
 #### Output verbosity
 
 How much Carson prints.
@@ -411,7 +441,6 @@ 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_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

@@ -32,20 +32,10 @@ Carson lives on your workstation and in CI, never inside the repositories it gov
 
 The outsider boundary still matters: Carson governs repositories without becoming a runtime dependency inside them.
 
-## Two Authorities
-
-Each governed repo chooses one integration authority.
-
-**Remote** — remote `main` is the integration authority. Agents still work in local worktrees, but completed work rejoins through remote `main`.
-
-**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.
-
-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.
-
 ## Principles
 
 - **Worktree-first** — substantive work happens in worktrees, not on `main`.
-- **Carson-owned operations** — Carson owns worktree and delivery operations in governed repositories.
+- **Carson-owned operations** — Carson owns worktree and delivery operations in governed repositories. Raw `git worktree add/remove`, raw `git pull --rebase`, and raw `gh pr create/merge` are blocked, and `git add` / `git commit` are blocked on the main working tree until you create a Carson worktree.
 - **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.
 
@@ -62,13 +52,16 @@ cd your/repo/path/.claude/worktrees/your-worktree
 
 # 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
+# inspect cleanup recommendations once the work is landed
+carson worktree list
 ```
 
-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.
+`carson deliver` owns the normal branch-delivery path: it pushes the branch, creates or refreshes the PR, waits for the review and CI gates Carson can observe, merges when clear, and syncs local `main`. If CI or review is still pending after Carson's configured wait windows, `deliver` returns a gated state instead of merging. 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.
+
+When one Carson-governed required check is already red on the default branch and the current PR is the repair, use `carson recover --check "..."`. Recovery is the explicit exceptional path: Carson proves the baseline failure, keeps every other gate intact, records an audit event, and never teaches operators to step outside Carson first.
+
+`carson worktree list` is the visibility surface for cleanup: it shows every registered worktree, the branch, PR state, whether the content is already on `main`, and Carson's keep or reap recommendation. When work needs to be abandoned instead of landed, use `carson abandon <pr-number|pr-url|branch>` to close the PR and clean up the branch/worktree safely.
 
 ## Portfolio Layer
 
@@ -80,7 +73,7 @@ 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.
+`carson govern` is the portfolio layer. It reassesses active deliveries across governed repositories, 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.27.0
+
+### What changed
+
+- **3.25.0 — Value objects simplified** — `Delivery` gains `repo_path`, `key` (composite `repo_path:branch:head`), and an embedded `revisions` array. `revision_count` is now derived from `revisions.length`. `Revision` drops `id` and `delivery_id`. Numeric delivery IDs are removed from the model entirely.
+- **3.25.1 — Config defaults updated** — `govern.state_path` default changed from `~/.carson/state.sqlite3` to `~/.carson/state.json`. Fallback leaf follows suit.
+- **3.26.0 — Ledger rewritten from SQLite to JSON** — The delivery ledger is now a plain JSON file (`~/.carson/state.json`) with file-lock protection and atomic writes. Revisions are embedded in their parent delivery. No migration — a missing `state.json` starts with an empty ledger; legacy `state.sqlite3` files are left untouched.
+- **3.26.1 — Consumers use natural keys** — `govern.rb` and `deliver.rb` reference `delivery.key` instead of `delivery.id`. `revisions_for_delivery` uses the delivery object directly. `revision_count:` arguments removed from `update_delivery` calls (count is derived). Human output shows `Delivery: branch → main` instead of `Delivery #id`.
+- **3.27.0 — sqlite3 dependency removed** — `spec.add_dependency "sqlite3"` removed from `carson.gemspec`. Carson has zero native extension dependencies.
+
+### Migration
+
+- If you have an existing `~/.carson/state.sqlite3`, Carson will not read it. Active deliveries start fresh. The old file is not deleted.
+- Any automation referencing `govern.state_path` with `.sqlite3` should update to `.json`.
+
 ## 3.24.0
 
 ### What changed
@@ -47,7 +62,7 @@ Release-note scope rule:
 
 ### 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.
+- **Single-actor branch delivery redesign** — Carson is now the sole actor. Repository and branch state are recorded in a JSON 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.

data/VERSION

@@ -1 +1 @@
-3.24.0
+3.27.0

data/carson.gemspec

@@ -28,7 +28,6 @@ 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/hooks/command-guard

@@ -1,8 +1,9 @@
 #!/usr/bin/env bash
 # Carson command guard — Claude Code PreToolUse hook.
 #
-# Blocks raw `gh pr create` and `gh pr merge` in Carson-governed repositories.
-# Agents should use `carson deliver` instead.
+# Blocks raw worktree and delivery commands in Carson-governed repositories,
+# plus `git add` / `git commit` on the main working tree.
+# Agents should use Carson's governed path instead.
 #
 # Claude Code sends JSON on stdin: {"tool_name": "Bash", "tool_input": {"command": "..."}}
 # To block: print reason to stderr, exit 2.
@@ -22,6 +23,14 @@
 #   ]
 set -euo pipefail
 
+block_command() {
+	local summary="$1"
+	local recovery="$2"
+	echo "$summary" >&2
+	echo "$recovery" >&2
+	exit 2
+}
+
 # Read the tool call JSON from stdin.
 input="$(cat)"
 
@@ -32,14 +41,6 @@ tool_name="$(echo "$input" | jq -r '.tool_name // empty' 2>/dev/null)"
 command_text="$(echo "$input" | jq -r '.tool_input.command // empty' 2>/dev/null)"
 [ -n "$command_text" ] || exit 0
 
-# Check for gh pr commands that Carson replaces.
-# Match only at command position: start of line, or after a shell operator (&&, ||, ;, |).
-# This avoids false positives from gh pr references inside commit messages or string arguments.
-guarded_pattern='(^|&&|\|\||;|\|)\s*gh\s+pr\s+(create|merge)'
-if ! echo "$command_text" | grep -qE "$guarded_pattern"; then
-	exit 0
-fi
-
 # Check if the current directory is inside a governed repository.
 config_file="${HOME}/.carson/config.json"
 [ -f "$config_file" ] || exit 0
@@ -47,12 +48,55 @@ config_file="${HOME}/.carson/config.json"
 repo_root="$(git rev-parse --show-toplevel 2>/dev/null || echo "")"
 [ -n "$repo_root" ] || exit 0
 
-normalised="$(cd "$repo_root" && pwd -P)"
-if ! grep -qF "\"$normalised\"" "$config_file" 2>/dev/null; then
+current_root="$(cd "$repo_root" && pwd -P)"
+common_dir="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null || echo "")"
+if [ -n "$common_dir" ]; then
+	governed_root="$(cd "$(dirname "$common_dir")" && pwd -P)"
+else
+	governed_root="$current_root"
+fi
+
+if ! grep -qF "\"$governed_root\"" "$config_file" 2>/dev/null; then
 	exit 0
 fi
 
-# This is a raw gh pr command in a governed repo — block it.
-echo "This repo is Carson-governed — use \`carson deliver\` instead of raw \`gh pr\`." >&2
-echo "Use \`carson deliver\` instead — it handles push, PR, and merge with safety guards." >&2
-exit 2
+main_branch="$(jq -r '.git.main_branch // "main"' "$config_file" 2>/dev/null || echo "main")"
+[ -n "$main_branch" ] || main_branch="main"
+current_branch="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")"
+on_main_worktree=false
+on_main_branch=false
+[ "$current_root" = "$governed_root" ] && on_main_worktree=true
+[ "$current_branch" = "$main_branch" ] && on_main_branch=true
+
+# Match only at command position: start of line, or after a shell operator (&&, ||, ;, |).
+# This avoids false positives from mentions inside commit messages or string arguments.
+delivery_pattern='(^|&&|\|\||;|\|)\s*gh\s+pr\s+(create|merge)\b'
+worktree_pattern='(^|&&|\|\||;|\|)\s*git\s+worktree\s+(add|remove)\b'
+pull_rebase_pattern='(^|&&|\|\||;|\|)\s*git\s+pull([^;&|]|\\\|)*--rebase\b'
+main_mutation_pattern='(^|&&|\|\||;|\|)\s*git\s+(add|commit)\b'
+
+if grep -qE "$delivery_pattern" <<<"$command_text"; then
+	block_command \
+		"This repo is Carson-governed — use \`carson deliver\` instead of raw \`gh pr\`." \
+		"Use \`carson deliver\` instead — it handles push, PR, and merge with safety guards."
+fi
+
+if grep -qE "$worktree_pattern" <<<"$command_text"; then
+	block_command \
+		"This repo is Carson-governed — use \`carson worktree\` instead of raw \`git worktree\`." \
+		"Use \`carson worktree create <name>\` or \`carson worktree remove <name>\` instead."
+fi
+
+if grep -qE "$pull_rebase_pattern" <<<"$command_text"; then
+	block_command \
+		"This repo is Carson-governed — use \`carson sync\` instead of raw \`git pull --rebase\`." \
+		"Use \`carson sync\` instead — it owns main-branch alignment in governed repos."
+fi
+
+if [ "$on_main_worktree" = true ] && [ "$on_main_branch" = true ] && grep -qE "$main_mutation_pattern" <<<"$command_text"; then
+	block_command \
+		"Main working tree is read-only in this Carson-governed repo." \
+		"Use \`carson worktree create <name>\` first, then run \`git add\` or \`git commit\` inside that worktree."
+fi
+
+exit 0