carson 2.13.2 → 2.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d19271a17424021f6b4ef1ceabe73275feb47c54965175fbd5fbd1a2b6f869b
-  data.tar.gz: 8011d1e680ba9331e99bd8254b0b07605f64ed1856baa6a62b53ec1f6eb98c7c
+  metadata.gz: e3ffc3d262a100056bf88d5d6ecd8f08b1698eab461451510f36e3213f1843f9
+  data.tar.gz: 4afaf01a5a27919d8e14de1d1685ae8c1af58e9aee93cfdc2ce8a01fe8acf4a8
 SHA512:
-  metadata.gz: 51be2370d394a2b83169b5ca543339a8949ec0a8cb969430e934d7a22977e3e085997c7d6f89006a7d128abb9a8f426c5f22327555a6d26f85c89c186eb25dc9
-  data.tar.gz: 9bc89f7a0f84f70d21c0a38ec5cca6b84d961ebab815bfb826f86a1316139915093f378fbbf8d52f9696d9445bacbe3d5677b3c78e14e6a9542b334128adfbb3
+  metadata.gz: 204a4d7f91d94d687b2bc083fee2a988663670195f6835f8717d13607668295f6ce4e2e6bd278599e700208da60fbcdda8809fba298206ea5fc5909accc61dda
+  data.tar.gz: '09cfed5c094db7d7b24b4eb17673bcb226efa21b3615145eac4c6acc396b3ea1b95efcd4e92e6c017274474c5ebe8cd0c9e851af57389e96ea734bd8e72a5db0'

data/.github/copilot-instructions.md

@@ -1 +1 @@
-Read `.github/carson-instructions.md` for repository governance rules enforced by Carson.
+Read `.github/AGENTS.md` for repository governance rules enforced by Carson.

data/API.md

@@ -73,7 +73,7 @@ Blocked Carson artefacts in host repositories:
 - `.tools/carson/*`
 
 Allowed Carson-managed persistence in host repositories:
-- `.github/carson-instructions.md` — governance baseline (source of truth)
+- `.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

data/MANUAL.md

@@ -8,7 +8,7 @@ For the mental model and command overview, see `README.md`. For formal interface
 Prerequisites: Ruby `>= 3.4`, `gem` and `git` in `PATH`. `gh` (GitHub CLI) recommended for full review governance.
 
 ```bash
-gem install --user-install carson
+gem install carson
 ```
 
 If `carson` is not found after installation:
@@ -202,7 +202,7 @@ 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 distributed into each repo's `.github/linters/`, zero per-repo drift. MegaLinter enforces it in CI.
 - **Active review** — undisposed reviewer findings block merge; feedback must be acknowledged.
-- **Self-diagnosing output** — every message names the cause and the fix.
+- **Self-diagnosing output** — every warning and error names what went wrong, why, and what to do next.
 - **Transparent governance** — Carson prepares everything for merge but never makes decisions without telling you.
 
 ### Configurable defaults
@@ -299,10 +299,9 @@ Carson writes managed files that help interactive agents (Claude Code, Codex, Co
 
 **How it works:**
 
-- `.github/carson-instructions.md` — the single source of truth containing the full governance baseline. This file tells agents what Carson is, what commands to run, and what rules to follow.
-- `.github/CLAUDE.md` — read by Claude Code at session start. Points to `carson-instructions.md`.
-- `.github/AGENTS.md` — read by Codex at session start. Points to `carson-instructions.md`.
-- `.github/copilot-instructions.md` — read by GitHub Copilot. Points to `carson-instructions.md`.
+- `.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.
 

data/README.md

@@ -21,24 +21,11 @@ Carson is an autonomous governance runtime that lives on your workstation and in
 **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.
 
 ```
-┌──────────────────────────────────────────────┐
-│  Your workstation                             │
-│                                               │
-│  ~/.carson/            Carson config          │
-│  ~/.carson/hooks/      Git hooks              │
-│  ~/.carson/cache/      Reports                │
-│  ~/.carson/govern/     Dispatch state         │
-│                                               │
-│  carson govern ──► for each repo:             │
-│    1. List open PRs (gh)                      │
-│    2. Classify: CI / review / audit status    │
-│    3. Act: merge | dispatch agent | escalate  │
-│    4. Housekeep: sync + prune                 │
-│                                               │
-│  Governed repos:  repo-A/  repo-B/  repo-C/   │
-│    .github/* templates (committed)            │
-│    core.hooksPath → ~/.carson/hooks           │
-└──────────────────────────────────────────────┘
+  ~/.carson/                     ← Carson lives here, never inside your repos
+       │
+       ├─ hooks ──────────────►  commit gates      (every governed repo)
+       ├─ lint configs ───────►  .github/linters/  (MegaLinter auto-discovers)
+       └─ govern ─────────────►  PR triage → merge | dispatch agent | escalate
 ```
 
 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.
@@ -60,25 +47,17 @@ Carson is opinionated about governance. These are non-negotiable principles, not
 - **Outsider boundary** — Carson lives outside your repo, never inside. No Carson-owned artefacts in your repository. Offboarding leaves no trace.
 - **Centralised lint** — lint policy distributed from a central source into each repo's `.github/linters/`. One source of truth, zero drift. MegaLinter enforces it in CI.
 - **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.
+- **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.
 
 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
 
-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 full review governance features.
 
 ```bash
-gem install --user-install carson
-carson version
-```
-
-**Prepare your lint policy.** A policy source is any directory (or git URL) containing your lint configuration files (`.rubocop.yml`, `biome.json`, `ruff.toml`, etc.). Carson copies these into the governed repo's `.github/linters/` where MegaLinter auto-discovers them:
-
-```bash
-carson lint policy --source /path/to/your-policy-repo
+gem install carson
 ```
 
 **Onboard a repository:**
@@ -87,6 +66,8 @@ carson lint policy --source /path/to/your-policy-repo
 carson onboard /path/to/your-repo
 ```
 
+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.
+
 After `carson onboard`, your repository has:
 - Git hooks that run `carson audit` on every commit.
 - Managed `.github/*` templates synchronised from Carson.
@@ -94,10 +75,20 @@ After `carson onboard`, your repository has:
 
 Commit the generated `.github/*` changes, and the repository is governed.
 
-**Run governance across your portfolio:**
+**Set up lint policy** (optional). If you have a central directory or repository of lint configs, point Carson at it — configs are copied into `.github/linters/` where MegaLinter auto-discovers them:
+
+```bash
+# local directory
+carson lint policy --source /path/to/your-policy-dir
+
+# remote repository
+carson lint policy --source https://github.com/you/lint-policy.git
+```
+
+**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, dispatch coding agents, and housekeep across all governed repos:
 
 ```bash
-carson govern --dry-run     # see what Carson would do across all repos
+carson govern --dry-run     # preview what Carson would do, change nothing
 carson govern               # triage PRs, merge ready ones, dispatch agents, housekeep
 carson govern --loop 300    # run continuously, cycling every 5 minutes
 ```
@@ -106,10 +97,6 @@ carson govern --loop 300    # run continuously, cycling every 5 minutes
 
 - **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.
-- **docs/design.md** — experience and brand design.
-- **docs/develop.md** — contributor guide: architecture, development workflow.
 
 ## Support
 

data/RELEASE.md

@@ -5,6 +5,38 @@ 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.14.0 — Superseded File Cleanup on Template Apply
+
+### What changed
+
+- `carson template apply` now automatically removes files that Carson previously managed but has since renamed or replaced. Running `carson template apply` in a governed repo after upgrading to 2.14.0 will delete `.github/carson-instructions.md` without any manual intervention.
+- `carson template check` reports superseded files present in the repo as stale, listed with a `— superseded` annotation. Exit code `2` (BLOCK) if any stale files are detected.
+- `offboard` also removes superseded files as part of full Carson cleanup.
+- `carson.md` updated to reflect the new `template apply` behaviour.
+
+### No migration required
+
+No manual steps needed. Run `carson template apply` — Carson handles the rest.
+
+## 2.13.3 — Rename carson-instructions.md to carson.md
+
+### What changed
+
+- Renamed `.github/carson-instructions.md` → `.github/carson.md` in both the template set and the Carson repo itself. Shorter name, consistent with Carson's naming conventions.
+- Enriched `carson.md` content: added Commands section (before committing, before merge, housekeeping), exit codes table, and clearer headings. Governance rules are unchanged.
+- Updated agent pointer files: `CLAUDE.md` and `copilot-instructions.md` now point to `AGENTS.md`; `AGENTS.md` points to `carson.md`. One extra level of indirection, zero new files to maintain.
+
+### Migration
+
+In each governed repository, run:
+
+```bash
+git rm .github/carson-instructions.md
+carson template apply
+```
+
+`carson template apply` writes the new `carson.md` and updates the pointer files. The old `carson-instructions.md` must be removed manually — Carson will not delete it automatically.
+
 ## 2.13.2 — Docs Refresh
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-2.13.2
+2.14.0

data/lib/carson/config.rb

@@ -8,7 +8,7 @@ module Carson
 	class Config
 		attr_accessor :git_remote
 		attr_reader :main_branch, :protected_branches, :hooks_base_path, :required_hooks,
-			:path_groups, :template_managed_files,
+			:path_groups, :template_managed_files, :template_superseded_files,
 			:lint_policy_source,
 			:review_wait_seconds, :review_poll_seconds, :review_max_polls, :review_sweep_window_days,
 			:review_sweep_states, :review_disposition_prefix, :review_risk_keywords,
@@ -48,7 +48,8 @@ module Carson
 					}
 				},
 				"template" => {
-					"managed_files" => [ ".github/carson-instructions.md", ".github/copilot-instructions.md", ".github/CLAUDE.md", ".github/AGENTS.md", ".github/pull_request_template.md", ".github/workflows/carson-lint.yml" ]
+					"managed_files" => [ ".github/carson.md", ".github/copilot-instructions.md", ".github/CLAUDE.md", ".github/AGENTS.md", ".github/pull_request_template.md", ".github/workflows/carson-lint.yml" ],
+					"superseded_files" => [ ".github/carson-instructions.md" ]
 				},
 				"lint" => {
 					"policy_source" => "wanghailei/lint.git"
@@ -216,6 +217,7 @@ module Carson
 			@path_groups = fetch_hash( hash: fetch_hash( hash: data, key: "scope" ), key: "path_groups" ).transform_values { |value| normalize_patterns( value: value ) }
 
 			@template_managed_files = fetch_string_array( hash: fetch_hash( hash: data, key: "template" ), key: "managed_files" )
+			@template_superseded_files = fetch_optional_string_array( hash: fetch_hash( hash: data, key: "template" ), key: "superseded_files" )
 			lint_hash = fetch_hash( hash: data, key: "lint" )
 			@lint_policy_source = lint_hash.fetch( "policy_source", "" ).to_s.strip
 

data/lib/carson/runtime/local.rb

@@ -339,27 +339,34 @@ module Carson
 				puts_verbose ""
 				puts_verbose "[Template Sync Check]"
 				results = template_results
+				stale = template_superseded_present
 				drift_count = results.count { |entry| entry.fetch( :status ) == "drift" }
 				error_count = results.count { |entry| entry.fetch( :status ) == "error" }
+				stale_count = stale.count
 				results.each do |entry|
 					puts_verbose "template_file: #{entry.fetch( :file )} status=#{entry.fetch( :status )} reason=#{entry.fetch( :reason )}"
 				end
-				puts_verbose "template_summary: total=#{results.count} drift=#{drift_count} error=#{error_count}"
+				stale.each { |file| puts_verbose "template_file: #{file} status=stale reason=superseded" }
+				puts_verbose "template_summary: total=#{results.count} drift=#{drift_count} stale=#{stale_count} error=#{error_count}"
 				unless verbose?
-					if drift_count.positive?
-						drift_files = results.select { |entry| entry.fetch( :status ) == "drift" }.map { |entry| entry.fetch( :file ) }
-						puts_line "Templates: #{drift_count} of #{results.count} drifted"
-						drift_files.each { |file| puts_line "  #{file}" }
+					if ( drift_count + stale_count ).positive?
+						summary_parts = []
+						summary_parts << "#{drift_count} of #{results.count} drifted" if drift_count.positive?
+						summary_parts << "#{stale_count} stale" if stale_count.positive?
+						puts_line "Templates: #{summary_parts.join( ", " )}"
+						results.select { |entry| entry.fetch( :status ) == "drift" }.each { |entry| puts_line "  #{entry.fetch( :file )}" }
+						stale.each { |file| puts_line "  #{file} — superseded" }
 					else
 						puts_line "Templates: #{results.count} files in sync"
 					end
 				end
 				return EXIT_ERROR if error_count.positive?
 
-				drift_count.positive? ? EXIT_BLOCK : EXIT_OK
+				( drift_count + stale_count ).positive? ? EXIT_BLOCK : EXIT_OK
 			end
 
 			# Applies managed template files as full-file writes from Carson sources.
+			# Also removes superseded files that are no longer part of the managed set.
 			def template_apply!
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
@@ -367,6 +374,7 @@ module Carson
 				puts_verbose ""
 				puts_verbose "[Template Sync Apply]"
 				results = template_results
+				stale = template_superseded_present
 				applied = 0
 				results.each do |entry|
 					if entry.fetch( :status ) == "error"
@@ -386,11 +394,22 @@ module Carson
 					applied += 1
 				end
 
+				removed = 0
+				stale.each do |file|
+					file_path = resolve_repo_path!( relative_path: file, label: "template.superseded_files entry #{file}" )
+					File.delete( file_path )
+					puts_verbose "template_file: #{file} status=removed reason=superseded"
+					removed += 1
+				end
+
 				error_count = results.count { |entry| entry.fetch( :status ) == "error" }
-				puts_verbose "template_apply_summary: updated=#{applied} error=#{error_count}"
+				puts_verbose "template_apply_summary: updated=#{applied} removed=#{removed} error=#{error_count}"
 				unless verbose?
-					if applied.positive?
-						puts_line "Templates applied (#{applied} updated)."
+					if applied.positive? || removed.positive?
+						summary_parts = []
+						summary_parts << "#{applied} updated" if applied.positive?
+						summary_parts << "#{removed} removed" if removed.positive?
+						puts_line "Templates applied (#{summary_parts.join( ", " )})."
 					else
 						puts_line "Templates in sync."
 					end
@@ -428,6 +447,13 @@ module Carson
 				config.template_managed_files.map { |managed_file| template_result_for_file( managed_file: managed_file ) }
 			end
 
+			def template_superseded_present
+				config.template_superseded_files.select do |file|
+					file_path = resolve_repo_path!( relative_path: file, label: "template.superseded_files entry #{file}" )
+					File.file?( file_path )
+				end
+			end
+
 			# Calculates whole-file expected content and returns sync status plus apply payload.
 			def template_result_for_file( managed_file: )
 				# Try subdirectory-aware path first (e.g. .github/workflows/carson-lint.yml),
@@ -764,7 +790,7 @@ module Carson
 			end
 
 			def offboard_cleanup_targets
-				( config.template_managed_files + [
+				( config.template_managed_files + config.template_superseded_files + [
 					".github/workflows/carson-governance.yml",
 					".github/workflows/carson_policy.yml",
 					".carson.yml",

data/templates/.github/AGENTS.md

@@ -1 +1 @@
-Read `.github/carson-instructions.md` for repository governance rules enforced by Carson.
+Read `.github/carson.md` for repository governance rules enforced by Carson.

data/templates/.github/CLAUDE.md

@@ -1 +1 @@
-Read `.github/carson-instructions.md` for repository governance rules enforced by Carson.
+Read `.github/AGENTS.md` for repository governance rules enforced by Carson.

data/templates/.github/carson.md

@@ -0,0 +1,45 @@
+# Carson Governance
+
+This repository is governed by [Carson](https://github.com/wanghailei/carson), an autonomous governance runtime. Carson lives on the maintainer's workstation, not inside this repository.
+
+## What Carson Does Not Do
+
+Carson has no `commit`, `push`, or `pr` commands. Use `git` and `gh` for those. Carson audits and governs; you execute.
+
+## Commands
+
+**Before committing:**
+```bash
+carson audit           # full governance check — run before every commit
+carson template check  # detect drift in .github/* managed files, including stale superseded files
+carson template apply  # fix drift and remove superseded files
+```
+
+**Before recommending merge:**
+```bash
+carson review gate     # block until actionable review findings are resolved
+```
+
+**Branch housekeeping:**
+```bash
+carson sync            # fast-forward local main from remote
+carson prune           # remove stale branches (safer than git branch -d on squash repos)
+carson housekeep       # sync + prune together
+```
+
+## Exit Codes
+
+- `0` — success
+- `1` — runtime or configuration error
+- `2` — policy blocked (hard stop; treat as expected failure in CI)
+
+## Governance Rules
+
+- Before commit and before push, run `carson audit`.
+- At session start and again immediately before merge recommendation, run `gh pr list --state open --limit 50` and re-confirm active PR priorities.
+- Before merge recommendation, run `carson review gate`; it enforces warm-up wait, unresolved-thread convergence, and `Disposition:` acknowledgements for actionable top-level findings.
+- Actionable findings are unresolved review threads, any non-author `CHANGES_REQUESTED` review, or non-author comments/reviews with risk keywords (`bug`, `security`, `incorrect`, `block`, `fail`, `regression`).
+- `Disposition:` responses must include one token (`accepted`, `rejected`, `deferred`) and the target review URL.
+- Scheduled governance runs `carson review sweep` every 8 hours to track late actionable review activity.
+- Do not treat green checks or `mergeStateStatus: CLEAN` as sufficient if unresolved review threads remain.
+- Never suggest destructive operations on protected refs (`main`/`master`, local or remote).

data/templates/.github/copilot-instructions.md

@@ -1 +1 @@
-Read `.github/carson-instructions.md` for repository governance rules enforced by Carson.
+Read `.github/AGENTS.md` for repository governance rules enforced by Carson.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 2.13.2
+  version: 2.14.0
 platform: ruby
 authors:
 - Hailei Wang
@@ -63,7 +63,7 @@ files:
 - lib/carson/version.rb
 - templates/.github/AGENTS.md
 - templates/.github/CLAUDE.md
-- templates/.github/carson-instructions.md
+- templates/.github/carson.md
 - templates/.github/copilot-instructions.md
 - templates/.github/pull_request_template.md
 - templates/.github/workflows/carson-lint.yml

data/templates/.github/carson-instructions.md

@@ -1,12 +0,0 @@
-## Shared Governance Baseline
-
-- GitHub rulesets and required checks are merge authority.
-- Carson runs as an outsider runtime for hook health, main sync, scope integrity, and gh visibility.
-- Before commit and before push, run `carson audit`.
-- At session start and again immediately before merge recommendation, run `gh pr list --state open --limit 50` and re-confirm active PR priorities.
-- Before merge recommendation, run `carson review gate`; it enforces warm-up wait, unresolved-thread convergence, and `Disposition:` dispositions for actionable top-level findings.
-- Actionable findings are unresolved review threads, any non-author `CHANGES_REQUESTED` review, or non-author comments/reviews with risk keywords (`bug`, `security`, `incorrect`, `block`, `fail`, `regression`).
-- `Disposition:` dispositions must include one token (`accepted`, `rejected`, `deferred`) and the target review URL.
-- Scheduled governance runs `carson review sweep` every 8 hours to track late actionable review activity on recent open/closed PRs.
-- Do not treat green checks or `mergeStateStatus: CLEAN` as sufficient if unresolved review threads remain.
-- Never suggest destructive operations on protected refs (`main`/`master`, local or remote).