carson 2.10.0 → 2.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b99975ce01b36b30e333553f7c491ebbf92591a3bc7dbc492633984b80a807a
-  data.tar.gz: 55c64697792a9400be1fef45a68731ac7eab6be3be517c79ae2caebd5f5edc9c
+  metadata.gz: 4c1366b08108b8d3891fdf7b5a408c6fa48fc1f09fee3e7078f6740e775fb113
+  data.tar.gz: 7cfc57e6b7cd66909ea92f9241423e99312cc368c8395c33d8c6b367e8fbaf60
 SHA512:
-  metadata.gz: c716497d2db2c235dc5d8fa90c65fda8002722cabd7e8425305ce9c26917ebd48e905aed20564393d01178bd8d12257606097fdbf3ab1a77be71d1e48dc08681
-  data.tar.gz: 7f5358b84901463fbd1b211c3094df9c7c46566f9decc3a99d4d643264fc76e79de8b3c298d642c6efac41ecc16aa07647b52e66b6a822f7fff842345dfd9ab6
+  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,30 @@ 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
+
+- **Audit concise output now names the remote and suggests recovery actions.** "Main sync (origin): ahead by 1 — git fetch origin, or carson setup to switch remote." instead of the opaque "Main sync: ahead by 1 — reset local drift." The remote name is visible; the fix is embedded.
+- **Setup warns when multiple remotes share the same URL.** Interactive mode annotates duplicates with `[duplicate]` and prints a warning. Silent mode logs a `duplicate_remotes:` verbose line. URL normalisation treats SSH and HTTPS variants as equal (`git@github.com:user/repo.git` matches `https://github.com/user/repo`).
+
+### What users must do now
+
+1. Upgrade Carson to `2.11.0`.
+2. If you have duplicate remotes (e.g. both `origin` and `github` pointing to the same URL), remove the stale one with `git remote remove <name>`.
+
 ## 2.10.0 — Lower Ruby Requirement to 3.4
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-2.10.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"

data/lib/carson/runtime/audit.rb

@@ -46,13 +46,13 @@ module Carson
 					puts_verbose "main_vs_remote_main_behind: #{behind_count}"
 					puts_verbose "ACTION: local #{config.main_branch} is ahead of #{config.git_remote}/#{config.main_branch} by #{ahead_count} commit#{plural_suffix( count: ahead_count )}; reset local drift before commit/push workflows."
 					audit_state = "block"
-					audit_concise_problems << "Main sync: ahead by #{ahead_count} — reset local drift."
+					audit_concise_problems << "Main sync (#{config.git_remote}): ahead by #{ahead_count} — git fetch #{config.git_remote}, or carson setup to switch remote."
 				elsif behind_count.positive?
 					puts_verbose "main_vs_remote_main_ahead: #{ahead_count}"
 					puts_verbose "main_vs_remote_main_behind: #{behind_count}"
 					puts_verbose "ACTION: local #{config.main_branch} is behind #{config.git_remote}/#{config.main_branch} by #{behind_count} commit#{plural_suffix( count: behind_count )}; run carson sync."
 					audit_state = "attention" if audit_state == "ok"
-					audit_concise_problems << "Main sync: behind by #{behind_count} — run carson sync."
+					audit_concise_problems << "Main sync (#{config.git_remote}): behind by #{behind_count} — run carson sync."
 				else
 					puts_verbose "main_vs_remote_main_ahead: 0"
 					puts_verbose "main_vs_remote_main_behind: 0"

data/lib/carson/runtime/setup.rb

@@ -1,3 +1,6 @@
+require "set"
+require "uri"
+
 module Carson
 	class Runtime
 		module Setup
@@ -51,6 +54,15 @@ module Carson
 					puts_verbose "detected_remote: none"
 				end
 
+				remotes = list_git_remotes
+				duplicates = duplicate_remote_groups( remotes: remotes )
+				unless duplicates.empty?
+					duplicates.each_value do |group|
+						names = group.map { it.fetch( :name ) }.join( " and " )
+						puts_verbose "duplicate_remotes: #{names} share the same URL"
+					end
+				end
+
 				branch = detect_main_branch
 				if branch && branch != config.main_branch
 					choices[ "git.main_branch" ] = branch
@@ -69,9 +81,18 @@ module Carson
 					return nil
 				end
 
+				duplicates = duplicate_remote_groups( remotes: remotes )
+				duplicate_names = duplicates.values.flatten.map { it.fetch( :name ) }.to_set
+				unless duplicates.empty?
+					duplicates.each_value do |group|
+						names = group.map { it.fetch( :name ) }.join( " and " )
+						puts_line "Remotes #{names} share the same URL. Consider removing the duplicate."
+					end
+				end
+
 				puts_line ""
 				puts_line "Git remote"
-				options = build_remote_options( remotes: remotes )
+				options = build_remote_options( remotes: remotes, duplicate_names: duplicate_names )
 				options << { label: "Other (enter name)", value: :other }
 
 				default_index = 0
@@ -151,12 +172,13 @@ module Carson
 				value.empty? ? nil : value
 			end
 
-			def build_remote_options( remotes: )
+			def build_remote_options( remotes:, duplicate_names: Set.new )
 				sorted = sort_remotes( remotes: remotes )
 				sorted.map do |entry|
 					name = entry.fetch( :name )
 					url = entry.fetch( :url )
-					{ label: "#{name} (#{url})", value: name }
+					tag = duplicate_names.include?( name ) ? " [duplicate]" : ""
+					{ label: "#{name} (#{url})#{tag}", value: name }
 				end
 			end
 
@@ -173,6 +195,35 @@ module Carson
 				well_known.sort_by { |e| WELL_KNOWN_REMOTES.index( e.fetch( :name ) ) || 999 } + others.sort_by { |e| e.fetch( :name ) }
 			end
 
+			# Normalises a remote URL so SSH and HTTPS variants of the same host/path compare equal.
+			# Strips trailing .git, lowercases, converts git@host:path to https://host/path.
+			def normalise_remote_url( url: )
+				text = url.to_s.strip
+				return "" if text.empty?
+
+				# Convert SSH shorthand (git@host:owner/repo) to HTTPS form.
+				if text.match?( /\A[\w.-]+@[\w.-]+:/ )
+					text = text.sub( /\A[\w.-]+@([\w.-]+):/, 'https://\1/' )
+				end
+
+				text = text.delete_suffix( ".git" )
+				text = text.chomp( "/" )
+				text.downcase
+			end
+
+			# Groups remotes that share the same normalised URL. Returns a hash of
+			# normalised_url => [remote entries] for groups with more than one member.
+			def duplicate_remote_groups( remotes: )
+				by_url = {}
+				remotes.each do |entry|
+					key = normalise_remote_url( url: entry.fetch( :url ) )
+					next if key.empty?
+
+					( by_url[ key ] ||= [] ) << entry
+				end
+				by_url.select { |_url, entries| entries.length > 1 }
+			end
+
 			def build_main_branch_options
 				options = []
 				main_exists = branch_exists_locally_or_remote?( branch: "main" )

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 2.10.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: []
-...