carson 2.11.0 → 2.11.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef5d5bfa64c8a8b7f4d2b4893dd5a3cab05ab2f154bd12ab926837ae396c2fe2
-  data.tar.gz: 106a0dc1a54c05e59ba9fe4eb0d01f647c420ac305d92a5d70cbc3c606300006
+  metadata.gz: 2ee87fb6195405a8984a69edfe853c54e4148e097ddeb68b664f3b174f76aa58
+  data.tar.gz: 1aff6cd40925b1e29a5317062963874428759a76932b5bc87ff49b1f181a433c
 SHA512:
-  metadata.gz: 1c1d53528fa822f8d7e4850234a039459f56053762ed8ed1982e7a27c2b1f7fd7820f6565afc2a8cda596971ce4dfab2e2288aeabf8b92e54e2cc5e9266ab213
-  data.tar.gz: 04755a262052a630f8200089d03ff1f5a7c48ab8e68f50097fcdd206a8672da988d51c5f041384752a7d97712854b054aa4fd85b2b7268989190ea248d33bf1f
+  metadata.gz: 5431016b0e297bd23d69a781b633e6e786df4ebe5bb9625a9ed4052e8cdfb399e59e253b007d5403944f52ffdc6882c35eb0cf3babcb487740eadb178306d933
+  data.tar.gz: 713018f54df585927a2a86dc9d922bf750214603fb3daf89991c5eec9152a85ceeaad1ea130597f2fd357f8d95be282953c12c9a408bb169fd445ce26e4c6e10

data/MANUAL.md

@@ -5,7 +5,7 @@ For the mental model and command overview, see `README.md`. For formal interface
 
 ## Install Carson
 
-Prerequisites: Ruby `>= 4.0`, `gem` and `git` in `PATH`. `gh` (GitHub CLI) recommended for full review governance.
+Prerequisites: Ruby `>= 3.4`, `gem` and `git` in `PATH`. `gh` (GitHub CLI) recommended for full review governance.
 
 ```bash
 gem install --user-install carson
@@ -176,6 +176,105 @@ Carson's `govern.merge.method` controls how `carson govern` merges ready PRs. Th
 
 **Important:** Carson's merge method must match your GitHub repository's allowed merge types. If your repo only allows squash merges and Carson is set to `merge`, govern will fail when it tries to auto-merge. Check your repository settings under Settings > General > Pull Requests.
 
+## Defaults and Why
+
+### Principles (iron rules)
+
+These define what Carson *is*. They are not configurable.
+
+- **Outsider boundary** — Carson never places its own artefacts inside a governed repository.
+- **Centralised lint** — one policy source at `~/.carson/lint/`, shared across all repos, zero per-repo drift.
+- **Active review** — undisposed reviewer findings block merge; feedback must be acknowledged.
+- **Self-diagnosing output** — every message names the cause and the fix.
+- **Transparent governance** — Carson prepares everything for merge but never makes decisions without telling you.
+
+### Configurable defaults
+
+These are starting points chosen during `carson setup`. Every default has a reason, but all can be changed.
+
+#### Workflow style
+
+How code reaches main.
+
+- **`branch`** (default) — every change goes through a PR. Hooks block direct commits and pushes to main/master. PRs enforce review, scope integrity, and CI gates before code reaches main.
+- **`trunk`** — commit directly to main. Hooks allow all commits. Suits solo projects or flat teams that don't need PR-based review.
+
+Change: `carson setup` or `CARSON_WORKFLOW_STYLE`.
+
+#### Merge method
+
+How `carson govern` merges ready PRs.
+
+- **`squash`** (default) — one PR = one commit on main. Linear, bisectable history. Every commit is individually revertable. Branch commits are preserved in the PR on GitHub.
+- **`rebase`** — preserves individual branch commits on main. Linear history. Use when commit-level attribution matters.
+- **`merge`** — creates merge commits. Non-linear graph but preserves branch topology. Use when branch structure is meaningful.
+
+Must match your GitHub repo's allowed merge types. Change: `carson setup` or `govern.merge.method` in config.
+
+#### Git remote
+
+Which remote Carson checks for main sync and PR operations.
+
+- Default: **`origin`**. Setup detects your actual remotes and presents them — pick the one that points to GitHub.
+- If multiple remotes share the same URL, setup warns about the duplicate.
+
+Change: `carson setup` or `git.remote` in config.
+
+#### Main branch
+
+Which branch Carson treats as the canonical baseline.
+
+- Default: **`main`**. Setup detects whether `main` or `master` exists and offers both.
+
+Change: `carson setup` or `git.main_branch` in config.
+
+#### Hooks location
+
+Where Carson installs git hooks.
+
+- Default: **`~/.carson/hooks/<version>/`**. Outsider principle: hooks live outside your repo, versioned per Carson release, never committed to your repository.
+
+Change: `CARSON_HOOKS_BASE_PATH`.
+
+#### Lint policy source
+
+Where lint configuration files live.
+
+- Default: **`~/.carson/lint/`**. Centralised: one policy source governs all repos consistently. Repo-local `.rubocop.yml` is forbidden in outsider mode to prevent per-repo drift.
+
+Change the source: `carson lint setup --source <path-or-git-url>`.
+
+#### Scope integrity
+
+Whether cross-module changes are flagged.
+
+- Default: **advisory** (attention, not block). Carson informs you when staged files span multiple module groups (e.g. both `domain` and `ui`), but doesn't prevent the commit. Useful for awareness; not a hard gate.
+
+Customise groups: `scope.path_groups` in config.
+
+#### Review disposition
+
+Whether reviewer findings require acknowledgement.
+
+- Default: **required**. Comments containing risk keywords (`bug`, `security`, `regression`, etc.) must have a `Disposition:` response from the PR author before merge. Prevents feedback from being buried.
+
+Change prefix: `CARSON_REVIEW_DISPOSITION_PREFIX`.
+
+#### Merge authority
+
+Whether `carson govern` can merge PRs autonomously.
+
+- Default: **enabled**. Carson merges PRs that pass all gates (CI green, review clean, audit clean). PRs that need human judgement are escalated, never silently merged.
+
+Disable: `govern.merge_authority: false` in config.
+
+#### Output verbosity
+
+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.

data/README.md

@@ -40,6 +40,18 @@ Carson is an autonomous governance runtime that lives on your workstation and in
 
 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.
 
+## Opinions
+
+Carson is opinionated about governance. These are non-negotiable principles, not configurable defaults:
+
+- **Outsider boundary** — Carson lives outside your repo, never inside. No Carson-owned artefacts in your repository. Offboarding leaves no trace.
+- **Centralised lint** — lint policy at `~/.carson/lint/`, shared across all repos. Repo-local config files are forbidden — one source of truth, zero drift.
+- **Active review** — undisposed reviewer findings block merge. Feedback must be acknowledged, not buried.
+- **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 rules (e.g. `CODING/rubocop.yml`). Carson copies these to `~/.carson/lint/` via `carson lint setup`.
@@ -95,7 +107,7 @@ The data flow:
 
 ## Quickstart
 
-Prerequisites: Ruby `>= 4.0`, `git`, and `gem` in your PATH.
+Prerequisites: Ruby `>= 3.4`, `git`, and `gem` in your PATH.
 `gh` (GitHub CLI) is recommended for full review governance features.
 
 ```bash

data/RELEASE.md

@@ -5,6 +5,28 @@ 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.11.2 — Improve RubyGems Summary and Description
+
+### What changed
+
+- **Gemspec** — rewrote `summary` and `description` to explain what Carson actually does instead of abstract jargon. Summary: "You write the code, Carson manages everything from commit to merge." Description covers the full loop: lint, review gates, PR triage, agent dispatch, merge, cleanup.
+
+### What users must do now
+
+Nothing. Metadata only.
+
+## 2.11.1 — Document Philosophy, Opinions, and Configurable Defaults
+
+### What changed
+
+- **README.md** — added "Opinions" section stating Carson's five iron-rule principles (outsider boundary, centralised lint, active review, self-diagnosing output, transparent governance).
+- **MANUAL.md** — added "Defaults and Why" section: principles recap plus comprehensive reference for all ten configurable defaults with options, rationale, and how to change each one.
+- Fixed stale Ruby prerequisite in both files: `>= 4.0` → `>= 3.4`.
+
+### What users must do now
+
+Nothing. Documentation only.
+
 ## 2.11.0 — Self-Diagnosing Audit and Duplicate-Remote Prevention
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-2.11.0
+2.11.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 = "Outsider governance runtime for repository hygiene and merge readiness."
-	spec.description = "Carson runs outside host repositories and applies governance checks, review gates, and managed GitHub-native files."
+	spec.summary = "You write the code, Carson manages everything from commit to merge."
+	spec.description = "Carson is an autonomous governance runtime that lives outside your repositories. It enforces lint policy on every commit, gates merges on unresolved reviewer feedback, triages open PRs across your entire portfolio, dispatches coding agents to fix failures, merges what's ready, and cleans up after itself. One gem, all your projects, unmanned."
 	spec.homepage = "https://github.com/wanghailei/carson"
 	spec.license = "MIT"
 	spec.required_ruby_version = ">= 3.4"
@@ -20,15 +20,9 @@ Gem::Specification.new do |spec|
 	}
 
 	spec.post_install_message = <<~MSG
-
 		\u29D3 Carson at your service.
-
-		  Step into your project directory and run:
-
-		    carson onboard
-
+		  Step into your project directory and run: carson onboard
 		  I'll walk you through everything from there.
-
 	MSG
 
 	spec.bindir = "exe"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 2.11.0
+  version: 2.11.2
 platform: ruby
 authors:
 - Hailei Wang
@@ -9,8 +9,10 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: Carson runs outside host repositories and applies governance checks,
-  review gates, and managed GitHub-native files.
+description: Carson is an autonomous governance runtime that lives outside your repositories.
+  It enforces lint policy on every commit, gates merges on unresolved reviewer feedback,
+  triages open PRs across your entire portfolio, dispatches coding agents to fix failures,
+  merges what's ready, and cleans up after itself. One gem, all your projects, unmanned.
 email:
 - wanghailei@users.noreply.github.com
 executables:
@@ -71,16 +73,10 @@ metadata:
   changelog_uri: https://github.com/wanghailei/carson/blob/main/RELEASE.md
   bug_tracker_uri: https://github.com/wanghailei/carson/issues
   documentation_uri: https://github.com/wanghailei/carson/blob/main/MANUAL.md
-post_install_message: |2+
-
+post_install_message: |
   ⧓ Carson at your service.
-
-    Step into your project directory and run:
-
-      carson onboard
-
+    Step into your project directory and run: carson onboard
     I'll walk you through everything from there.
-
 rdoc_options: []
 require_paths:
 - lib
@@ -97,6 +93,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: Outsider governance runtime for repository hygiene and merge readiness.
+summary: You write the code, Carson manages everything from commit to merge.
 test_files: []
-...