carson 2.13.1 → 2.13.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7fde15079ed380bb8c6e4d476fb8157dd7980ea6a250e06706188a645c1d160
-  data.tar.gz: 85a76cdb10a52573ba463a884079178e2b69befe21b8b377bb425f620057bd65
+  metadata.gz: 8d19271a17424021f6b4ef1ceabe73275feb47c54965175fbd5fbd1a2b6f869b
+  data.tar.gz: 8011d1e680ba9331e99bd8254b0b07605f64ed1856baa6a62b53ec1f6eb98c7c
 SHA512:
-  metadata.gz: 910cfd8d4ee3095b3ea559ba66bcd372d764043d02131f38d2d75071542aa04e1ea7cf5bdf10ab1aabd792f8ff21762ea31063720c23c719cc361d4313ea38fd
-  data.tar.gz: 236417f25de6aba2640a3ec992c5f756851b931f961f213408f57533533403f20d011cf4169cb8384ed980d58100456e49ea9209ed08fc2bb87a2d9729fcd9e4
+  metadata.gz: 51be2370d394a2b83169b5ca543339a8949ec0a8cb969430e934d7a22977e3e085997c7d6f89006a7d128abb9a8f426c5f22327555a6d26f85c89c186eb25dc9
+  data.tar.gz: 9bc89f7a0f84f70d21c0a38ec5cca6b84d961ebab815bfb826f86a1316139915093f378fbbf8d52f9696d9445bacbe3d5677b3c78e14e6a9542b334128adfbb3

data/API.md

@@ -99,6 +99,39 @@ Environment overrides:
 - `CARSON_WORKFLOW_STYLE`
 - `CARSON_RUBY_INDENTATION`
 - `CARSON_LINT_POLICY_SOURCE`
+- `CARSON_GOVERN_REPOS`
+- `CARSON_GOVERN_MERGE_AUTHORITY`
+- `CARSON_GOVERN_MERGE_METHOD`
+- `CARSON_GOVERN_AGENT_PROVIDER`
+- `CARSON_GOVERN_CHECK_WAIT`
+
+`govern` schema:
+
+```json
+{
+  "govern": {
+    "repos": ["~/Dev/project-a", "~/Dev/project-b"],
+    "agent": {
+      "provider": "auto",
+      "codex": {},
+      "claude": {}
+    },
+    "check_wait": 30,
+    "merge": {
+      "authority": false,
+      "method": "squash"
+    }
+  }
+}
+```
+
+`govern` semantics:
+- `repos`: list of local repo paths to govern (empty = current repo only).
+- `agent.provider`: `"auto"`, `"codex"`, or `"claude"`.
+- `agent.codex` / `agent.claude`: provider-specific options (reserved).
+- `check_wait`: seconds to wait for CI checks before classifying (default: `30`).
+- `merge.authority`: `false` (default) — Carson does not merge until explicitly enabled.
+- `merge.method`: `"squash"` (default), `"merge"`, or `"rebase"`.
 
 `lint` schema:
 

data/README.md

@@ -2,11 +2,15 @@
 
 # ⧓ Carson
 
+*Carson at your service.*
+
 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
+## The Problem to Solve
+
+Managing a growing portfolio of repositories is rewarding work — but the operational overhead scales faster than the code itself. Lint configs drift between repos, 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.
 
-If you govern more than a handful of repositories, you know the pattern: lint configs drift between repos, PR templates go stale, reviewer feedback gets quietly ignored, and what passes on a developer's laptop fails in CI. Across a portfolio of projects with coding agents producing many PRs, you become the bottleneck — manually checking results, dispatching fixes, clicking merge, and cleaning up.
+Carson exists so you can focus on what matters — building — while governance runs itself.
 
 ## How Carson Works
 
@@ -14,7 +18,7 @@ Carson is an autonomous governance runtime that lives on your workstation and in
 
 **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. Lint execution is handled entirely by MegaLinter in CI and by the developer's own local tooling — Carson distributes the shared lint configuration but does not run linters itself.
 
-**Portfolio-level autonomy** — `carson govern` is a scheduled triage loop that scans all your 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.
+**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.
 
 ```
 ┌──────────────────────────────────────────────┐
@@ -59,61 +63,7 @@ Carson is opinionated about governance. These are non-negotiable principles, not
 - **Self-diagnosing output** — every message names the cause and the fix. If you need to debug Carson's output, the output failed.
 - **Transparent governance** — Carson prepares everything for merge but never oversteps. It does not make decisions for you without telling you.
 
-Everything else — workflow style, merge method, remote name, main branch — is a configurable default chosen during `carson setup`. See `MANUAL.md` for the full list of defaults and why each was chosen.
-
-The data flow:
-
-1. You maintain a **policy source** — a directory or git repository containing your lint config files (e.g. `.rubocop.yml`, `biome.json`, `ruff.toml`). `carson lint policy --source <repo>` copies these into each governed repo's `.github/linters/`, where MegaLinter auto-discovers them.
-2. `carson onboard` installs git hooks, synchronises `.github/*` templates (including a MegaLinter CI workflow), and runs a first governance audit on a host repository.
-3. From that point, every commit triggers `carson audit` through the managed `pre-commit` hook. The same `carson audit` runs in GitHub Actions. If it passes locally, it passes in CI.
-4. `carson review gate` enforces review accountability: it blocks merge until every actionable reviewer comment has been formally acknowledged by the PR author through a **disposition comment**.
-5. `carson govern` triages all open PRs across your portfolio. Ready PRs are merged and housekept. Failing PRs get a coding agent dispatched to fix them. Stuck PRs are escalated for your attention.
-
-## Commands at a Glance
-
-**Govern** — autonomous portfolio management:
-
-| Command | What it does |
-|---|---|
-| `carson govern` | Triage all open PRs: merge ready ones, dispatch agents for failures, escalate the rest. |
-| `carson govern --dry-run` | Show what Carson would do without taking action. |
-| `carson govern --loop SECONDS` | Run the govern cycle continuously, sleeping SECONDS between cycles. |
-| `carson housekeep` | Sync main + prune stale branches (also runs automatically after govern merges). |
-
-**Setup** — run once per machine or per repository:
-
-| Command | What it does |
-|---|---|
-| `carson lint policy --source <repo>` | Distribute lint configs from policy source into `.github/linters/`. |
-| `carson onboard` | One-command baseline: hooks + templates + first audit. |
-| `carson prepare` | Install or refresh Carson-managed global hooks. |
-| `carson refresh` | Re-apply hooks, templates, and audit after upgrading Carson. |
-| `carson refresh --all` | Refresh all governed repositories at once. |
-| `carson offboard` | Remove Carson from a repository. |
-
-**Daily** — regular development workflow:
-
-| Command | What it does |
-|---|---|
-| `carson audit` | Full governance check (also runs automatically on every commit). |
-| `carson sync` | Fast-forward local `main` from remote. |
-| `carson prune` | Remove stale local branches whose upstream is gone. |
-| `carson template check` | Detect drift between managed and host `.github/*` files. |
-| `carson template apply` | Repair drifted `.github/*` files. |
-
-**Review** — PR merge readiness:
-
-| Command | What it does |
-|---|---|
-| `carson review gate` | Block or approve merge based on unresolved review comments. |
-| `carson review sweep` | Scan recent PRs and update a tracking issue for late feedback. |
-
-**Info**:
-
-| Command | What it does |
-|---|---|
-| `carson version` | Print installed version. |
-| `carson inspect` | Verify Carson-managed hook installation and repository setup. |
+Everything else bends to your preference. Which branch is main, how PRs are merged, which repositories to govern, which coding agent to dispatch, where your lint policy lives — Carson asks during setup and remembers. Sensible defaults are provided; you only change what matters to you. See `MANUAL.md` for the full list.
 
 ## Quickstart
 
@@ -121,7 +71,6 @@ Prerequisites: Ruby `>= 3.4`, `git`, and `gem` in your PATH.
 `gh` (GitHub CLI) is recommended for full review governance features.
 
 ```bash
-# Install
 gem install --user-install carson
 carson version
 ```
@@ -145,7 +94,7 @@ After `carson onboard`, your repository has:
 
 Commit the generated `.github/*` changes, and the repository is governed.
 
-**Daily workflow:**
+**Run governance across your portfolio:**
 
 ```bash
 carson govern --dry-run     # see what Carson would do across all repos
@@ -153,18 +102,9 @@ carson govern               # triage PRs, merge ready ones, dispatch agents, hou
 carson govern --loop 300    # run continuously, cycling every 5 minutes
 ```
 
-Or the individual commands if you prefer manual control:
-
-```bash
-carson audit                # full governance check
-carson review gate          # block or approve merge based on review status
-carson sync                 # fast-forward local main
-carson prune                # clean up stale local branches
-```
-
 ## Where to Read Next
 
-- **MANUAL.md** — installation, first-time setup, CI configuration, daily operations, troubleshooting.
+- **MANUAL.md** — installation, first-time setup, CI configuration, daily operations, full command reference, troubleshooting.
 - **API.md** — formal interface contract: commands, exit codes, configuration schema.
 - **RELEASE.md** — version history and upgrade actions.
 - **docs/define.md** — product definition and scope.

data/RELEASE.md

@@ -5,6 +5,14 @@ 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`.
 
+## 2.13.2 — Docs Refresh
+
+### What changed
+
+- Updated `docs/define.md`: added missing in-scope commands (`govern`, `housekeep`, `refresh --all`, `lint policy`); corrected out-of-scope merge authority statement.
+- Updated `docs/plan.md`: corrected test counts, added `prompt.rb` and `runtime_refresh_all_test.rb` to file structure, added `--loop SECONDS` and `refresh --all` to CLI section, updated delivery status.
+- Updated `API.md`: added `govern` config schema and environment overrides.
+
 ## 2.13.1 — Guided Governance Registration
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-2.13.1
+2.13.2

data/carson.gemspec

@@ -7,8 +7,8 @@ Gem::Specification.new do |spec|
 	spec.version = Carson::VERSION
 	spec.authors = [ "Hailei Wang" ]
 	spec.email = [ "wanghailei@users.noreply.github.com" ]
-	spec.summary = "Autonomous governance runtime — lint, review gates, PR triage, and merge across repositories."
-	spec.description = "Carson lives outside the repositories it governs. On every commit it enforces centralised lint policy and scope checks. On PRs it gates merge on unresolved reviewer feedback, dispatches coding agents to fix CI failures, merges passing PRs, and housekeeps branches. Runs locally and in GitHub Actions."
+	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.required_ruby_version = ">= 3.4"

data/lib/carson/runtime/local.rb

@@ -188,7 +188,7 @@ module Carson
 				puts_line ""
 				puts_line "Onboarding #{repo_name}..."
 
-				unless global_config_exists?
+				if !global_config_exists? || !git_remote_exists?( remote_name: config.git_remote )
 					if self.in.respond_to?( :tty? ) && self.in.tty?
 						setup_status = setup!
 						return setup_status unless setup_status == EXIT_OK

data/lib/carson/runtime/setup.rb

@@ -356,9 +356,9 @@ module Carson
 				accepted = prompt_yes_no( default: true )
 				if accepted
 					append_govern_repo!( repo_path: expanded )
-					puts_line "Registered."
+					puts_line "Registered. Run carson refresh --all to keep all repos in sync."
 				else
-					puts_line "Skipped. Re-run carson onboard to register later."
+					puts_line "Skipped. Run carson onboard here again to register later."
 				end
 			end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 2.13.1
+  version: 2.13.2
 platform: ruby
 authors:
 - Hailei Wang
@@ -9,10 +9,12 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: Carson lives outside the repositories it governs. On every commit it
-  enforces centralised lint policy and scope checks. On PRs it gates merge on unresolved
-  reviewer feedback, dispatches coding agents to fix CI failures, merges passing PRs,
-  and housekeeps branches. Runs locally and in GitHub Actions.
+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.'
 email:
 - wanghailei@users.noreply.github.com
 executables:
@@ -93,6 +95,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: Autonomous governance runtime — lint, review gates, PR triage, and merge
-  across repositories.
+summary: Autonomous repository governance — you write the code, Carson manages everything
+  else.
 test_files: []