carson 2.13.3 → 2.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17b8bd4f2f9f3b9d1cc1d637accc607cfb3f7a49e98cc4a998cb8b797a82bc50
-  data.tar.gz: 3247d5bac41cbd0da539a45210521c66436b2ee3d2da8b6e28ee8f6a6c694955
+  metadata.gz: e3ffc3d262a100056bf88d5d6ecd8f08b1698eab461451510f36e3213f1843f9
+  data.tar.gz: 4afaf01a5a27919d8e14de1d1685ae8c1af58e9aee93cfdc2ce8a01fe8acf4a8
 SHA512:
-  metadata.gz: e018a857a0af89a3828355f0af131b4bf3fee40412d6c1e719c20493f9c6daf91f2da595d9b0b611f0df787a25e6d65997456668160615ca4b9c6419ffb89ee7
-  data.tar.gz: f7db01059c1dfb0b8be6be61c34859c157ac7283df40f010120f57bcdc1ad95b3bbdaf2a6596329be260be1dfcb818d2b177ded70e92d637294441fe70bc0f69
+  metadata.gz: 204a4d7f91d94d687b2bc083fee2a988663670195f6835f8717d13607668295f6ce4e2e6bd278599e700208da60fbcdda8809fba298206ea5fc5909accc61dda
+  data.tar.gz: '09cfed5c094db7d7b24b4eb17673bcb226efa21b3615145eac4c6acc396b3ea1b95efcd4e92e6c017274474c5ebe8cd0c9e851af57389e96ea734bd8e72a5db0'

data/RELEASE.md

@@ -5,6 +5,19 @@ 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

data/VERSION

@@ -1 +1 @@
-2.13.3
+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.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/carson.md

@@ -11,8 +11,8 @@ Carson has no `commit`, `push`, or `pr` commands. Use `git` and `gh` for those.
 **Before committing:**
 ```bash
 carson audit           # full governance check — run before every commit
-carson template check  # detect drift in .github/* managed files
-carson template apply  # fix drift if detected
+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:**

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 2.13.3
+  version: 2.14.0
 platform: ruby
 authors:
 - Hailei Wang