carson 3.20.0 → 3.21.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e7fdc44d330fd415b8f6d9ee479d5256d6fc860e5d63c7c9287f28ebbdb2ba4
-  data.tar.gz: 19056bd376bcab3b7077e38ba4e42f2b9f5a3ffbf2c8027f0aa6626bb70587fb
+  metadata.gz: 6e487779056ecbcf22d7aca1527c557051cd2ce94b31e030a515ffedcb8bbce5
+  data.tar.gz: 9cc271426a2c241d855f9a11d7b583e1bb0db2a8041e2972e8bdb3b7df4b55a7
 SHA512:
-  metadata.gz: 13f0d5ac83272711329d435a935dd940afc461c5c3b10e20d23842492e8e53f7032cf34a8b027d70db80563af148cda5f99c2c8e7ec4025b94f4d72609ea9d1d
-  data.tar.gz: b1903c6a8f8682adc7b942e49b553579d014d56c0bb65587465568119d41583a14e0cb4a7b00bc61b9165fac79094567395dbf2b39191e3c9d673dc0750dc4f5
+  metadata.gz: 1e9085ad4e193f0b0c09b5ea890bbbc708194c0ccaf9b5dea96e4daafa5b074f08790ac994d44fbcee3767641eb519cc97d4b05ae65bc29532a2c695a752807c
+  data.tar.gz: 2bc2779bde9dabc17a79c2e0668f370a8f8aecd9ee41bbb56c51ebedf394d1546e029f611a7ffc2072e496a4d01ade6e390157ca4b4468bdf220a1ac4bb99393

data/LICENSE

@@ -1,21 +1,91 @@
-MIT License
-
-Copyright (c) 2026 Hailei Wang (WHL) <wanghailei@gmail.com>
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+Required Notice: Copyright (c) 2026 Hailei Wang (WHL) <wanghailei@gmail.com>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to Distribution License and make changes or new works based on the software according to Changes and New Works License.
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by Changes and New Works License.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any product that competes with the software or any product the licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality through different kinds of interfaces or for different technical platforms. Applications can compete with services, libraries with plugins, frameworks with development tools, and so on, even if they're written in different programming languages or for different computer architectures. Goods and services compete even when provided free of charge. If you market a product as a practical substitute for the software or another product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does not compete, but the licensor or any of its affiliates brings your product into competition by providing a new version of the software or another product using the software, you may continue using versions of the software available under these terms beforehand to provide your competing product, but not any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product or service that the licensor or any of its affiliates has stopped providing, unless the licensor includes a plain-text line beginning with `Licensor Line of Business:` with the software that mentions that line of business. For example:
+
+> Licensor Line of Business: YoyodyneCMS Content Management System (http://example.com/cms)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of business developing the software or using the software to provide a product, the buyer can also enforce Noncompete for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
+
+## No Liability
+
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+A **product** can be a good or service, or a combination of them.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all its affiliates.
+
+**Affiliates** means the other organizations than an organization has control over, is under the control of, or is under common control with.
+
+**Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

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,26 @@ 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.1
+
+### What changed
+
+- **Command guard false-positive fix** — the `command-guard` regex now matches `gh pr create/merge` only at command position (start of line or after `&&`, `||`, `;`, `|`). Previously it matched inside string arguments, blocking legitimate commands like `git commit -m 'Document gh pr create hook'`.
+
+## 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.1

data/carson.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
 	spec.summary = "Autonomous repository governance — you write the code, Carson manages everything else."
 	spec.description = "Carson is a governance runtime that lives outside the repositories it governs — no Carson-owned artefacts in your repo. On every commit, managed hooks enforce centralised lint policy and review gates. At portfolio level, carson govern triages every open PR across your registered repositories: merge what's ready, dispatch coding agents to fix what's failing, escalate what needs human judgement. One command, all your projects, unmanned."
 	spec.homepage = "https://github.com/wanghailei/carson"
-	spec.license = "MIT"
+	spec.license = "PolyForm-Shield-1.0.0"
 	spec.required_ruby_version = ">= 3.4"
 	spec.metadata = {
 		"source_code_uri" => "https://github.com/wanghailei/carson",

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,58 @@
+#!/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.
+# 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
+
+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