carson 3.27.0 → 3.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e71c18b520bc6869f6f22cff8593d59b7e4d38a58b7c9f7648d75252fdd8691c
-  data.tar.gz: 468b1b132620b3844ccd5df01907c149ddce5bf987bf2aa4fee6a17f3301cea7
+  metadata.gz: a58a0b99b9cd8c7e241c6278f9b72fd4a6188cf45a51f22a5cb88bb6a83a703a
+  data.tar.gz: 0203fbacb58d17d33f58e90f4b868ad7065c086d0fb0963100eb0cac7f4d5f51
 SHA512:
-  metadata.gz: 6a3842a3fdb48ede44c4def41b1533ae43f68b5267a8d1280f1cdf7685b161406f58365002e20b34bb4dfa5a9fc2e788a970cf6c406dd877087844197114148d
-  data.tar.gz: 8ee70fb5f5f06bfc417ae39634f9277a07ca5aaa867a57b14960987a12cbe66a44ea193fc167831645025cd573d599f8cf385e8849c2a40d94ff0c6c43eb5967
+  metadata.gz: 356111e22c7bf14aac077ebc02b80554713c1228dc7ab36688abdd8fb199e40e9c9965f1da0398e2736545b1bf9ffb38dee11f36081f8d781acc7c23e11d506e
+  data.tar.gz: 2476eae596465a0f3b7256646a7ed8364c709ed6279a3183da6ea4636dc05129cb7168d9e6dc2eee701ff4f05d56ec13e94a0c86719b0ec0dc82ce967548ab1c

data/.github/workflows/carson_policy.yml

@@ -42,7 +42,7 @@ jobs:
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: "4.0"
+          ruby-version: "3.4"
 
       - name: Validate expected version
         run: |

data/API.md

@@ -25,14 +25,14 @@ carson <command> [subcommand] [arguments]
 | Command | Purpose |
 |---|---|
 | `carson audit` | Evaluate governance status and generate report output. |
-| `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 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. Before push, Carson verifies the branch is fresh against the configured remote `main`; behind or unknown freshness blocks delivery without creating or refreshing a PR. If freshness is good, Carson pushes, creates or refreshes the PR, watches the delivery for a bounded settle window, merges when clear, syncs local `main`, and reports merge proof for the delivered branch. Non-integrated exits report `Merge deferred` or `Merge blocked` with explicit handoff commands. |
 | `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 housekeep [--json] [--dry-run]` | Attempt to sync the current repo, then reap worktrees with strong abandonment evidence, 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, including the next queued delivery and blocked-delivery summaries. 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. For the current branch, status also reports Carson's last observed PR state and merge proof when the branch has a Carson delivery record. 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. |
@@ -50,7 +50,7 @@ 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 [--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. |
+| `carson housekeep --all [--loop SECONDS]` | Attempt sync, then reap worktrees with strong abandonment evidence, 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.
 
@@ -58,7 +58,7 @@ All batch commands operate across every governed repository registered in `gover
 
 | Command | Purpose |
 |---|---|
-| `carson govern [--dry-run] [--json] [--loop SECONDS]` | Portfolio-level delivery oversight: assess active deliveries, integrate ready branches, dispatch revisions, and escalate blocked work. |
+| `carson govern [--dry-run] [--json] [--loop SECONDS]` | Portfolio-level delivery oversight: assess active deliveries, integrate ready branches, dispatch revisions, and escalate blocked work. Live integrated rows include merge proof. |
 
 `--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.
 
@@ -66,7 +66,34 @@ Governed integration is fixed to `squash`. Non-squash `govern.merge.method` valu
 
 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 CI and review pass, Carson still checks GitHub mergeability. Conflicting PRs exit as `Merge blocked` with an explicit merge-conflict summary. `BEHIND` is treated as freshness failure: Carson blocks and requires a branch refresh before it will continue.
+
+In `--json` mode, `deliver` still suppresses human output. Every JSON result now includes `watch_window_seconds`, `waited_seconds`, and `merge_attempted`; integrated exits also include a `merge_proof` object; deferred and blocked exits also include a `handoff` object with `reason`, `expectation`, and ordered `next_steps`.
+
+`status --json` extends the `branch` object with:
+
+```json
+{
+  "pull_request": {
+    "number": 299,
+    "url": "https://github.com/example/repo/pull/299",
+    "state": "MERGED",
+    "draft": false,
+    "merged_at": "2026-03-16T09:00:00Z",
+    "summary": "PR #299 is merged."
+  },
+  "merge_proof": {
+    "applicable": true,
+    "proven": true,
+    "basis": "content_identical",
+    "summary": "proven on main — 6 changed files already match main.",
+    "main_branch": "main",
+    "changed_files_count": 6
+  }
+}
+```
+
+On `main`, `branch.merge_proof` is still present with `basis: "not_applicable"`. On non-main branches with no Carson delivery record, `branch.pull_request` and `branch.merge_proof` are `null`. `status --all` remains summary-only in v1 and does not include per-repo merge proof.
 
 After a successful govern merge, Carson runs the same cleanup path as `housekeep`: sync, reap safe worktrees, then prune.
 
@@ -157,7 +184,7 @@ Environment overrides:
 - `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`: JSON file path for active deliveries and revisions.
+- `state_path`: JSON ledger path for active deliveries and revisions. Legacy SQLite ledgers are imported automatically on first read; explicit legacy `.sqlite3` paths keep working after import.
 
 `template` schema:
 

data/MANUAL.md

@@ -66,12 +66,12 @@ on:
 
 jobs:
   governance:
-    uses: wanghailei/carson/.github/workflows/carson_policy.yml@v1.0.0
+    uses: wanghailei/carson/.github/workflows/carson_policy.yml@v3.28.0
     secrets:
       CARSON_READ_TOKEN: ${{ secrets.CARSON_READ_TOKEN }}
     with:
-      carson_ref: "v1.0.0"
-      carson_version: "1.0.0"
+      carson_ref: "v3.28.0"
+      carson_version: "3.28.0"
       rubocop_version: "1.81.0"
 ```
 
@@ -157,16 +157,16 @@ On the governed main working tree, Carson blocks raw `git add` / `git commit` an
 
 **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 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.
+**3. Hand the branch to Carson** — `deliver` is the synchronous happy path. Before any push, Carson verifies the branch is fresh against the configured remote `main`. If freshness is behind or unknown, delivery stops immediately and no PR is created or refreshed. If freshness is good, Carson pushes the branch, creates or refreshes the PR, watches the delivery for a bounded settle window, merges when the path is clear, syncs local `main`, and then reports merge proof for the delivered branch. If the window expires without integration, Carson exits with an explicit `Merge deferred` or `Merge blocked` handoff that states whether merge was attempted and what to run next. 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: merged into main, or held at gate with the next command
+# Output: merged into main, or an explicit deferred/blocked handoff
 ```
 
-**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:
+**4. Inspect or wait when needed** — when `deliver` cannot merge immediately, Carson tells you whether the PR was deferred or blocked, whether merge was attempted, and which command to run next. `status` still shows the current branch, the next queued delivery, and blocked-delivery summaries for the repository. When the current branch has a Carson delivery record, `status` also shows Carson's last observed PR state and merge proof. Keep `govern` running when you want unattended portfolio reassessment and revision dispatch across governed repositories:
 
 ```bash
 carson status
@@ -193,7 +193,7 @@ 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` 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. Absorbed-into-main detection is informational; Carson only auto-reaps when it also has stronger abandonment evidence such as a missing directory, merged PR, or closed abandoned PR.
 
 `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.
 
@@ -325,9 +325,9 @@ 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 a live merge attempt, govern reports the actual outcome. Failed merges stay held at gate instead of being reported as integrated. Successful integrations also report merge proof for the landed branch.
 
-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 CI and review pass, Carson still checks GitHub mergeability. Conflicting PRs exit as `Merge blocked` with an explicit merge-conflict summary. `BEHIND` is treated as a freshness failure, not a harmless squash detail: Carson blocks and requires a branch refresh before it will continue.
 
 After a successful govern merge, Carson runs the same cleanup path as `carson housekeep`: sync, reap safe worktrees, then prune.
 
@@ -359,6 +359,7 @@ These define what Carson *is*. They are not configurable.
 - **Active review** — undisposed reviewer findings block merge; feedback must be acknowledged.
 - **Self-diagnosing output** — every warning and error names what went wrong, why, and what to do next.
 - **Transparent governance** — Carson prepares everything for merge but never makes decisions without telling you.
+- **Structural-edit discipline** — coding agents must not use Python or other blind text-rewrite scripts to edit Carson's Ruby source. Ruby files are edited with scoped patches or Ruby-aware tools so structural `end` boundaries are not truncated by cross-language text munging.
 
 ### Configurable defaults
 

data/README.md

@@ -26,7 +26,7 @@ Carson lives on your workstation and in CI, never inside the repositories it gov
   ~/.carson/                     ← Carson lives here, never inside your repos
        │
        ├─ hooks ──────────────►  commit gates and command guards
-       ├─ worktree flow ──────►  create → work → deliver → clean up
+       ├─ worktree flow ──────►  create → work → deliver → housekeep
        └─ portfolio layer ────►  status --all | refresh --all | govern
 ```
 
@@ -35,6 +35,7 @@ The outsider boundary still matters: Carson governs repositories without becomin
 ## Principles
 
 - **Worktree-first** — substantive work happens in worktrees, not on `main`.
+- **Single landing path** — completed work rejoins shared truth through remote `main` via PR-based delivery.
 - **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.
@@ -50,18 +51,24 @@ carson onboard your/repo/path
 carson worktree create your-worktree
 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"
+# work and test, then commit and hand the branch to Carson
+git add -A
+git commit -m "fix: describe this delivery"
+carson deliver
 
-# inspect cleanup recommendations once the work is landed
-carson worktree list
+# or let Carson create one all-dirty delivery commit:
+# carson deliver --commit "fix: describe this delivery"
+
+# once the delivery is integrated, clean up from the repo root
+cd your/repo/path
+carson housekeep
 ```
 
-`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.
+`carson deliver` runs Carson-owned branch delivery. Before any push, Carson verifies that the branch is fresh against the configured remote `main`. If freshness is behind or unknown, delivery stops with an explicit block and no PR side effect. Plain `deliver` transports existing commits only; `carson deliver --commit "..."` creates one all-dirty delivery commit first, then continues the same flow. If the branch is fresh, Carson pushes it, creates or refreshes the PR, watches the delivery for a bounded settle window, merges when clear, and syncs local `main`. If the settle window expires without integration, Carson exits with an explicit `Merge deferred` or `Merge blocked` handoff instead of leaving the PR mysteriously open. Deferred and blocked exits say whether Carson attempted merge and list the next commands in order.
 
 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.
+`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. Content matching `main` is diagnostic, not standalone proof that a worktree is abandoned. `carson housekeep` is the main cleanup pass: sync main, reap worktrees with strong abandonment evidence (for example a missing directory, merged PR, or closed abandoned PR), and prune stale branches. 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
 
@@ -73,7 +80,7 @@ carson refresh --all
 carson govern --dry-run
 ```
 
-`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.
+`carson govern` is the portfolio layer. It assesses active deliveries across governed repositories, integrates ready branches, dispatches revisions for blocked work, and escalates what still 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,30 @@ 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.28.0
+
+### What changed
+
+- **Merge proof is now a first-class delivery surface** — Carson now proves whether a delivered branch's content is already on `main`, even after squash or rewritten history. `carson status` reports the current branch's last observed PR state and merge proof when Carson is tracking that branch, while `carson deliver` and live `carson govern` integrations report the same proof immediately after landing.
+- **Delivery state now preserves PR telemetry and proof for machine consumers** — the JSON ledger stores the last observed PR state, draft flag, merged timestamp, and merge-proof payload so Carson can report stable `pull_request` and `merge_proof` objects without re-querying GitHub on every status read.
+- **Delivery and worktree safety are harder to break** — sync now refuses to proceed from a detached main worktree, worktree lifecycle guards catch more partial-state failures, and govern/deliver reporting stays consistent when mergeability, freshness, and follow-up paths change underneath the branch.
+
+### No migration required
+
+- Existing workflows continue to work unchanged. Machine consumers may now see additive `merge_proof` and current-branch `pull_request` data in Carson JSON output.
+
+## 3.27.1
+
+### What changed
+
+- **JSON ledger preserves legacy state and FIFO ordering** — legacy SQLite ledgers now import automatically into the JSON store on first read, same branch/head deliveries collapse across repo-path aliases, and queue order stays first-in-first-out even when multiple deliveries share the same timestamp.
+- **sqlite3 support restored for migration** — `carson.gemspec` depends on `sqlite3` again so Carson can import legacy SQLite ledgers, and CI installs the gem before running unit tests.
+- **Script Ruby guards now follow the gem contract** — `script/ci_smoke.sh` and `script/install_global_carson.sh` read the minimum supported Ruby version from `carson.gemspec` instead of hard-coding it, so smoke checks and installer behaviour stay aligned with the published gem.
+
+### Migration
+
+- Existing SQLite ledgers are imported automatically on first read. Explicit legacy `.sqlite3` paths keep working after import.
+
 ## 3.27.0
 
 ### What changed
@@ -27,7 +51,9 @@ Release-note scope rule:
 - **Govern now finds worktree-created deliveries** — `repository_record` stored the worktree CWD as `repo_path` in the ledger, but `govern` looked up deliveries by the main tree path from config. The SQL query never matched, so `carson govern` always reported "no active deliveries" for worktree-created PRs. Now `repository_record` uses `main_worktree_root` so the ledger key is always the canonical main tree path. Also fixed the govern fallback path, `reconcile_delivery!`, `housekeep_repo!`, and `review_evidence` for the same mismatch.
 - **Status shows canonical repository name** — `carson status` from a worktree displayed the worktree folder name (e.g. `feature-branch`) as `Repository:` instead of the actual repository name. Now correctly shows the canonical name.
 
-### No migration required
+### Migration note
+
+- Existing SQLite ledgers are imported automatically on first read. No manual cleanup is required before upgrading.
 
 ## 3.23.3
 

data/VERSION

@@ -1 +1 @@
-3.27.0
+3.28.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/delivery.rb

@@ -8,13 +8,16 @@ module Carson
 
 		attr_reader :repo_path, :repository, :branch, :head, :worktree_path, :status,
 			:pull_request_number, :pull_request_url, :revisions, :cause, :summary,
-			:created_at, :updated_at, :integrated_at, :superseded_at
+			:created_at, :updated_at, :integrated_at, :superseded_at,
+			:pull_request_state, :pull_request_draft, :pull_request_merged_at, :merge_proof
 
 		def initialize(
 			repo_path:, branch:, head:, worktree_path:, status:,
 			pull_request_number:, pull_request_url:, cause:, summary:,
 			created_at:, updated_at:, integrated_at:, superseded_at:,
-			revisions: [], repository: nil
+			revisions: [], repository: nil,
+			pull_request_state: nil, pull_request_draft: nil, pull_request_merged_at: nil,
+			merge_proof: nil
 		)
 			@repo_path = repo_path
 			@repository = repository
@@ -31,6 +34,10 @@ module Carson
 			@updated_at = updated_at
 			@integrated_at = integrated_at
 			@superseded_at = superseded_at
+			@pull_request_state = pull_request_state
+			@pull_request_draft = pull_request_draft
+			@pull_request_merged_at = pull_request_merged_at
+			@merge_proof = merge_proof
 		end
 
 		def key