carson 3.13.0 → 3.13.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d653b3c6ec67aa729186db46215c6e51c85a42ac82ca782f5004f9d84e32a31
-  data.tar.gz: 5caa70de1a5c9538c3ef3027ba0862445c9ff2d985ec6f4659231bb40d8e5cb7
+  metadata.gz: d49ac2582d874ea7b4a25a9d71401fd8424b33ef8740ef8c9d1588d81616b00a
+  data.tar.gz: 37d5ba4ebe4c7455eb1751a55cff6724f073bcce37463080fa3324db86c42fac
 SHA512:
-  metadata.gz: 91bd6ee521d91f31c3593558e1b544fcba99eefd1d084fb8c618fad428c470d308ed774e7655b31be9d0fc35969bd9d5354832d5002042396e3d48b8ffde77b2
-  data.tar.gz: 10758df9aeb5d246211592671eb19c59156cbd9fd7cb5d6e31e32186ee36d1caef8fe3dc7c785bdbfbac4e1339ee8d56bf445556a6722395f8eb42a2bfdabe12
+  metadata.gz: 33498b92e55ab4caab2ddb9935ca1ce2b1965e61f03898849720cedbd24e878d981662fa1acad7312addb08d7bb90e83ab72e2f55658087f2af2c3f3d9c37f2c
+  data.tar.gz: 01ee3460c17e00db79f9216592bda4171cc135ceb90ff88d3c83fa8925653f50ad1b3b8ea98e1f6ef37bce1a4f0f2e868d06968d7788e466f54d7d21e99b842b

data/MANUAL.md

@@ -108,6 +108,40 @@ Carson discovers files in this directory and syncs them to governed repos alongs
 
 **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.
 
+## 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:
+
+```bash
+carson worktree create my-feature
+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+):
+
+```bash
+carson deliver --merge
+# Output: Merged PR #N via squash.
+#   Next: cd /path/to/repo && carson worktree remove my-feature
+```
+
+**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+):
+
+```bash
+cd /path/to/repo && carson worktree remove my-feature
+carson prune
+```
+
+**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`.
+
 ## Daily Operations
 
 **Start of work:**

data/RELEASE.md

@@ -5,6 +5,23 @@ 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.13.2
+
+### What changed
+
+- **Fix CI detection in `deliver --merge`** — `check_pr_ci` queried `gh pr checks --json name,state,conclusion` but `conclusion` is not a valid field in current `gh` CLI versions. Every `deliver --merge` silently fell back to "CI: none" and skipped the merge step. Now uses `--json name,bucket` which returns `pass`/`fail`/`pending` directly.
+- **Document agent worktree workflow** — added "Agent Worktree Workflow" section to MANUAL.md covering the full create → work → deliver → clean up lifecycle with 3.13.x improvements.
+
+### UX improvement
+
+- `deliver --merge` now actually detects CI status and merges when green. Previously it always said "CI: none" due to the broken field query.
+
+## 3.13.1
+
+### What changed
+
+- **Content-aware unpushed-commits guard** — `carson worktree remove` no longer falsely blocks after squash or rebase merges. Previously it compared commit SHAs, which differ after squash merge even though the content is on main. Now it compares tree content via `git diff --quiet`: if the branch's content matches main, the work is already merged and removal proceeds without `--force`.
+
 ## 3.13.0
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-3.13.0
+3.13.2

data/lib/carson/runtime/deliver.rb

@@ -214,25 +214,23 @@ module Carson
 			end
 
 			# Checks CI status on a PR. Returns :pass, :fail, :pending, or :none.
-			def check_pr_ci( number: )
-				stdout, _, success, = gh_run(
-					"pr", "checks", number.to_s,
-					"--json", "name,state,conclusion"
-				)
-				return :none unless success
-
-				checks = JSON.parse( stdout ) rescue []
-				return :none if checks.empty?
-
-				conclusions = checks.map { |c| c[ "conclusion" ].to_s.upcase }
-				states = checks.map { |c| c[ "state" ].to_s.upcase }
-
-				return :fail if conclusions.any? { |c| c == "FAILURE" || c == "CANCELLED" || c == "TIMED_OUT" }
-				return :pending if states.any? { |s| s == "PENDING" || s == "QUEUED" || s == "IN_PROGRESS" } ||
-					conclusions.any? { |c| c == "" || c == "PENDING" }
-
-				:pass
-			end
+# Uses the `bucket` field (pass/fail/pending) from `gh pr checks --json`.
+def check_pr_ci( number: )
+	stdout, _, success, = gh_run(
+		"pr", "checks", number.to_s,
+		"--json", "name,bucket"
+	)
+	return :none unless success
+
+	checks = JSON.parse( stdout ) rescue []
+	return :none if checks.empty?
+
+	buckets = checks.map { |c| c[ "bucket" ].to_s.downcase }
+	return :fail if buckets.include?( "fail" )
+	return :pending if buckets.include?( "pending" )
+
+	:pass
+end
 
 			# Checks review decision on a PR. Returns :approved, :changes_requested, :review_required, or :none.
 			def check_pr_review( number: )

data/lib/carson/runtime/local/worktree.rb

@@ -220,6 +220,7 @@ module Carson
 			end
 
 			# Checks whether a branch has unpushed commits that would be lost on removal.
+			# Content-aware: after squash/rebase merge, SHAs differ but tree content may match main. Compares content, not SHAs.
 			# Returns nil if safe, or { error:, recovery: } hash if unpushed work exists.
 			def check_unpushed_commits( branch:, worktree_path: )
 				return nil unless branch
@@ -231,8 +232,16 @@ module Carson
 					# Remote ref does not exist. Only block if the branch has unique commits vs main.
 					unique, _, unique_status, = Open3.capture3( "git", "rev-list", "--count", "#{config.main_branch}..#{branch}", chdir: worktree_path )
 					if unique_status.success? && unique.strip.to_i > 0
-						return { error: "branch has not been pushed to #{remote}",
-							recovery: "git -C #{worktree_path} push -u #{remote} #{branch}, or use --force to override" }
+						# Content-aware check: after squash/rebase merge, commit SHAs differ
+						# but the tree content may be identical to main. Compare content,
+						# not SHAs — if the diff is empty, the work is already on main.
+						diff_out, _, diff_ok, = Open3.capture3( "git", "diff", "--quiet", config.main_branch, branch, chdir: worktree_path )
+						unless diff_ok.success?
+							return { error: "branch has not been pushed to #{remote}",
+								recovery: "git -C #{worktree_path} push -u #{remote} #{branch}, or use --force to override" }
+						end
+						# Diff is empty — content is on main (squash/rebase merged). Safe.
+						puts_verbose "branch #{branch} content matches main — squash/rebase merged, safe to remove"
 					end
 				elsif ahead.strip.to_i > 0
 					return { error: "worktree has unpushed commits",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 3.13.0
+  version: 3.13.2
 platform: ruby
 authors:
 - Hailei Wang