carson 1.0.1 → 2.6.0

data/SKILL.md

@@ -0,0 +1,102 @@
+# Carson Skill
+
+You are working in a repository governed by Carson — a deterministic governance runtime. Carson handles git hooks, lint enforcement, PR triage, agent dispatch, merge, and cleanup. You provide the intelligence; Carson provides the infrastructure.
+
+## When to use Carson commands
+
+| User intent | Command | What happens |
+|---|---|---|
+| "Check if my code is ready" | `carson audit` | Lint, scope, boundary checks. Exit 0 = clean. Exit 2 = policy block. |
+| "Is my PR mergeable?" | `carson review gate` | Polls for unresolved review threads and actionable comments. Blocks until resolved. |
+| "What's happening across my repos?" | `carson govern --dry-run` | Classifies every open PR without taking action. Read the summary. |
+| "Run governance continuously" | `carson govern --loop 300` | Triage-dispatch-merge cycle every 300 seconds. Ctrl-C to stop. |
+| "Merge ready PRs and dispatch fixes" | `carson govern` | Full autonomous cycle: merge, dispatch agents, escalate, housekeep. |
+| "Set up Carson for a repo" | `carson onboard /path/to/repo` | Installs hooks, syncs templates, runs first audit. |
+| "Refresh after upgrading Carson" | `carson refresh` | Re-applies hooks and templates for the current version. |
+| "Update my local main" | `carson sync` | Fast-forward local main from remote. Blocks if tree is dirty. |
+| "Clean up stale branches" | `carson prune` | Removes local branches whose upstream is gone. |
+| "Check template drift" | `carson template check` then `carson template apply` | Detect and fix .github/* drift. |
+| "Remove Carson from a repo" | `carson offboard /path/to/repo` | Removes hooks and managed files. |
+| "What version?" | `carson version` | Prints installed version with ⧓ badge. |
+| "Verify hook installation" | `carson inspect` | Checks hooks path, file existence, permissions. |
+
+## Exit codes
+
+- `0` — success, all clear.
+- `1` — runtime or configuration error. Read the error message.
+- `2` — policy block. Something must be fixed before proceeding (lint violation, unresolved review, boundary breach).
+
+When you see exit 2, do NOT bypass it. Read the output, fix the root cause, and re-run.
+
+## Interpreting audit output
+
+Carson audit output is structured as labelled key-value lines prefixed with ⧓. Key sections:
+
+- **Working Tree** — staged/unstaged status.
+- **Local Lint Quality** — per-language lint results. `lint_ruby_status: ok` means clean.
+- **Main Sync Status** — whether local main matches remote. If ahead, reset drift before committing.
+- **Scope Integrity Guard** — checks that commits stay within a single business intent and scope group.
+- **Audit Result** — final verdict: `status: ok` (clean), `status: attention` (advisory, not blocking), `status: block` (must fix).
+
+## Interpreting govern output
+
+`carson govern --dry-run` classifies each PR:
+
+- **ready** → would merge. All gates pass.
+- **ci_failing** → would dispatch agent to fix CI.
+- **review_blocked** → would dispatch agent to address review comments.
+- **pending** → skip. Checks still running (within check_wait window).
+- **needs_attention** → escalate. Needs human judgement.
+
+The summary line: `govern_summary: repos=N prs=N ready=N blocked=N`
+
+## Configuration
+
+Single config file: `~/.carson/config.json`. Key settings:
+
+```json
+{
+  "govern": {
+    "repos": ["~/Dev/repo-a", "~/Dev/repo-b"],
+    "merge": { "method": "rebase" },
+    "agent": { "provider": "auto" }
+  },
+  "review": {
+    "bot_usernames": ["gemini-code-assist"]
+  }
+}
+```
+
+- `govern.merge.method` — must match GitHub branch protection. Use `rebase` if linear history is required.
+- `govern.repos` — list of repo paths for portfolio-level governance. Empty = current repo only.
+- `govern.agent.provider` — `auto` (tries codex then claude), `codex`, or `claude`.
+- `review.bot_usernames` — bot logins to ignore in review gate. Use GraphQL login format (no `[bot]` suffix).
+
+Environment overrides take precedence over config file. Common ones:
+- `CARSON_GOVERN_MERGE_METHOD`
+- `CARSON_REVIEW_BOT_USERNAMES`
+- `CARSON_GOVERN_CHECK_WAIT`
+
+## Common scenarios
+
+**Commit blocked by audit:**
+Run `carson audit`, read the block reason, fix it, then `git add` and `git commit` again. Do not skip the hook.
+
+**Review gate blocked:**
+Run `carson review gate` to see which comments need disposition. Respond to each with the required prefix (default: `Disposition:`), then re-run.
+
+**Local main drifted ahead of remote:**
+This means a commit was made to main that couldn't be pushed (branch protection). Reset: `git checkout main && git reset --hard github/main`.
+
+**Hooks out of date after upgrade:**
+Run `carson prepare` to write new hook versions, then `carson inspect` to verify.
+
+**Govern merge fails:**
+Check that `govern.merge.method` in config matches what GitHub allows. If the repo enforces linear history, only `rebase` works.
+
+## Boundaries
+
+- Carson never lives inside governed repositories. No `.carson.yml`, no `bin/carson`, no `.tools/carson/`.
+- Carson-managed files in repos are limited to `.github/*` templates.
+- Carson's hooks live at `~/.carson/hooks/<version>/`, never in `.git/hooks/`.
+- Lint policy lives at `~/.carson/lint/`, seeded by `carson lint setup --source <policy-repo>`.

data/VERSION

@@ -1 +1 @@
-1.0.1
+2.6.0

data/carson.gemspec

@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
 	spec.bindir = "exe"
 	spec.executables = [ "carson" ]
 	spec.require_paths = [ "lib" ]
-	spec.files = Dir.glob( "{lib,exe,templates,assets}/**/*", File::FNM_DOTMATCH ).select { |path| File.file?( path ) } + [
+	spec.files = Dir.glob( "{lib,exe,templates,hooks}/**/*", File::FNM_DOTMATCH ).select { |path| File.file?( path ) } + [
 		".github/copilot-instructions.md",
 		".github/pull_request_template.md",
 		".github/workflows/carson_policy.yml",
@@ -32,6 +32,8 @@ Gem::Specification.new do |spec|
 		"RELEASE.md",
 		"VERSION",
 		"LICENSE",
+		"SKILL.md",
+		"icon.svg",
 		"carson.gemspec"
 	]
 end

data/{assets/hooks → hooks}/pre-commit

@@ -7,7 +7,7 @@ elif command -v carson >/dev/null 2>&1; then
 	carson_command=( "carson" )
 else
 	echo "Carson policy: 'carson' command is required for pre-commit governance checks." >&2
-	echo "Install Carson and rerun 'carson hook'." >&2
+	echo "Install Carson and rerun 'carson prepare'." >&2
 	exit 1
 fi
 

data/{assets/hooks → hooks}/pre-merge-commit

@@ -1,6 +1,10 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+hooks_dir="$(cd "$(dirname "$0")" && pwd)"
+style="$(cat "$hooks_dir/workflow_style" 2>/dev/null || echo "trunk")"
+[ "$style" = "trunk" ] && exit 0
+
 branch_name="$(git rev-parse --abbrev-ref HEAD)"
 if [[ "$branch_name" == "main" || "$branch_name" == "master" ]]; then
 	echo "Carson policy: direct merge commits on ${branch_name} are blocked. Merge through a pull request." >&2

data/{assets/hooks → hooks}/pre-push

@@ -1,6 +1,10 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+hooks_dir="$(cd "$(dirname "$0")" && pwd)"
+style="$(cat "$hooks_dir/workflow_style" 2>/dev/null || echo "trunk")"
+[ "$style" = "trunk" ] && exit 0
+
 remote_name="${1:-unknown}"
 remote_url="${2:-unknown}"
 while read -r local_ref local_sha remote_ref remote_sha; do

data/{assets/hooks → hooks}/prepare-commit-msg

@@ -1,6 +1,10 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+hooks_dir="$(cd "$(dirname "$0")" && pwd)"
+style="$(cat "$hooks_dir/workflow_style" 2>/dev/null || echo "trunk")"
+[ "$style" = "trunk" ] && exit 0
+
 branch_name="$(git rev-parse --abbrev-ref HEAD)"
 if [[ "$branch_name" == "main" || "$branch_name" == "master" ]]; then
 	echo "Carson policy: direct commits on ${branch_name} are blocked. Work on a feature branch and merge via PR." >&2