carson 2.14.2 → 2.15.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce8a2ea7975761b31c6b5426d502a55dc106d375b4bd9f57c2d680674bf4e615
-  data.tar.gz: 0762d2fe10827f145729fe397e2f483bf22b2973279cbf3cf5b518658c75654c
+  metadata.gz: d3142430a752f707dc361e222db4581ad007baf32da8e041fc2f4c83475fe26a
+  data.tar.gz: aaefa0ac48072fa8ef9427b79617dac2f82492828b596bb8f9755c2c71c093f7
 SHA512:
-  metadata.gz: 9fd16b82c3766655488285b27bc93886b04cd1b6fe62de40c272ba61b44e6e017f2f5322ba2718246b31f7fdb82e3586903e8b2efd99df2ec0be96a4a616e32d
-  data.tar.gz: c3520519edd34d95326d8fb33b6ff5d2cf582c57fab1626d1f71107b5049f978d101436983f4684e9cebb391d0df393d3d9e23cd7e6961869766b0dabea75952
+  metadata.gz: 8ccd8f2cf691b6d44bd6435d49db141cf01ee4dbf93f1c8b7c37b63ac82ce923ef72c10455118628d2431fa312a344530822bc2d5e4aaecdc89b3487ec34e26e
+  data.tar.gz: a24f069a42dfb80d938aef2e1cb2e397180d59b52b658d80cb47824d26151b06d62dc6904b95e004d3a9440bacb0c9f76a162cea78d406335ae9e5b874bca4e1

data/API.md

@@ -56,6 +56,7 @@ carson <command> [subcommand] [arguments]
 |---|---|
 | `carson version` | Print installed Carson version. |
 | `carson inspect` | Verify Carson-managed hook installation and repository setup. |
+| `carson check` | Report required CI check status for the current branch's open PR. Exits 0 for passing or pending; exits 2 for failing. Never exits 8. |
 
 ## Exit status contract
 
@@ -118,7 +119,7 @@ Environment overrides:
     },
     "check_wait": 30,
     "merge": {
-      "authority": false,
+      "authority": true,
       "method": "squash"
     }
   }
@@ -130,7 +131,7 @@ Environment overrides:
 - `agent.provider`: `"auto"`, `"codex"`, or `"claude"`.
 - `agent.codex` / `agent.claude`: provider-specific options (reserved).
 - `check_wait`: seconds to wait for CI checks before classifying (default: `30`).
-- `merge.authority`: `false` (default) — Carson does not merge until explicitly enabled.
+- `merge.authority`: `true` (default) — Carson may merge autonomously. Set to `false` to require explicit enablement.
 - `merge.method`: `"squash"` (default), `"merge"`, or `"rebase"`.
 
 `lint` schema:

data/RELEASE.md

@@ -5,6 +5,46 @@ 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.15.1 — Codex Review Fixes
+
+### What changed
+
+- `carson check` now correctly exits 2 for cancelled, errored, or timed-out CI checks. Previously, only `fail`-bucketed checks were treated as failing — all other non-passing states (cancelled, error) fell through to "all passing".
+- Pre-push auto-commit now aborts the in-flight push and prints "Push again to include them." Previously the commit was created locally but not included in the push that triggered it.
+- `--push-prep` now stages and commits untracked managed files. Previously, new managed files introduced by a gem upgrade were silently omitted.
+- `API.md`: `merge.authority` default corrected from `false` to `true` to match the implementation.
+- `API.md`: `carson check` added to the Info commands table.
+- `docs/develop.md`: Architecture rationale updated — `govern.rb` acknowledged as a known exception to the adapter shell-out rule.
+- Test coverage added for `check` bucket classification, `managed_dirty_paths` untracked handling, and CLI dispatch.
+
+### No migration required
+
+No configuration or workflow changes needed.
+
+## 2.15.0 — JIT Auto-Commit on Pre-Push + `carson check`
+
+### What changed
+
+- Pre-push hook now calls `carson template apply --push-prep` automatically. Any uncommitted changes to Carson-managed template files or `.github/linters/` are committed before the push reaches GitHub — no manual `git add` / `git commit` needed after a gem upgrade or `lint policy` run.
+- `--push-prep` flag scopes the behaviour to pre-push only; interactive `carson template apply` is unchanged.
+- `carson check` command added: wraps `gh pr checks --required`, exits 0 for pending or passing and 2 for failing. Useful for callers that need a clean CI status signal without `gh`'s confusing "Error: Exit code 8" for pending runs.
+- CI smoke tests guarded against live audit exit codes with `|| true` so a pending or failing CI run on the default branch does not cause false test failures.
+
+### No migration required
+
+Run `bash install.sh` to pick up the updated pre-push hook in all governed repos.
+
+## 2.14.2 — Docs Enrichment
+
+### What changed
+
+- `docs/design.md` enriched with signal system, output design, prompt principles, and vocabulary guide.
+- `docs/develop.md` enriched with architecture rationale, new-command walkthrough, and testing approach.
+
+### No migration required
+
+Documentation only. No behavioural changes.
+
 ## 2.14.1 — Auto-Refresh on Install
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-2.14.2
+2.15.1

data/hooks/pre-push

@@ -7,6 +7,7 @@ style="$(cat "$hooks_dir/workflow_style" 2>/dev/null || echo "branch")"
 
 remote_name="${1:-unknown}"
 remote_url="${2:-unknown}"
+has_commit_push=false
 while read -r local_ref local_sha remote_ref remote_sha; do
 	case "$remote_ref" in
 		refs/heads/main|refs/heads/master)
@@ -14,4 +15,13 @@ while read -r local_ref local_sha remote_ref remote_sha; do
 			exit 1
 			;;
 	esac
+	[[ "$local_sha" != "0000000000000000000000000000000000000000" ]] && has_commit_push=true
 done
+
+if $has_commit_push; then
+	if [[ -n "${CARSON_BIN:-}" ]]; then
+		ruby "$CARSON_BIN" template apply --push-prep || exit 1
+	else
+		carson template apply --push-prep || exit 1
+	fi
+fi

data/lib/carson/cli.rb

@@ -53,7 +53,7 @@ module Carson
 
 		def self.build_parser
 			OptionParser.new do |opts|
-				opts.banner = "Usage: carson [setup|audit|sync|prune|prepare|inspect|onboard [repo_path]|refresh [--all|repo_path]|offboard [repo_path]|template check|template apply|lint policy --source <path-or-git-url>|review gate|review sweep|govern [--dry-run] [--json] [--loop SECONDS]|housekeep|version]"
+				opts.banner = "Usage: carson [setup|audit|check|sync|prune|prepare|inspect|onboard [repo_path]|refresh [--all|repo_path]|offboard [repo_path]|template check|template apply|lint policy --source <path-or-git-url>|review gate|review sweep|govern [--dry-run] [--json] [--loop SECONDS]|housekeep|version]"
 			end
 		end
 
@@ -79,7 +79,7 @@ module Carson
 			when "refresh"
 				parse_refresh_command( argv: argv, parser: parser, err: err )
 			when "template"
-				parse_named_subcommand( command: command, usage: "check|apply", argv: argv, parser: parser, err: err )
+				parse_template_subcommand( argv: argv, parser: parser, err: err )
 			when "lint"
 				parse_lint_subcommand( argv: argv, parser: parser, err: err )
 			when "review"
@@ -143,6 +143,35 @@ module Carson
 			{ command: "#{command}:#{action}" }
 		end
 
+		def self.parse_template_subcommand( argv:, parser:, err: )
+			action = argv.shift
+			if action.to_s.strip.empty?
+				err.puts "#{BADGE} Missing subcommand for template. Use: carson template check|apply"
+				err.puts parser
+				return { command: :invalid }
+			end
+
+			return { command: "template:#{action}" } unless action == "apply"
+
+			options = { push_prep: false }
+			apply_parser = OptionParser.new do |opts|
+				opts.banner = "Usage: carson template apply [--push-prep]"
+				opts.on( "--push-prep", "Apply templates and auto-commit any managed file changes (used by pre-push hook)" ) do
+					options[ :push_prep ] = true
+				end
+			end
+			apply_parser.parse!( argv )
+			unless argv.empty?
+				err.puts "#{BADGE} Unexpected arguments for template apply: #{argv.join( ' ' )}"
+				err.puts apply_parser
+				return { command: :invalid }
+			end
+			{ command: "template:apply", push_prep: options.fetch( :push_prep ) }
+		rescue OptionParser::ParseError => e
+			err.puts "#{BADGE} #{e.message}"
+			{ command: :invalid }
+		end
+
 		def self.parse_lint_subcommand( argv:, parser:, err: )
 			action = argv.shift
 			unless action == "policy"
@@ -235,6 +264,8 @@ module Carson
 				runtime.prepare!
 			when "inspect"
 				runtime.inspect!
+			when "check"
+				runtime.check!
 			when "onboard"
 				runtime.onboard!
 			when "refresh"
@@ -246,7 +277,7 @@ module Carson
 			when "template:check"
 				runtime.template_check!
 			when "template:apply"
-				runtime.template_apply!
+				runtime.template_apply!( push_prep: parsed.fetch( :push_prep, false ) )
 			when "lint:setup"
 				runtime.lint_setup!(
 					source: parsed.fetch( :source ),

data/lib/carson/runtime/audit.rb

@@ -74,6 +74,60 @@ module Carson
 				audit_state == "block" ? EXIT_BLOCK : EXIT_OK
 			end
 
+			# Thin focused command: show required-check status for the current branch's open PR.
+			# Always exits 0 for pending or passing so callers never see a false "Error: Exit code 8".
+			def check!
+				unless gh_available?
+					puts_line "Checks: gh CLI not available."
+					return EXIT_ERROR
+				end
+
+				pr_stdout, pr_stderr, pr_success, = gh_run(
+					"pr", "view", current_branch,
+					"--json", "number,title,url"
+				)
+				unless pr_success
+					error_text = gh_error_text( stdout_text: pr_stdout, stderr_text: pr_stderr, fallback: "no open PR for branch #{current_branch}" )
+					puts_line "Checks: #{error_text}."
+					return EXIT_ERROR
+				end
+				pr_data = JSON.parse( pr_stdout )
+				pr_number = pr_data[ "number" ].to_s
+
+				checks_stdout, checks_stderr, checks_success, checks_exit = gh_run(
+					"pr", "checks", pr_number, "--required", "--json", "name,state,bucket,workflow,link"
+				)
+				if checks_stdout.to_s.strip.empty?
+					error_text = gh_error_text( stdout_text: checks_stdout, stderr_text: checks_stderr, fallback: "required checks unavailable" )
+					puts_line "Checks: #{error_text}."
+					return EXIT_ERROR
+				end
+
+				checks_data = JSON.parse( checks_stdout )
+				pending = checks_data.select { |e| e[ "bucket" ].to_s == "pending" }
+				failing = checks_data.select { |e| check_entry_failing?( entry: e ) }
+				total = checks_data.count
+				# gh exits 8 when required checks are still pending (not a failure).
+				is_pending = !checks_success && checks_exit == 8
+
+				if failing.any?
+					puts_line "Checks: FAIL (#{failing.count} of #{total} failing)."
+					normalise_check_entries( entries: failing ).each { |e| puts_line "  #{e.fetch( :workflow )} / #{e.fetch( :name )} #{e.fetch( :link )}".strip }
+					return EXIT_BLOCK
+				end
+
+				if is_pending || pending.any?
+					puts_line "Checks: pending (#{total - pending.count} of #{total} complete)."
+					return EXIT_OK
+				end
+
+				puts_line "Checks: all passing (#{total} required)."
+				EXIT_OK
+			rescue JSON::ParserError => e
+				puts_line "Checks: invalid gh response (#{e.message})."
+				EXIT_ERROR
+			end
+
 		private
 			def pr_and_check_report
 				report = {
@@ -127,8 +181,8 @@ module Carson
 					return report
 				end
 				checks_data = JSON.parse( checks_stdout )
-				failing = checks_data.select { |entry| entry[ "bucket" ].to_s == "fail" || entry[ "state" ].to_s.upcase == "FAILURE" }
 				pending = checks_data.select { |entry| entry[ "bucket" ].to_s == "pending" }
+				failing = checks_data.select { |entry| check_entry_failing?( entry: entry ) }
 				report[ :checks ][ :status ] = checks_success ? "ok" : ( checks_exit == 8 ? "pending" : "attention" )
 				report[ :checks ][ :required_total ] = checks_data.count
 				report[ :checks ][ :failing_count ] = failing.count
@@ -307,6 +361,12 @@ module Carson
 				[ critical, advisory ]
 			end
 
+			# Returns true when a required-check entry is in a non-passing, non-pending state.
+			# Cancelled, errored, timed-out, and any unknown bucket all count as failing.
+			def check_entry_failing?( entry: )
+				!%w[pass pending].include?( entry[ "bucket" ].to_s )
+			end
+
 			# Failing means completed with a non-successful conclusion.
 			def default_branch_check_run_failing?( entry: )
 				status = entry[ "status" ].to_s.strip.downcase

data/lib/carson/runtime/local.rb

@@ -367,7 +367,7 @@ module Carson
 
 			# 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!
+			def template_apply!( push_prep: false )
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
 
@@ -414,7 +414,10 @@ module Carson
 						puts_line "Templates in sync."
 					end
 				end
-				error_count.positive? ? EXIT_ERROR : EXIT_OK
+				return EXIT_ERROR if error_count.positive?
+
+				return EXIT_BLOCK if push_prep && push_prep_commit!
+				EXIT_OK
 			end
 
 		private
@@ -742,6 +745,33 @@ module Carson
 				git_capture!( "status", "--porcelain" ).strip.empty?
 			end
 
+			def push_prep_commit!
+				# JIT auto-commit is for feature branches only; main is protected from direct commits.
+				return if current_branch == config.main_branch
+
+				dirty = managed_dirty_paths
+				return if dirty.empty?
+
+				git_system!( "add", *dirty )
+				git_system!( "commit", "-m", "chore: sync Carson managed files" )
+				puts_line "Carson committed managed file updates. Push again to include them."
+				true
+			end
+
+			def managed_dirty_paths
+				template_paths = config.template_managed_files + config.template_superseded_files
+				linters_glob   = Dir.glob( File.join( repo_root, ".github/linters/**/*" ) )
+					.select { |p| File.file?( p ) }
+					.map { |p| p.delete_prefix( "#{repo_root}/" ) }
+				candidates = ( template_paths + linters_glob ).uniq
+				return [] if candidates.empty?
+
+				stdout_text, = git_capture_soft( "status", "--porcelain", "--", *candidates )
+				stdout_text.to_s.lines
+					.map { |l| l[ 3.. ].strip }
+					.reject( &:empty? )
+			end
+
 			def inside_git_work_tree?
 				stdout_text, = git_capture_soft( "rev-parse", "--is-inside-work-tree" )
 				stdout_text.to_s.strip == "true"

metadata

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