carson 1.0.1 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a136a4bb80b1d4f339596760492eb0f692d1fc13dab6c2eb9192ed5aaa7d7345
-  data.tar.gz: 3c71649e9457b2fab7a3091f3b3100f853cf407c1f419c07973b55969082cd7e
+  metadata.gz: fdf6978ed4ecdbef69aba67dba84b678d1145038ff47925a1dfbfdc777170135
+  data.tar.gz: a79ce86bc59f79528e0bf73d51098cd8f1ef1c96c2034d98900c282e26d047c7
 SHA512:
-  metadata.gz: 9bd6d9169e1b7e5cdc5aabbcb5213f8c39c34e65f8f5800e69abb8bf5d13cd91bee4bedc05208e2ae63102bb5d412551527ea81fb90ab69572fa8f241a54970a
-  data.tar.gz: 104447d9c905aff8f0960f037b669634eb1cc35307d002231066ca15f979e7ab9d87f76b10508a2ac5a9069a9b62b70f865934aacad5a73d3b01edc08319b85d
+  metadata.gz: 5c11f2bd0fa18ca630b6c51bc23aae320e96bc63cfd24359c685b4664dd45594c68e3333554a9628c0411833de6c4a1779ef18cdd1d6b048516b116848a88484
+  data.tar.gz: c6d3810f02303d1dbe6f614bc85b6d4a4186a171fa08b9705f66a86cac206eaf1f7c63e67c8a346d5ec9fd0a4c3454fbedbf5fed7275e46a9f1d03f5bd6d55fb

data/.github/copilot-instructions.md

@@ -1,12 +1 @@
-## 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).
+Read `.github/carson-instructions.md` for repository governance rules enforced by Carson.

data/.github/workflows/carson_policy.yml

@@ -79,7 +79,7 @@ jobs:
           CARSON_READ_TOKEN: ${{ secrets.CARSON_READ_TOKEN }}
         run: |
           carson lint setup --source https://github.com/wanghailei/ai.git --ref main --force
-          carson hook
+          carson prepare
           carson audit
 
       - name: Carson review gate

data/API.md

@@ -1,6 +1,7 @@
 # Carson API
 
 This document defines Carson's user-facing interface contract for CLI commands, configuration inputs, and exit behaviour.
+For operational usage and daily workflows, see `MANUAL.md`.
 
 ## Command interface
 
@@ -10,25 +11,53 @@ Command form:
 carson <command> [subcommand] [arguments]
 ```
 
-Supported commands:
+### Setup commands
+
+| Command | Purpose |
+|---|---|
+| `carson lint setup --source <path-or-git-url> [--ref <git-ref>] [--force]` | Seed or refresh `~/.carson/lint` policy files from an explicit source. |
+| `carson onboard [repo_path]` | Apply one-command baseline setup for a target git repository. |
+| `carson prepare` | Install or refresh Carson-managed global hooks. |
+| `carson refresh [repo_path]` | Re-apply hooks, templates, and audit after upgrading Carson. |
+| `carson offboard [repo_path]` | Remove Carson-managed host artefacts and detach Carson hooks path where applicable. |
+
+### Daily commands
 
 | Command | Purpose |
 |---|---|
-| `carson version` | Print installed Carson version. |
-| `carson init [repo_path]` | Apply one-command baseline setup for a target git repository. |
-| `carson sync` | Fast-forward local `main` from configured remote when tree is clean. |
 | `carson audit` | Evaluate governance status and generate report output. |
-| `carson hook` | Install or refresh Carson-managed global hooks. |
-| `carson check` | Run governance checks against current repository state. |
+| `carson sync` | Fast-forward local `main` from configured remote when tree is clean. |
 | `carson prune` | Remove stale local branches whose upstream refs no longer exist. |
 | `carson template check` | Detect drift between managed templates and host `.github/*` files. |
 | `carson template apply` | Write canonical managed template content into host `.github/*` files. |
-| `carson lint setup --source <path-or-git-url> [--ref <git-ref>] [--force]` | Seed or refresh `~/AI/CODING` policy files from an explicit source. |
+
+### Govern commands
+
+| Command | Purpose |
+|---|---|
+| `carson govern [--dry-run] [--json] [--loop SECONDS]` | Portfolio-level PR triage: classify, merge, dispatch agents, escalate. |
+| `carson housekeep` | Sync main + prune stale branches (also runs automatically after govern merges). |
+
+`--loop SECONDS` runs the govern cycle continuously, sleeping SECONDS between cycles. The loop isolates errors per cycle — a single failing cycle does not stop the daemon. `Ctrl-C` cleanly exits with a cycle count summary. SECONDS must be a positive integer.
+
+`govern.merge.method` accepts `squash`, `merge`, or `rebase` (default: `squash`). Squash keeps main linear — one PR, one commit. When the target repository enforces linear history via branch protection, both `squash` and `rebase` are accepted by GitHub — only `merge` is rejected.
+
+### Review commands
+
+| Command | Purpose |
+|---|---|
 | `carson review gate` | Block until actionable review findings are resolved or convergence timeout is reached. |
 | `carson review sweep` | Scan recent PR activity and update a rolling tracking issue for late actionable feedback. |
-| `carson offboard [repo_path]` | Remove Carson-managed host artefacts and detach Carson hooks path where applicable. |
+
+### Info commands
+
+| Command | Purpose |
+|---|---|
+| `carson version` | Print installed Carson version. |
+| `carson inspect` | Verify Carson-managed hook installation and repository setup. |
 
 ## Exit status contract
+
 - `0`: success
 - `1`: runtime/configuration/command error
 - `2`: policy blocked (hard stop)
@@ -36,15 +65,21 @@ Supported commands:
 Automation and CI integrations should treat exit `2` as an expected policy failure signal.
 
 ## Repository boundary contract
+
 Blocked Carson artefacts in host repositories:
 - `.carson.yml`
 - `bin/carson`
 - `.tools/carson/*`
 
 Allowed Carson-managed persistence in host repositories:
-- selected GitHub-native files under `.github/*`
+- `.github/carson-instructions.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
+- `.github/pull_request_template.md` — PR template
 
 ## Configuration interface
+
 Default global configuration path:
 - `~/.carson/config.json`
 
@@ -71,7 +106,7 @@ Environment overrides:
         "enabled": true,
         "globs": ["**/*.rb"],
         "command": ["ruby", "/absolute/path/to/carson/lib/carson/policy/ruby/lint.rb", "{files}"],
-        "config_files": ["~/AI/CODING/rubocop.yml"]
+        "config_files": ["~/.carson/lint/rubocop.yml"]
       }
     }
   }
@@ -84,7 +119,7 @@ Environment overrides:
 - `command`: argv array executed without shell interpolation.
 - `config_files`: required files that must exist before lint runs.
 - `{files}` token: replaced with matched files; if omitted, matched files are appended at the end of argv.
-- Default Ruby policy source is `~/AI/CODING/rubocop.yml`; Ruby execution logic is Carson-owned.
+- Default Ruby policy source is `~/.carson/lint/rubocop.yml`; Ruby execution logic is Carson-owned.
 - Client repositories containing repo-local `.rubocop.yml` are hard-blocked by `carson audit` in outsider mode.
 - Non-Ruby language entries (`javascript`, `css`, `html`, `erb`) are present but disabled by default.
 
@@ -101,14 +136,16 @@ Ruby source requirement for `carson lint setup` (when Ruby lint is enabled):
 - `CODING/rubocop.yml` must exist in the source tree.
 
 Policy layout requirement:
-- Language policy files are stored directly under `CODING/` and copied to `~/AI/CODING/` without language subdirectories.
+- Language policy files are stored directly under `CODING/` and copied to `~/.carson/lint/` without language subdirectories.
 
 ## Output interface
+
 Report output directory precedence:
-- `~/.cache/carson`
+- `~/.carson/cache`
 - `TMPDIR/carson` (used when `HOME` is invalid and `TMPDIR` is absolute)
 - `/tmp/carson` (fallback)
 
 ## Versioning and compatibility
+
 - Pin Carson in automation by explicit release and version pair (`carson_ref`, `carson_version`).
 - Review upgrade actions in `RELEASE.md` before moving to a newer minor or major version.

data/MANUAL.md

@@ -1,19 +1,14 @@
 # Carson Manual
 
-This manual is for users who need to install Carson, configure repository governance, and run a stable daily operating cadence.
-
-## Prerequisites
-- Ruby `>= 4.0`
-- `gem` in `PATH`
-- `git` in `PATH`
-- `gh` in `PATH` (recommended for full review governance features)
+This manual covers installation, first-time setup, CI configuration, and daily operations.
+For the mental model and command overview, see `README.md`. For formal interface definitions, see `API.md`.
 
 ## Install Carson
 
-Recommended installation path:
+Prerequisites: Ruby `>= 4.0`, `gem` and `git` in `PATH`. `gh` (GitHub CLI) recommended for full review governance.
 
 ```bash
-gem install --user-install carson -v 1.0.0
+gem install --user-install carson
 ```
 
 If `carson` is not found after installation:
@@ -22,53 +17,53 @@ If `carson` is not found after installation:
 export PATH="$(ruby -e 'print Gem.user_dir')/bin:$PATH"
 ```
 
-Verify installation:
+Verify:
 
 ```bash
 carson version
 ```
 
-Expected result:
-- Carson version is printed.
-- The `carson` command is available in your shell.
+## First-Time Setup
+
+### Step 1: Prepare your lint policy
 
-## Configure your first repository
-Assume your repository path is `/local/path/of/repo`.
+Carson enforces lint rules from a central policy source — a directory or git repository you control that contains a `CODING/` folder. For Ruby governance, the required file is `CODING/rubocop.yml`.
 
-Prepare your global lint policy baseline first:
+Run `lint setup` to copy policy files into `~/.carson/lint/`:
 
 ```bash
-carson lint setup --source /path/to/ai-policy-repo
+carson lint setup --source /path/to/your-policy-repo
 ```
 
-`lint setup` expects the source to contain `CODING/` and writes policy files to `~/AI/CODING/`.
-For Ruby, the required policy file is `CODING/rubocop.yml`.
-Language policy files are expected directly under `CODING/` (flat layout, no language subfolders).
-Use `--ref <git-ref>` when `--source` is a git URL.
-Use `--force` to overwrite existing `~/AI/CODING` files.
+After this command, `~/.carson/lint/rubocop.yml` exists and is ready for Carson to use. Every governed repository will reference these same policy files — this is how Carson keeps lint consistent.
+
+Options:
+- `--source <path-or-git-url>` — where to read policy files from (required).
+- `--ref <git-ref>` — branch or tag when `--source` is a git URL.
+- `--force` — overwrite existing `~/.carson/lint` files.
 
-Audit policy notes:
-- Ruby lint policy data lives only in `~/AI/CODING/rubocop.yml`; execution logic is Carson-owned.
-- Client repositories must not contain repo-local `.rubocop.yml`; `carson audit` blocks when it exists.
-- Non-Ruby language entries remain configured but disabled by default.
+Policy layout: language config files sit directly under `CODING/` (flat layout, no language subfolders). Non-Ruby entries are present but disabled by default.
 
-Run baseline initialisation:
+### Step 2: Onboard a repository
 
 ```bash
-carson init /local/path/of/repo
+carson onboard /path/to/your-repo
 ```
 
-`init` performs:
-- remote alignment using configured `git.remote` (default `github`)
-- hook installation under `~/.carson/hooks/<version>/`
-- repository `core.hooksPath` alignment to Carson global hooks
-- commit-time governance gate via managed `pre-commit` hook
-- managed `.github/*` template synchronisation
-- initial governance audit
+`onboard` performs:
+- Remote alignment using configured `git.remote` (default `github`).
+- Hook installation under `~/.carson/hooks/<version>/`.
+- Repository `core.hooksPath` alignment to Carson global hooks.
+- Commit-time governance gate via managed `pre-commit` hook.
+- Managed `.github/*` template synchronisation.
+- Initial governance audit.
+
+### Step 3: Commit generated files
+
+After `onboard`, commit the generated `.github/*` changes in your repository. From this point the repository is governed.
 
-After `init`, commit generated `.github/*` changes in your repository.
+## CI Setup
 
-## Pin Carson in CI
 Use the reusable workflow with explicit release pins:
 
 ```yaml
@@ -79,7 +74,7 @@ on:
 
 jobs:
   governance:
-    uses: wanghailei/carson/.github/workflows/carson_policy.yml.8.1
+    uses: wanghailei/carson/.github/workflows/carson_policy.yml@v1.0.0
     secrets:
       CARSON_READ_TOKEN: ${{ secrets.CARSON_READ_TOKEN }}
     with:
@@ -88,20 +83,22 @@ jobs:
       rubocop_version: "1.81.0"
 ```
 
-When upgrading Carson, update both `carson_ref` and `carson_version` together.
-`CARSON_READ_TOKEN` must have read access to `wanghailei/ai` so CI can run `carson lint setup`.
-The reusable workflow installs a pinned RuboCop gem before `carson audit`; mirror the same pin in host governance workflows (including BOS) for deterministic checks.
+Notes:
+- When upgrading Carson, update both `carson_ref` and `carson_version` together.
+- `CARSON_READ_TOKEN` must have read access to your policy source repository so CI can run `carson lint setup`.
+- The reusable workflow installs a pinned RuboCop gem before `carson audit`; mirror the same pin in host governance workflows for deterministic checks.
 
-## Daily operations
-Start of work:
+## Daily Operations
+
+**Start of work:**
 
 ```bash
-carson sync
-carson lint setup --source /path/to/ai-policy-repo
-carson audit
+carson sync                                          # fast-forward local main
+carson lint setup --source /path/to/your-policy-repo # refresh policy if needed
+carson audit                                         # full governance check
 ```
 
-Before push or PR update:
+**Before push or PR update:**
 
 ```bash
 carson audit
@@ -114,57 +111,135 @@ If template drift is detected:
 carson template apply
 ```
 
-Before merge recommendation:
+**Before merge:**
 
 ```bash
-gh pr list --state open --limit 50
 carson review gate
 ```
 
-Scheduled late-review monitoring:
+**Periodic maintenance:**
 
 ```bash
-carson review sweep
+carson review sweep    # update tracking issue for late review feedback
+carson prune           # remove stale local branches
 ```
 
-Local branch clean-up:
+## Running Carson Govern Continuously
+
+Use `--loop SECONDS` to run `carson govern` as a persistent daemon that cycles on a schedule:
 
 ```bash
-carson prune
+carson govern --loop 300              # cycle every 5 minutes
+carson govern --loop 300 --dry-run    # observe mode, no merges or dispatches
+```
+
+The loop is built-in and cross-platform — no cron, launchd, or Task Scheduler required. Run it in a terminal, tmux, screen, or as a system service.
+
+Each cycle runs independently: if one cycle fails (network error, GitHub API timeout), the error is logged and the next cycle proceeds normally. Press `Ctrl-C` to stop — Carson exits cleanly with a cycle count summary.
+
+## Merge Method and Linear History
+
+Carson's `govern.merge.method` controls how `carson govern` merges ready PRs. The options are `squash`, `merge`, and `rebase` (default: `squash`). Set this in `~/.carson/config.json`:
+
+```json
+{
+  "govern": {
+    "merge": {
+      "method": "squash"
+    }
+  }
+}
 ```
 
-## Exit contract
-- `0`: success
-- `1`: runtime or configuration error
-- `2`: policy blocked (hard stop)
+**Why squash is the default.** Squash-to-main keeps history linear: one PR = one commit on main. Every commit on main corresponds to a reviewed, CI-passing unit of work. The benefits:
+
+- `git log --oneline` on main tells the full story without merge noise or work-in-progress commits.
+- Every commit is individually revertable — `git revert <sha>` undoes exactly one PR.
+- `git bisect` operates on meaningful boundaries, not intermediate fixup commits.
+- Individual branch commits are still preserved in the PR on GitHub for full traceability.
+
+**When to use other methods:**
+
+- `rebase` — if you want to preserve individual commits from the branch on main. Both `squash` and `rebase` are compatible with GitHub's "Require linear history" branch protection — only `merge` is rejected.
+- `merge` — if you want explicit merge commits. This creates a non-linear graph but preserves branch topology.
+
+**Important:** Carson's merge method must match your GitHub repository's allowed merge types. If your repo only allows squash merges and Carson is set to `merge`, govern will fail when it tries to auto-merge. Check your repository settings under Settings > General > Pull Requests.
 
-Treat exit `2` as a mandatory stop until the policy violation is resolved.
+## Agent Discovery
+
+Carson writes managed files that help interactive agents (Claude Code, Codex, Copilot) discover the governance system when they work in a governed repository.
+
+**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`.
+
+Each agent reads its own expected filename and follows the reference to the shared baseline. One file to maintain, zero drift across agents.
+
+All four files are managed templates — `carson template check` detects drift, `carson template apply` writes them, and `carson offboard` removes them.
+
+**Why this matters:** without discovery, agents working in governed repos hit Carson's hooks blindly and don't understand the governance contract. With discovery, agents know to run `carson audit` before committing, `carson review gate` before recommending a merge, and to respect protected refs.
+
+## Configuration
+
+Default global config path: `~/.carson/config.json`.
+
+Precedence (highest wins): environment variables > config file > built-in defaults.
+
+Override the config file path with `CARSON_CONFIG_FILE=/absolute/path/to/config.json`.
+
+Common environment overrides:
+
+| Variable | Purpose |
+|---|---|
+| `CARSON_HOOKS_BASE_PATH` | Custom hooks installation directory. |
+| `CARSON_REVIEW_WAIT_SECONDS` | Initial wait before first review poll. |
+| `CARSON_REVIEW_POLL_SECONDS` | Interval between review polls. |
+| `CARSON_REVIEW_MAX_POLLS` | Maximum review poll attempts. |
+| `CARSON_REVIEW_DISPOSITION_PREFIX` | Required prefix for disposition comments. |
+| `CARSON_REVIEW_SWEEP_WINDOW_DAYS` | Lookback window for review sweep. |
+| `CARSON_REVIEW_SWEEP_STATES` | PR states to include in sweep. |
+| `CARSON_RUBY_INDENTATION` | Ruby indentation policy (`tabs`, `spaces`, or `either`). |
+
+For the full configuration schema and `lint.languages` definition, see `API.md`.
 
 ## Troubleshooting
-`carson: command not found`
+
+**`carson: command not found`**
 - Confirm Ruby and gem installation.
 - Confirm `$(ruby -e 'print Gem.user_dir')/bin` is in `PATH`.
 
-`review gate` fails on actionable comments
+**`review gate` fails on actionable comments**
 - Respond with a valid disposition comment using the required prefix.
 - Re-run `carson review gate`.
 
-Template drift blocks
+**Template drift blocks**
 
 ```bash
 carson template apply
 carson template check
 ```
 
-## Offboard from a repository
+**Audit blocks on repo-local `.rubocop.yml`**
+- Carson hard-blocks governed repositories that contain their own `.rubocop.yml`. Remove the repo-local file and rely on the central policy in `~/.carson/lint/rubocop.yml`.
+
+**Hook version mismatch after upgrade**
+- Run `carson refresh` to re-apply hooks and templates for the new Carson version.
+
+## Offboard a Repository
+
 To retire Carson from a repository:
 
 ```bash
-carson offboard /local/path/of/repo
+carson offboard /path/to/your-repo
 ```
 
 This removes Carson-managed host artefacts and unsets `core.hooksPath` when it points to Carson-managed global hooks.
 
-## Related documents
-- Interface reference: `API.md`
+## Related Documents
+
+- Mental model and command overview: `README.md`
+- Formal interface contract: `API.md`
 - Release notes: `RELEASE.md`