carson 2.18.0 → 2.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9bf941a78e322ebb3086476fe99f2ec31ef59847e94e54de4e8acf3aa2517be
-  data.tar.gz: 962ee4ef4b7618bc23d4208d610459030974f8b4482d891f6a27ad7e26d39640
+  metadata.gz: b6b2ecf51c931d6c85244d96e294ce87a86583e3a807782ddd74c9058c647563
+  data.tar.gz: 19b49e67b2bdefe3443aa00500394cc479951eb074498d82b69ff3f776b42b15
 SHA512:
-  metadata.gz: 8f0f970f45b6951ce5b56aeb675f5876e515694c01f005d9182f7a2d39d9e56eb7b428b15fc40d93996229487fc62302a56cf3d3a7b5b6d3f1fc799a100f7e48
-  data.tar.gz: 239edae42c9be23c0a273caa110387c090ab33d93f9b2780918e766aeb6aa0d2c837cc85367d22cab139a87e5082e11e245520979d5d6746a50bbb8545e88be9
+  metadata.gz: acc11f185996f6e424b18bbc55ed6194ae87d31db6de09b9b34fc50237c87ada00ab8c1c3809cf9d0b3654353e24cf1a2fb1b9fd6134610a57ded49d4fbe1a5c
+  data.tar.gz: c27ac61fba18b5cf449a33b8703337282b5a30f0cf87568e24320acd56b030b57093ba8d24466c92450745dc61f0eaa83f2c5db603cd242e0e6b2413233331d0

data/API.md

@@ -79,7 +79,7 @@ Allowed Carson-managed persistence in host repositories:
 - `.github/CLAUDE.md` — agent discovery pointer for Claude Code
 - `.github/AGENTS.md` — agent discovery pointer for Codex
 - `.github/pull_request_template.md` — PR template
-- `.github/workflows/carson-lint.yml` — MegaLinter CI workflow
+- Any file discovered from `template.canonical` — user's canonical `.github/` files
 
 ## Configuration interface
 
@@ -134,6 +134,19 @@ Environment overrides:
 - `merge.authority`: `true` (default) — Carson may merge autonomously. Set to `false` to require explicit enablement.
 - `merge.method`: `"squash"` (default), `"merge"`, or `"rebase"`.
 
+`template` schema:
+
+```json
+{
+  "template": {
+    "canonical": "~/AI/LINT"
+  }
+}
+```
+
+`template` semantics:
+- `canonical`: path to a directory of canonical `.github/` files. Carson discovers files in this directory and syncs them to governed repos alongside its own governance files. The directory mirrors `.github/` structure — `workflows/lint.yml` deploys to `.github/workflows/lint.yml`. Default: `nil` (no canonical files).
+
 `lint` schema:
 
 ```json

data/MANUAL.md

@@ -99,16 +99,33 @@ Notes:
 - `CARSON_READ_TOKEN` must have read access to your policy source repository so CI can run `carson lint policy`.
 - The reusable workflow installs a pinned RuboCop gem before `carson audit`; mirror the same pin in host governance workflows for deterministic checks.
 
-### MegaLinter in CI
+### Canonical Templates
 
-Carson manages a MegaLinter workflow template (`carson-lint.yml`) that is applied to governed repositories via `carson template apply`. MegaLinter auto-discovers lint configs from `.github/linters/` — the same directory populated by `carson lint policy`. This means:
+Carson manages 5 governance files (carson.md, CLAUDE.md, AGENTS.md, copilot-instructions.md, pull_request_template.md). Beyond those, you can tell Carson about your own canonical `.github/` files — CI workflows, linter configs, dependabot settings, anything that belongs in `.github/`.
 
-- **Policy source** (your central lint repo) defines the rules.
-- **`carson lint policy`** distributes the rules into each repo.
-- **MegaLinter** (in GitHub Actions) enforces the rules.
-- **`carson govern`** reads CI check status (including MegaLinter results) and acts on it.
+Set `template.canonical` in `~/.carson/config.json`:
 
-Carson's `audit` gates on CI check status reported by GitHub — it does not duplicate MegaLinter's work locally. If MegaLinter fails in CI, `carson govern` classifies the PR accordingly and can dispatch a coding agent to fix the issues.
+```json
+{
+  "template": {
+    "canonical": "~/AI/LINT"
+  }
+}
+```
+
+That directory mirrors the `.github/` structure:
+
+```
+~/AI/LINT/
+├── workflows/
+│   └── lint.yml          → deployed to .github/workflows/lint.yml
+├── .mega-linter.yml      → deployed to .github/.mega-linter.yml
+└── dependabot.yml        → deployed to .github/dependabot.yml
+```
+
+Carson discovers files in this directory and syncs them to governed repos alongside its own governance files. `carson template check` detects drift, `carson template apply` writes them, and `carson refresh` propagates them to the remote.
+
+**Why this design.** Lint, CI, and tooling config are personal decisions — not governance decisions. Carson's job is to deliver your canonical files reliably, not to decide what they should contain.
 
 ## Daily Operations
 
@@ -200,7 +217,7 @@ Carson's `govern.merge.method` controls how `carson govern` merges ready PRs. Th
 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.
+- **Canonical delivery** — your canonical `.github/` files distributed into each governed repo, zero per-repo drift. What those files contain is your call.
 - **Active review** — undisposed reviewer findings block merge; feedback must be acknowledged.
 - **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.

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.19.0 — Canonical Templates, Lint Removed
+
+### What changed
+
+- **Lint templates removed from Carson.** `carson-lint.yml` and `.mega-linter.yml` are no longer managed by Carson. Both are now superseded — `carson refresh` will delete them from governed repos automatically. Lint is a personal decision, not a governance decision.
+- **New `template.canonical` config key.** Point Carson at a directory of your canonical `.github/` files and Carson syncs them to all governed repos alongside its own governance files. You control the content; Carson handles the delivery.
+
+### Migration
+
+1. Run `carson refresh` in each governed repo. Carson will remove the old lint files automatically.
+2. If you want lint, create your own workflow files and set `template.canonical` in `~/.carson/config.json`:
+
+```json
+{
+  "template": {
+    "canonical": "~/AI/LINT"
+  }
+}
+```
+
+That directory mirrors `.github/` structure — for example, `workflows/lint.yml` deploys to `.github/workflows/lint.yml`.
+
+3. Run `carson refresh` again to deploy your canonical files.
+
 ## 2.18.0 — Audit Attention Detail
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-2.18.0
+2.19.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, :template_superseded_files,
+			:path_groups, :template_managed_files, :template_superseded_files, :template_canonical,
 			: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,8 +48,9 @@ module Carson
 					}
 				},
 				"template" => {
-					"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", ".github/.mega-linter.yml" ],
-					"superseded_files" => [ ".github/carson-instructions.md" ]
+					"managed_files" => [ ".github/carson.md", ".github/copilot-instructions.md", ".github/CLAUDE.md", ".github/AGENTS.md", ".github/pull_request_template.md" ],
+					"superseded_files" => [ ".github/carson-instructions.md", ".github/workflows/carson-lint.yml", ".github/.mega-linter.yml" ],
+					"canonical" => nil
 				},
 				"lint" => {
 					"policy_source" => "wanghailei/lint.git"
@@ -218,6 +219,8 @@ module Carson
 
 			@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" )
+			@template_canonical = fetch_optional_path( hash: fetch_hash( hash: data, key: "template" ), key: "canonical" )
+			resolve_canonical_files!
 			lint_hash = fetch_hash( hash: data, key: "lint" )
 			@lint_policy_source = lint_hash.fetch( "policy_source", "" ).to_s.strip
 
@@ -347,5 +350,28 @@ module Carson
 			rescue ArgumentError
 				path
 			end
+
+			# Returns an expanded path string, or nil when the value is absent/blank.
+			def fetch_optional_path( hash:, key: )
+				value = hash[ key ]
+				return nil if value.nil?
+				text = value.to_s.strip
+				return nil if text.empty?
+				safe_expand_path( text )
+			end
+
+			# Discovers files in the canonical directory and appends them to managed_files.
+			# Canonical files mirror the .github/ structure and are synced alongside Carson's own governance files.
+			def resolve_canonical_files!
+				return if @template_canonical.nil? || @template_canonical.empty?
+				return unless Dir.exist?( @template_canonical )
+
+				Dir.glob( File.join( @template_canonical, "**", "*" ) ).sort.each do |absolute_path|
+					next unless File.file?( absolute_path )
+					relative = absolute_path.delete_prefix( "#{@template_canonical}/" )
+					managed_path = ".github/#{relative}"
+					@template_managed_files << managed_path unless @template_managed_files.include?( managed_path )
+				end
+			end
 	end
 end

data/lib/carson/runtime/local.rb

@@ -483,10 +483,8 @@ module Carson
 			# Also removes superseded files present in the worktree.
 			def template_propagate_write_files!( worktree_dir: )
 				config.template_managed_files.each do |managed_file|
-					relative_within_github = managed_file.delete_prefix( ".github/" )
-					template_path = File.join( github_templates_dir, relative_within_github )
-					template_path = File.join( github_templates_dir, File.basename( managed_file ) ) unless File.file?( template_path )
-					next unless File.file?( template_path )
+					template_path = template_source_path( managed_file: managed_file )
+					next if template_path.nil?
 
 					target_path = File.join( worktree_dir, managed_file )
 					FileUtils.mkdir_p( File.dirname( target_path ) )
@@ -665,12 +663,8 @@ module Carson
 
 			# 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),
-				# then fall back to flat basename lookup for backward compatibility.
-				relative_within_github = managed_file.delete_prefix( ".github/" )
-				template_path = File.join( github_templates_dir, relative_within_github )
-				template_path = File.join( github_templates_dir, File.basename( managed_file ) ) unless File.file?( template_path )
-				return { file: managed_file, status: "error", reason: "missing template #{File.basename( managed_file )}", applied_content: nil } unless File.file?( template_path )
+				template_path = template_source_path( managed_file: managed_file )
+				return { file: managed_file, status: "error", reason: "missing template #{File.basename( managed_file )}", applied_content: nil } if template_path.nil?
 
 				expected_content = normalize_text( text: File.read( template_path ) )
 				file_path = resolve_repo_path!( relative_path: managed_file, label: "template.managed_files entry #{managed_file}" )
@@ -692,6 +686,28 @@ module Carson
 				File.join( tool_root, "templates", ".github" )
 			end
 
+			# Resolves the source file path for a managed template.
+			# Checks the user's canonical directory first, then falls back to Carson's built-in templates.
+			def template_source_path( managed_file: )
+				relative_within_github = managed_file.delete_prefix( ".github/" )
+
+				# Canonical source: the user's canonical .github/ files.
+				canonical = config.template_canonical
+				if canonical && !canonical.empty?
+					canonical_path = File.join( canonical, relative_within_github )
+					return canonical_path if File.file?( canonical_path )
+				end
+
+				# Carson built-in templates: subdirectory-aware path first, then flat basename fallback.
+				template_path = File.join( github_templates_dir, relative_within_github )
+				return template_path if File.file?( template_path )
+
+				basename_path = File.join( github_templates_dir, File.basename( managed_file ) )
+				return basename_path if File.file?( basename_path )
+
+				nil
+			end
+
 			# Canonical hook template location inside Carson repository.
 			def hook_template_path( hook_name: )
 				File.join( tool_root, "hooks", hook_name )

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 2.18.0
+  version: 2.19.0
 platform: ruby
 authors:
 - Hailei Wang
@@ -63,13 +63,11 @@ files:
 - lib/carson/runtime/review/utility.rb
 - lib/carson/runtime/setup.rb
 - lib/carson/version.rb
-- templates/.github/.mega-linter.yml
 - templates/.github/AGENTS.md
 - templates/.github/CLAUDE.md
 - templates/.github/carson.md
 - templates/.github/copilot-instructions.md
 - templates/.github/pull_request_template.md
-- templates/.github/workflows/carson-lint.yml
 homepage: https://github.com/wanghailei/carson
 licenses:
 - MIT

data/templates/.github/.mega-linter.yml

@@ -1,29 +0,0 @@
-# Carson-managed MegaLinter configuration.
-# Pushed to governed repositories by `carson template apply`.
-# To override, add entries to a local .mega-linter.yml — MegaLinter merges both.
-
-# Use project-root linter configs (.rubocop.yml, .eslintrc, etc.)
-# instead of MegaLinter's built-in defaults.
-LINTER_RULES_PATH: "."
-
-# Only lint changed files on PRs, not the entire codebase.
-VALIDATE_ALL_CODEBASE: false
-
-# Exclude vendored, generated, and dependency directories.
-FILTER_REGEX_EXCLUDE: "(vendor/|node_modules/|public/packs|public/assets|tmp/|log/|coverage/)"
-
-# Lint code, not prose. Disable documentation-oriented descriptors.
-DISABLE:
-  - MARKDOWN
-  - RST
-  - SPELL
-
-# Disable linters that are too noisy without per-project configuration.
-# checkov/kics flag Carson workflow permissions as overly permissive.
-# devskim floods Rails apps with false-positive security warnings.
-DISABLE_LINTERS:
-  - COPYPASTE_JSCPD
-  - HTML_DJLINT
-  - REPOSITORY_CHECKOV
-  - REPOSITORY_DEVSKIM
-  - REPOSITORY_KICS

data/templates/.github/workflows/carson-lint.yml

@@ -1,23 +0,0 @@
-name: Carson Lint
-on:
-  pull_request:
-    branches: [main, master]
-  push:
-    branches: [main, master]
-
-jobs:
-  lint:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      issues: write
-      pull-requests: write
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - uses: oxsecurity/megalinter@v8
-        env:
-          MEGALINTER_CONFIG: .github/.mega-linter.yml
-          VALIDATE_ALL_CODEBASE: false
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}