carson 3.20.0 → 3.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e7fdc44d330fd415b8f6d9ee479d5256d6fc860e5d63c7c9287f28ebbdb2ba4
-  data.tar.gz: 19056bd376bcab3b7077e38ba4e42f2b9f5a3ffbf2c8027f0aa6626bb70587fb
+  metadata.gz: 8274b4268c0fc93eeb9323f2b9fd0d4e042001d1633ccde431afcb7f61448bae
+  data.tar.gz: cff9a441857c256c82bf0f395c92a29a2879c5f1da45c4de3ae1232803e0ea5f
 SHA512:
-  metadata.gz: 13f0d5ac83272711329d435a935dd940afc461c5c3b10e20d23842492e8e53f7032cf34a8b027d70db80563af148cda5f99c2c8e7ec4025b94f4d72609ea9d1d
-  data.tar.gz: b1903c6a8f8682adc7b942e49b553579d014d56c0bb65587465568119d41583a14e0cb4a7b00bc61b9165fac79094567395dbf2b39191e3c9d673dc0750dc4f5
+  metadata.gz: 375300bdb2789594fa0a088c3f2d983a31aa492884b7fd399e76f0531885c191b81d855dd35c9d79a488cca6a3fdbdc3da35a9ac24d820901a34558d60bbc4f2
+  data.tar.gz: a5f3ddb10f668b7003578c62bdec28b95c0c584cfe5c93da38d50ffc01e4a03f4a91c31053d02a7a97af396baa247917ce3a5edf95608d801c9ce274024cde04

data/README.md

@@ -6,13 +6,13 @@
 
 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.
 
-## The Problem to Solve
+## 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.
 
 Carson exists so you can focus on what matters — building — while governance runs itself.
 
-## How Carson Works
+## 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:
 
@@ -40,7 +40,7 @@ Carson orchestrates a closed governance loop across two layers:
 
 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.
 
-## Opinions
+### Principles
 
 Carson is opinionated about governance. These are non-negotiable principles, not configurable defaults:
 
@@ -51,6 +51,14 @@ Carson is opinionated about governance. These are non-negotiable principles, not
 
 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.
 
+## When to Use Carson
+
+- **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.
+
 ## Quickstart
 
 Prerequisites: Ruby `>= 3.4`, `git`, and `gem` in your PATH. `gh` (GitHub CLI) is recommended for full review governance features.

data/RELEASE.md

@@ -5,6 +5,20 @@ 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.21.0
+
+### 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.
+  - **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.
+
+### UX improvement
+
+- Agents that forget to use `carson deliver` are caught at push time or tool-call time with a clear message: what happened, why, and what to use instead. Born from scar: a preflight agent used raw `git push github main` and `gh pr create` in a governed repo, wasting work and requiring manual recovery (2026-03-09).
+
 ## 3.20.0
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-3.20.0
+3.21.0

data/exe/carson

@@ -5,9 +5,9 @@ $LOAD_PATH.unshift( File.expand_path( "../lib", __dir__ ) )
 require "carson"
 
 exit Carson::CLI.start(
-	argv: ARGV.dup,
+	arguments: ARGV.dup,
 	repo_root: Dir.pwd,
 	tool_root: File.expand_path( "..", __dir__ ),
-	out: $stdout,
-	err: $stderr
+	output: $stdout,
+	error: $stderr
 )

data/hooks/command-guard

@@ -0,0 +1,56 @@
+#!/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.
+#
+# Claude Code sends JSON on stdin: {"tool_name": "Bash", "tool_input": {"command": "..."}}
+# To block: print reason to stderr, exit 2.
+# To allow: exit 0.
+#
+# Registration in ~/.claude/settings.json:
+#   "PreToolUse": [
+#     {
+#       "matcher": "Bash",
+#       "hooks": [
+#         {
+#           "type": "command",
+#           "command": "~/.carson/hooks/command-guard"
+#         }
+#       ]
+#     }
+#   ]
+set -euo pipefail
+
+# Read the tool call JSON from stdin.
+input="$(cat)"
+
+# Only inspect Bash tool calls.
+tool_name="$(echo "$input" | jq -r '.tool_name // empty' 2>/dev/null)"
+[ "$tool_name" = "Bash" ] || exit 0
+
+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.
+guarded_pattern='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
+
+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
+	exit 0
+fi
+
+# This is a raw gh pr command in a governed repo — block it.
+echo "BLOCKED: raw \`gh pr create/merge\` in a Carson-governed repository." >&2
+echo "Use \`carson deliver\` instead — it handles push, PR, and merge with safety guards." >&2
+exit 2

data/hooks/pre-push

@@ -1,23 +1,59 @@
 #!/usr/bin/env bash
+# Carson pre-push hook — enforces push policy in governed repositories.
+#
+# Guards:
+#   1. Blocks direct push to main/master refs.
+#   2. Blocks raw git push in governed repos — agents must use `carson deliver`.
+#      Carson sets CARSON_PUSH=1 internally so its own pushes pass through.
+#
+# Bypass (emergency only): git push --no-verify
 set -euo pipefail
 
 hooks_dir="$(cd "$(dirname "$0")" && pwd)"
 style="$(cat "$hooks_dir/workflow_style" 2>/dev/null || echo "branch")"
 [ "$style" = "trunk" ] && exit 0
 
+# --- Guard 1: block pushes to main/master refs ---
+
 remote_name="${1:-unknown}"
 remote_url="${2:-unknown}"
 has_commit_push=false
 while read -r local_ref local_sha remote_ref remote_sha; do
 	case "$remote_ref" in
 		refs/heads/main|refs/heads/master)
-			echo "Carson policy: direct push to ${remote_ref#refs/heads/} is blocked on remote ${remote_name} (${remote_url}). Use a pull request." >&2
+			echo "BLOCKED: direct push to ${remote_ref#refs/heads/} is not allowed." >&2
+			echo "Use \`carson deliver\` instead — it handles push, PR, and merge with safety guards." >&2
+			echo "Bypass (emergency only): git push --no-verify" >&2
 			exit 1
 			;;
 	esac
 	[[ "$local_sha" != "0000000000000000000000000000000000000000" ]] && has_commit_push=true
 done
 
+# --- Guard 2: block raw git push in governed repos ---
+# Carson sets CARSON_PUSH=1 when pushing internally via `deliver`.
+# If the variable is absent, this is a raw git push from an agent or human.
+
+if [[ -z "${CARSON_PUSH:-}" ]]; then
+	config_file="${HOME}/.carson/config.json"
+	if [[ -f "$config_file" ]]; then
+		repo_root="$(git rev-parse --show-toplevel 2>/dev/null || echo "")"
+		if [[ -n "$repo_root" ]]; then
+			# Check if this repo appears in govern.repos.
+			# Uses a simple grep against the JSON — no jq dependency required.
+			normalised="$(cd "$repo_root" && pwd -P)"
+			if grep -qF "\"$normalised\"" "$config_file" 2>/dev/null; then
+				echo "BLOCKED: raw \`git push\` in a Carson-governed repository." >&2
+				echo "Use \`carson deliver\` instead — it handles push, PR, and merge with safety guards." >&2
+				echo "Bypass (emergency only): git push --no-verify" >&2
+				exit 1
+			fi
+		fi
+	fi
+fi
+
+# --- Template sync on push ---
+
 if $has_commit_push; then
 	if [[ -n "${CARSON_BIN:-}" ]]; then
 		ruby "$CARSON_BIN" template apply --push-prep || exit 1

data/lib/carson/adapters/agent.rb

@@ -1,3 +1,4 @@
+# Defines the WorkOrder and Result data structures for agent dispatch.
 module Carson
 	module Adapters
 		module Agent

data/lib/carson/adapters/claude.rb

@@ -1,8 +1,10 @@
+# Dispatches coding work to the Claude Code CLI and parses its output.
 require "open3"
 require "json"
 
 module Carson
 	module Adapters
+		# Adapter for dispatching work to Claude Code.
 		class Claude
 			include Prompt
 

data/lib/carson/adapters/codex.rb

@@ -1,8 +1,10 @@
+# Dispatches coding work to the OpenAI Codex CLI and parses its output.
 require "open3"
 require "json"
 
 module Carson
 	module Adapters
+		# Adapter for dispatching work to OpenAI Codex.
 		class Codex
 			include Prompt
 

data/lib/carson/adapters/git.rb

@@ -1,7 +1,9 @@
+# Executes git commands via Open3 and returns structured output.
 require "open3"
 
 module Carson
 	module Adapters
+		# Thin wrapper around the git CLI. Runs commands via Open3.
 		class Git
 			def initialize( repo_root: )
 				@repo_root = repo_root

data/lib/carson/adapters/github.rb

@@ -1,7 +1,9 @@
+# Executes gh CLI commands via Open3 for GitHub API access.
 require "open3"
 
 module Carson
 	module Adapters
+		# Thin wrapper around the gh CLI for GitHub API access.
 		class GitHub
 			def initialize( repo_root: )
 				@repo_root = repo_root

data/lib/carson/adapters/prompt.rb

@@ -1,5 +1,7 @@
+# Builds structured prompts for dispatching work orders to coding agents.
 module Carson
 	module Adapters
+		# Builds structured prompts for coding agent dispatch.
 		module Prompt
 		private