carson 3.21.1 → 3.22.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e487779056ecbcf22d7aca1527c557051cd2ce94b31e030a515ffedcb8bbce5
-  data.tar.gz: 9cc271426a2c241d855f9a11d7b583e1bb0db2a8041e2972e8bdb3b7df4b55a7
+  metadata.gz: 0e8e1399ec6024845aecc0b88bd5549a2dc2c4f9a4b8a9852a725a718eb837d9
+  data.tar.gz: cc4e9c3b9fe55e238c394d2056a2fe25afe100bdf1191a7b58cfd9b9f05e0fc6
 SHA512:
-  metadata.gz: 1e9085ad4e193f0b0c09b5ea890bbbc708194c0ccaf9b5dea96e4daafa5b074f08790ac994d44fbcee3767641eb519cc97d4b05ae65bc29532a2c695a752807c
-  data.tar.gz: 2bc2779bde9dabc17a79c2e0668f370a8f8aecd9ee41bbb56c51ebedf394d1546e029f611a7ffc2072e496a4d01ade6e390157ca4b4468bdf220a1ac4bb99393
+  metadata.gz: 63148df8fdf6cd881b4a63a9c3f330221a60481943e2ec97647242a791b0b672d86cc557fd38062e003d531c8ca2007390d0312731595cb24d115f806a73a6e0
+  data.tar.gz: 74df1a6e073a1c7d4cce7b227344295146d0a3d69c4941b3befe129660ab3eb50ccbbe5465cc35fbabaa7d56f6912ae2f9b6a38f6347e1b1ace2f9eae2e797ed

data/API.md

@@ -84,12 +84,7 @@ Blocked Carson artefacts in host repositories:
 - `.tools/carson/*`
 
 Allowed Carson-managed persistence in host repositories:
-- `.github/carson.md` — governance baseline (source of truth)
-- `.github/copilot-instructions.md` — agent discovery pointer for Copilot
-- `.github/CLAUDE.md` — agent discovery pointer for Claude Code
-- `.github/AGENTS.md` — agent discovery pointer for Codex
-- `.github/pull_request_template.md` — PR template
-- Any file discovered from `template.canonical` — user's canonical `.github/` files
+- Any file discovered from `lint.canonical` — user's canonical GitHub and lint-policy files
 
 ## Configuration interface
 
@@ -146,14 +141,14 @@ Environment overrides:
 
 ```json
 {
-  "template": {
+  "lint": {
     "canonical": "~/AI/CODING/LINT"
   }
 }
 ```
 
-`template` semantics:
-- `canonical`: path to a directory of canonical `.github/` files. Carson discovers files in this directory and syncs them to governed repos alongside its own governance files. The directory mirrors `.github/` structure — `workflows/lint.yml` deploys to `.github/workflows/lint.yml`. Default: `nil` (no canonical files).
+`lint` semantics:
+- `canonical`: path to a directory of canonical GitHub and lint-policy files. Carson discovers files in this directory and syncs them to governed repos. Explicit GitHub paths stay under `.github/` (`workflows/lint.yml` → `.github/workflows/lint.yml`, `.github/labeler.yml` → `.github/labeler.yml`); flat policy files default to `.github/linters/` (`rubocop.yml` → `.github/linters/rubocop.yml`). Legacy root lint configs become stale and are removed on apply. Default: `nil` (no canonical files). The deprecated alias `template.canonical` is still accepted when loading config.
 
 ## Output interface
 

data/MANUAL.md

@@ -39,7 +39,7 @@ On first run (no `~/.carson/config.json` exists), `onboard` launches `carson set
 - Hook installation under `~/.carson/hooks/<version>/`.
 - Repository `core.hooksPath` alignment to Carson global hooks.
 - Commit-time governance gate via managed `pre-commit` hook.
-- Managed `.github/*` template synchronisation.
+- Canonical `.github/*` template synchronisation (when `lint.canonical` is configured).
 - Initial governance audit.
 
 ### Reconfigure later
@@ -52,7 +52,7 @@ Re-run the interactive setup quiz to change your remote, main branch, workflow s
 
 ### Commit generated files
 
-After `onboard`, commit the generated `.github/*` changes in your repository. From this point the repository is governed.
+After `onboard`, commit any `.github/*` changes in your repository. From this point the repository is governed.
 
 ## CI Setup
 
@@ -82,37 +82,70 @@ Notes:
 
 ### Canonical Templates
 
-Carson manages 5 governance files (carson.md, CLAUDE.md, AGENTS.md, copilot-instructions.md, pull_request_template.md). Beyond those, you can tell Carson about your own canonical `.github/` files — CI workflows, linter configs, labeller rules, anything that belongs in `.github/`.
+Carson has no built-in template files. Instead, you tell Carson about your own canonical GitHub and lint-policy files via `lint.canonical`.
 
-Set `template.canonical` in `~/.carson/config.json`:
+Set `lint.canonical` in `~/.carson/config.json`:
 
 ```json
 {
-  "template": {
+  "lint": {
     "canonical": "~/AI/CODING/LINT"
   }
 }
 ```
 
-That directory mirrors the `.github/` structure:
+Flat lint-policy directories default to `.github/linters/`, while explicit GitHub paths stay under `.github/`:
 
 ```
 ~/AI/CODING/LINT/
+├── rubocop.yml           → deployed to .github/linters/rubocop.yml
+├── ruff.toml             → deployed to .github/linters/ruff.toml
 ├── workflows/
 │   └── lint.yml          → deployed to .github/workflows/lint.yml
-├── .mega-linter.yml      → deployed to .github/.mega-linter.yml
-└── labeler.yml           → deployed to .github/labeler.yml
+└── .github/
+    └── labeler.yml       → deployed to .github/labeler.yml
 ```
 
-Carson discovers files in this directory and syncs them to governed repos alongside its own governance files. `carson template check` detects drift, `carson template apply` writes them, and `carson refresh` propagates them to the remote.
+Carson discovers files in this directory and syncs them to governed repos. Root files that are not recognised GitHub artefacts are treated as lint policy and written under `.github/linters/`; legacy root lint configs become stale and are removed on apply. `carson template check` detects drift, `carson template apply` writes them, and `carson refresh` propagates them to the remote. Carson still reads the deprecated `template.canonical` key for backwards compatibility, but new setup writes `lint.canonical`.
 
 **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.
 
+## Operating Strategies
+
+These strategies are the audit lens for Carson. If behaviour departs from them, either the product model or the implementation needs attention.
+
+### 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.
+- **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.
+
+### Repo Governor
+
+- **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.
+- **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.
+
+### Safety Strategies
+
+- **Process-aware worktree removal** — Carson checks whether the current shell or another process has its CWD inside a worktree before attempting removal.
+- **Stale worktree sweep** — Carson removes worktrees whose content has already been absorbed into `main` so dead state does not block later maintenance.
+- **Protected branch preservation** — Carson never deletes protected branches and does not prune branches that are still held by active worktrees.
+- **Hook bypass only for managed operations** — Carson uses controlled bypasses such as `--no-verify` only for its own managed flows, not as a general escape hatch.
+- **Self-diagnosing errors** — blocks and failures must explain the condition and prescribe the exact recovery command.
+- **Self-configuring guardrails** — running Carson should install and refresh its own safeguards rather than expecting manual post-install housekeeping.
+
 ## 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:
+**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:
 
 ```bash
 carson worktree create my-feature
@@ -121,7 +154,7 @@ 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+):
+**3. Deliver and merge** — use Carson's landing path for the repo authority. In remote authority that means push, PR, and merge; in local authority that means integrate into local `main` and back it up by pushing `main`. Managed template drift is corrected and committed automatically before push (3.22.1+). After delivery, Carson prints the exact next command:
 
 ```bash
 carson deliver --merge
@@ -152,7 +185,7 @@ Claude Code has a built-in `EnterWorktree` tool. Both create a git worktree unde
 
 | Concern | EnterWorktree | Carson |
 |---|---|---|
-| Auto-sync main before branching | No — branches from current HEAD, which may be stale | Yes — `git pull --ff-only` before branch creation |
+| Governed baseline before branching | No — branches from current HEAD, which may be stale | Yes — branches from the repo's governed baseline rather than the caller's current HEAD |
 | CWD guard on removal | No | Yes — blocks if shell is inside the worktree |
 | Unpushed-commits guard | No | Yes — blocks if work hasn't been pushed |
 | Content-aware squash/rebase detection | No | Yes — compares tree content, not SHAs |
@@ -362,22 +395,6 @@ How much Carson prints.
 - Default: **concise**. A healthy audit prints one line. Problems print actionable summaries with cause and fix.
 - `--verbose` restores full diagnostic key-value output for debugging.
 
-## Agent Discovery
-
-Carson writes managed files that help interactive agents (Claude Code, Codex, Copilot) discover the governance system when they work in a governed repository.
-
-**How it works:**
-
-- `.github/AGENTS.md` — full governance baseline; read by Codex and other agents. Points to `carson.md`.
-- `.github/CLAUDE.md` — read by Claude Code at session start. Points to `AGENTS.md`.
-- `.github/copilot-instructions.md` — read by GitHub Copilot. Points to `AGENTS.md`.
-
-Each agent reads its own expected filename and follows the reference to the shared baseline. One file to maintain, zero drift across agents.
-
-All four files are managed templates — `carson template check` detects drift, `carson template apply` writes them, and `carson offboard` removes them.
-
-**Why this matters:** without discovery, agents working in governed repos hit Carson's hooks blindly and don't understand the governance contract. With discovery, agents know to run `carson audit` before committing, `carson review gate` before recommending a merge, and to respect protected refs.
-
 ## Configuration
 
 Default global config path: `~/.carson/config.json`.

data/README.md

@@ -2,97 +2,92 @@
 
 # ⧓ Carson
 
-*Carson at your service.*
+Named after the butler of Downton Abbey, Carson is a strategic governor for multiple agents working in one repo.
 
-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.
+Carson is deterministic infrastructure for concurrent agent work. It governs how work starts, how it rejoins shared truth, and how the repo is cleaned up afterwards so agents can code without trampling each other. The agents provide the intelligence; Carson provides the discipline.
+
+Carson was built in real work. Its strategies come from scars: more than ten agents running across multiple projects at once, with each repeated failure turned into a rule, guardrail, or recovery path.
 
 ## 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.
+When several agents work on one repository, plain Git leaves too much to habit. Branches start from different bases, work lands back on `main` through inconsistent paths, old worktrees linger, and one clean-up step can disrupt another session.
 
-Carson exists so you can focus on what matters — building — while governance runs itself.
+Carson solves that single-repo concurrency problem first, then extends the same discipline across multiple repositories.
 
 ## 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:
+Carson lives on your workstation and in CI, never inside the repositories it governs. Two roles, one tool:
 
-**Per-commit governance** — Carson gates merges on unresolved review comments, synchronises templates, and keeps your local branches clean. Every commit triggers `carson audit` through managed hooks; the same checks run in GitHub Actions.
+**Git strategist** — Carson decides how new work begins, which base it uses, how it returns to shared truth, and how cleanup happens safely.
 
-**Portfolio-level autonomy** — `carson govern` is a triage loop that scans your registered repositories, classifies every open PR, and acts: merge what's ready, dispatch coding agents (Codex or Claude) to fix what's failing, and escalate what needs human judgement. One command, all your projects, unmanned.
+**Repo governor** — Carson enforces the repo's operating contract: worktree-first flow, Carson-owned delivery operations, policy checks, and exact recovery guidance when work cannot proceed.
 
 ```
   ~/.carson/                     ← Carson lives here, never inside your repos
        │
-       ├─ hooks ──────────────►  commit gates      (every governed repo)
-       └─ govern ─────────────►  PR triage → merge | dispatch agent | escalate
+       ├─ hooks ──────────────►  commit gates and command guards
+       ├─ worktree flow ──────►  create → work → deliver → clean up
+       └─ portfolio layer ────►  status --all | refresh --all | govern
 ```
 
-This separation is Carson's defining trait — the **outsider boundary**: no Carson scripts, config files, or governance payloads are ever placed inside a governed repository.
-
-**Agent workspace management** — `carson worktree create` and `carson worktree remove` give coding agents safe, isolated workspaces. Unlike Claude Code's built-in `EnterWorktree`, Carson auto-syncs main before branching, guards against removing worktrees with unpushed work or an active shell inside, detects squash/rebase merges so removal doesn't falsely block, and cleans up the local and remote branch in one step. The two tools are complementary — see `MANUAL.md § Carson vs Claude Code EnterWorktree` for the full comparison.
-
-### The Governance Loop
+The outsider boundary still matters: Carson governs repositories without becoming a runtime dependency inside them.
 
-Carson orchestrates a closed governance loop across two layers:
+## Two Authorities
 
-1. **CI enforcement** — Carson's `audit` gates on CI check status reported by GitHub. The actual CI runs are delegated to GitHub Actions.
-2. **Autonomous triage** — `carson govern` reads CI status, review disposition, and audit health for every open PR. Ready PRs are merged. Failing PRs get a coding agent (Codex or Claude) dispatched to fix them. Stuck PRs are escalated.
+Each governed repo chooses one integration authority.
 
-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.
+**Remote** — remote `main` is the integration authority. Agents still work in local worktrees, but completed work rejoins through remote `main`.
 
-### Principles
+**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.
 
-Carson is opinionated about governance. These are non-negotiable principles, not configurable defaults:
+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.
 
-- **Outsider boundary** — Carson lives outside your repo, never inside. No Carson-owned artefacts in your repository. Offboarding leaves no trace.
-- **Active review** — undisposed reviewer findings block merge. Feedback must be acknowledged, not buried.
-- **Self-diagnosing output** — every warning and error names what went wrong, why, and what to do next. If you have to read source code to understand a message, that message is a bug.
-- **Transparent governance** — Carson prepares everything for merge but never oversteps. It does not make decisions for you without telling you.
+## Principles
 
-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.
+- **Worktree-first** — substantive work happens in worktrees, not on `main`.
+- **Carson-owned operations** — Carson owns worktree and delivery operations in governed repositories.
+- **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.
 
 ## Quickstart
 
-Prerequisites: Ruby `>= 3.4`, `git`, and `gem` in your PATH. `gh` (GitHub CLI) is recommended for full review governance features.
+Prerequisites: Ruby `>= 3.4`, `git`, and `gem` in your `PATH`. `gh` (GitHub CLI) is recommended for review governance features.
 
 ```bash
 gem install carson
-```
+carson onboard your/repo/path
 
-**Onboard a repository:**
+# Optional: switch from the default remote authority
+carson repo authority local
 
-```bash
-carson onboard /path/to/your-repo
-```
+carson worktree create your-worktree
+cd your/repo/path/.claude/worktrees/your-worktree
 
-On first run, Carson walks you through setup — remote, main branch, workflow style, merge method — then installs hooks, syncs templates, and runs an initial audit.
+# work, test, commit
+carson deliver --merge
 
-After `carson onboard`, your repository has:
-- Git hooks that run `carson audit` on every commit.
-- Managed `.github/*` templates synchronised from Carson.
-- An initial governance audit report.
+cd your/repo/path
+carson worktree remove your-worktree
+carson prune
+```
 
-Commit the generated `.github/*` changes, and the repository is governed.
+By default, repositories onboard as `remote`. In `remote`, `deliver` lands through remote `main`. In `local`, the same loop lands on local `main` and then pushes `main` to the remote as backup.
 
-**Govern your portfolio.** Once repositories are onboarded, `carson govern` is your recurring command. Run it whenever you want Carson to triage open PRs, enforce review policy, and dispatch coding agents across all governed repos:
+## Portfolio Layer
+
+Single-repo depth comes first. Once multiple repositories are onboarded, the same discipline scales out across them:
 
 ```bash
-carson govern --dry-run     # preview what Carson would do, change nothing
-carson govern               # triage PRs, merge ready ones, dispatch agents
-carson govern --loop 300    # run continuously, cycling every 5 minutes
+carson status --all
+carson refresh --all
+carson govern --dry-run
 ```
 
+`carson govern` is the portfolio layer. It triages open PRs, merges what is ready, dispatches agents to fix what is failing, and reports what needs human judgement.
+
 ## Where to Read Next
 
-- **MANUAL.md** — installation, first-time setup, CI configuration, daily operations, full command reference, troubleshooting.
+- **MANUAL.md** — installation, setup, operating strategies, daily workflows, command reference, troubleshooting.
 - **API.md** — formal interface contract: commands, exit codes, configuration schema.
 
 ## Support

data/RELEASE.md

@@ -5,6 +5,29 @@ 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.22.1
+
+### What changed
+
+- **Template sync moved into deliver** — `deliver!` now runs `template_apply!` before push, restoring template drift detection that was lost when 3.21.0 added `--no-verify` to `push_branch!`. The pre-push hook's `template apply --push-prep` block was silently skipped; managed files with drifted content could reach the remote undetected. Canonical content is now written and committed automatically before the push.
+
+### No migration required
+
+## 3.22.0
+
+### What changed
+
+- **Command-guard auto-install at CLI startup** — Carson now installs the command-guard hook automatically when any CLI command runs, removing the need for a manual `carson refresh` after install. The guard is installed once and skipped on subsequent invocations.
+- **Stale worktree sweep before portfolio safety check** — `refresh --all` now sweeps stale worktrees before checking repo safety, preventing false "active worktree" skips for worktrees whose branches have already been merged.
+- **Nested config path fix for merge method** — `govern.merge.method` is now read from the correct nested config path instead of the top-level key, fixing repos where the merge method setting was silently ignored.
+- **Deliver proceeds when no CI checks configured** — `deliver --merge` no longer blocks on repos with no CI checks. Previously it waited indefinitely for checks that would never arrive.
+- **Rebase-merge orphan branch pruning** — `prune` now detects branches absorbed into main via rebase merge (tip commit reachable from main) and cleans them up, not just squash-merged branches.
+- **Pluralisation fix** — corrected "branchs" → "branches" in prune and status output.
+
+### UX improvement
+
+- Carson is now fully self-configuring: installing the gem and running any command sets up all safety guards automatically. Batch operations on portfolios no longer false-skip repos with stale worktrees. Repos using rebase merge keep their branch list clean without manual intervention.
+
 ## 3.21.1
 
 ### What changed
@@ -16,7 +39,7 @@ Release-note scope rule:
 ### 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.
+  - **Pre-push hook** — blocks raw `git push` unconditionally in governed repos. Carson uses `--no-verify` internally to skip its own hook. *(Side effect: `--no-verify` also skips the hook's `template apply --push-prep` block — template sync moved into `deliver!` in a later release to restore coverage.)*
   - **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.

data/SKILL.md

@@ -1,6 +1,6 @@
 # Carson Skill
 
-You are working in a repository governed by Carson — a deterministic governance runtime. Carson handles git hooks, PR triage, agent dispatch, merge, and cleanup. You provide the intelligence; Carson provides the infrastructure.
+You are working in a repository governed by Carson — an autonomous git strategist and repositories governor. Carson handles git hooks, PR triage, agent dispatch, merge, and cleanup. You provide the intelligence; Carson provides the infrastructure.
 
 ## When to use Carson commands
 

data/VERSION

@@ -1 +1 @@
-3.21.1
+3.22.1

data/carson.gemspec

@@ -7,8 +7,8 @@ Gem::Specification.new do |spec|
 	spec.version = Carson::VERSION
 	spec.authors = [ "Hailei Wang", "Codex", "Claude Code" ]
 	spec.email = [ "wanghailei@users.noreply.github.com" ]
-	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.summary = "Autonomous git strategist and repositories governor — you write the code, Carson manages everything else."
+	spec.description = "Carson is an autonomous git strategist and repositories governor that lives outside the repositories it governs — no Carson-owned artefacts in your repo. As strategist, Carson knows when to branch, how to isolate concurrent work, and how to recover from failures. As governor, it enforces review gates, manages templates, and triages every open PR across your portfolio: 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 = "PolyForm-Shield-1.0.0"
 	spec.required_ruby_version = ">= 3.4"
@@ -29,8 +29,6 @@ Gem::Specification.new do |spec|
 	spec.executables = [ "carson" ]
 	spec.require_paths = [ "lib" ]
 	spec.files = Dir.glob( "{lib,exe,templates,hooks}/**/*", File::FNM_DOTMATCH ).select { |path| File.file?( path ) } + [
-		".github/copilot-instructions.md",
-		".github/pull_request_template.md",
 		".github/workflows/carson_policy.yml",
 		"README.md",
 		"MANUAL.md",

data/hooks/command-guard

@@ -53,6 +53,6 @@ if ! grep -qF "\"$normalised\"" "$config_file" 2>/dev/null; then
 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 "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

data/hooks/pre-push

@@ -4,9 +4,9 @@
 # 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.
+#      Carson bypasses via --no-verify internally. No env-var signal to spoof.
 #
-# Bypass (emergency only): git push --no-verify
+# Bypass: git push --no-verify
 set -euo pipefail
 
 hooks_dir="$(cd "$(dirname "$0")" && pwd)"
@@ -21,9 +21,9 @@ 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 "BLOCKED: direct push to ${remote_ref#refs/heads/} is not allowed." >&2
+			echo "Pushes to ${remote_ref#refs/heads/} go through PRs, not direct push." >&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
+			echo "Bypass: git push --no-verify" >&2
 			exit 1
 			;;
 	esac
@@ -31,23 +31,20 @@ while read -r local_ref local_sha remote_ref remote_sha; do
 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.
+# All pushes in governed repos are blocked unconditionally.
+# Carson bypasses this hook via --no-verify when pushing internally.
+# No env-var bypass — cannot be spoofed.
 
-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
+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
+		normalised="$(cd "$repo_root" && pwd -P)"
+		if grep -qF "\"$normalised\"" "$config_file" 2>/dev/null; then
+			echo "This repo is Carson-governed — use \`carson deliver\` instead of raw \`git push\`." >&2
+			echo "Use \`carson deliver\` instead — it handles push, PR, and merge with safety guards." >&2
+			echo "Bypass: git push --no-verify" >&2
+			exit 1
 		fi
 	fi
 fi