carson 2.11.0 → 2.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef5d5bfa64c8a8b7f4d2b4893dd5a3cab05ab2f154bd12ab926837ae396c2fe2
-  data.tar.gz: 106a0dc1a54c05e59ba9fe4eb0d01f647c420ac305d92a5d70cbc3c606300006
+  metadata.gz: 4c1366b08108b8d3891fdf7b5a408c6fa48fc1f09fee3e7078f6740e775fb113
+  data.tar.gz: 7cfc57e6b7cd66909ea92f9241423e99312cc368c8395c33d8c6b367e8fbaf60
 SHA512:
-  metadata.gz: 1c1d53528fa822f8d7e4850234a039459f56053762ed8ed1982e7a27c2b1f7fd7820f6565afc2a8cda596971ce4dfab2e2288aeabf8b92e54e2cc5e9266ab213
-  data.tar.gz: 04755a262052a630f8200089d03ff1f5a7c48ab8e68f50097fcdd206a8672da988d51c5f041384752a7d97712854b054aa4fd85b2b7268989190ea248d33bf1f
+  metadata.gz: 9453360cbbc88577104b25a29373f987e4b8e3e881ec1d21127cbe0e8944beb0b479a617c9d8d83ca970a506b2bb76ceaeec6f264b25b00ae178f772be3a8ea1
+  data.tar.gz: f73ced7d9c9114ab395da8a348809ca17944b97cf6012b43c1dda23aa415d40a376c4e0ba01ba28eb3c8fbc74dc6ea7dad711850534ae10014b9a68cdd32dc40

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,18 @@ 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.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.1

data/carson.gemspec

@@ -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.1
 platform: ruby
 authors:
 - Hailei Wang
@@ -71,16 +71,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
@@ -99,4 +93,3 @@ rubygems_version: 4.0.3
 specification_version: 4
 summary: Outsider governance runtime for repository hygiene and merge readiness.
 test_files: []
-...