carson 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f56a11a84e2d19363137153a34302874e8ad0941e4fb330012a1ec92a124eb6a
+  data.tar.gz: 060f8f8c2fbe673321255c32d6b064c674358908b4171a71cf778ab2215cf3aa
+SHA512:
+  metadata.gz: 39c24b390c66d13428e7bede056a0465481759ec3abf64a380118c954c84705242645d772a3ecd9f52e85a9b61a33f27e345b641a7b8af63757d7fd8383904e4
+  data.tar.gz: 25612172dd0f5649f8fc54af37cba2a43727d3848caac284805ee0e3c7ba6b40da4ce9fedab8fd7cd780e05ff370862e2b03d0d259572f741b064df442af952d

data/.github/copilot-instructions.md

@@ -0,0 +1,12 @@
+## 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).

data/.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## Shared Scope and Validation
+
+- [ ] `single_business_intent`: this PR is one coherent domain or feature intent.
+- [ ] `single_scope_group`: non-doc files stay within one scope group.
+- [ ] `cross-boundary_changes_justified`: any cross-boundary change has explicit rationale.
+- [ ] `carson audit` before commit.
+- [ ] `carson audit` before push.
+- [ ] `gh pr list --state open --limit 50` checked at session start (capture competing active PRs).
+- [ ] `gh pr list --state open --limit 50` re-checked immediately before merge decision.
+- [ ] Required CI checks are passing.
+- [ ] At least 60 seconds passed since the last push to allow AI reviewers to post.
+- [ ] No unresolved required conversation threads at merge time.
+- [ ] `carson review gate` passes with converged snapshots.
+- [ ] Every actionable top-level review item has a `Disposition:` disposition (`accepted`, `rejected`, `deferred`) with the target review URL.

data/.github/workflows/carson_policy.yml

@@ -0,0 +1,90 @@
+name: Carson policy reusable
+
+on:
+  workflow_call:
+    inputs:
+      carson_ref:
+        description: Carson repository ref to check out
+        required: false
+        type: string
+        default: main
+      carson_version:
+        description: Exact Carson gem version expected in VERSION
+        required: true
+        type: string
+      rubocop_version:
+        description: Exact RuboCop gem version installed before Carson audit.
+        required: false
+        type: string
+        default: "1.81.0"
+    secrets:
+      CARSON_READ_TOKEN:
+        description: Read token for private lint-policy source repository.
+        required: false
+
+jobs:
+  governance:
+    name: Carson policy
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+
+    steps:
+      - name: Checkout host repository
+        uses: actions/checkout@v4
+        with:
+          path: host
+          fetch-depth: 0
+
+      - name: Checkout Carson runtime
+        uses: actions/checkout@v4
+        with:
+          repository: wanghailei/carson
+          ref: ${{ inputs.carson_ref }}
+          path: carson
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "4.0"
+
+      - name: Validate expected version
+        run: |
+          actual="$(cat carson/VERSION)"
+          if [[ "$actual" != "${{ inputs.carson_version }}" ]]; then
+            echo "Expected Carson version ${{ inputs.carson_version }} but got ${actual}" >&2
+            exit 1
+          fi
+
+      - name: Install Carson gem from source checkout
+        run: |
+          cd carson
+          gem build carson.gemspec
+          gem install --local "carson-${{ inputs.carson_version }}.gem"
+
+      - name: Install pinned RuboCop
+        run: gem install rubocop -v "${{ inputs.rubocop_version }}" --no-document
+
+      - name: Align remote name for Carson
+        working-directory: host
+        run: |
+          if ! git remote get-url github >/dev/null 2>&1; then
+            git remote rename origin github
+          fi
+
+      - name: Carson audit
+        working-directory: host
+        env:
+          CARSON_READ_TOKEN: ${{ secrets.CARSON_READ_TOKEN }}
+        run: |
+          carson lint setup --source https://github.com/wanghailei/ai.git --ref main --force
+          carson hook
+          carson audit
+
+      - name: Carson review gate
+        working-directory: host
+        env:
+          GH_TOKEN: ${{ github.token }}
+          CARSON_PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: carson review gate

data/API.md

@@ -0,0 +1,114 @@
+# Carson API
+
+This document defines Carson's user-facing interface contract for CLI commands, configuration inputs, and exit behaviour.
+
+## Command interface
+
+Command form:
+
+```bash
+carson <command> [subcommand] [arguments]
+```
+
+Supported 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 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. |
+| `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. |
+
+## Exit status contract
+- `0`: success
+- `1`: runtime/configuration/command error
+- `2`: policy blocked (hard stop)
+
+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/*`
+
+## Configuration interface
+Default global configuration path:
+- `~/.carson/config.json`
+
+Override path:
+- `CARSON_CONFIG_FILE=/absolute/path/to/config.json`
+
+Environment overrides:
+- `CARSON_HOOKS_BASE_PATH`
+- `CARSON_REVIEW_WAIT_SECONDS`
+- `CARSON_REVIEW_POLL_SECONDS`
+- `CARSON_REVIEW_MAX_POLLS`
+- `CARSON_REVIEW_DISPOSITION_PREFIX`
+- `CARSON_REVIEW_SWEEP_WINDOW_DAYS`
+- `CARSON_REVIEW_SWEEP_STATES`
+- `CARSON_RUBY_INDENTATION`
+
+`lint.languages` schema:
+
+```json
+{
+  "lint": {
+    "languages": {
+      "ruby": {
+        "enabled": true,
+        "globs": ["**/*.rb"],
+        "command": ["ruby", "/absolute/path/to/carson/lib/carson/policy/ruby/lint.rb", "{files}"],
+        "config_files": ["~/AI/CODING/rubocop.yml"]
+      }
+    }
+  }
+}
+```
+
+`lint.languages` semantics:
+- `enabled`: boolean toggle per language.
+- `globs`: file-match patterns applied to the selected audit target set.
+- `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.
+- 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.
+
+Lint target file source precedence in `carson audit`:
+- staged files for local commit-time execution.
+- PR changed files in GitHub `pull_request` events.
+- full repository tracked files in GitHub non-PR events.
+- local working-tree changes as fallback.
+
+Private-source clone token for `carson lint setup`:
+- `CARSON_READ_TOKEN` (used when `--source` points to a private GitHub repository).
+
+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.
+
+## Output interface
+Report output directory precedence:
+- `~/.cache/carson`
+- `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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hailei Wang (WHL) <wanghailei@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/MANUAL.md

@@ -0,0 +1,170 @@
+# 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)
+
+## Install Carson
+
+Recommended installation path:
+
+```bash
+gem install --user-install carson -v 1.0.0
+```
+
+If `carson` is not found after installation:
+
+```bash
+export PATH="$(ruby -e 'print Gem.user_dir')/bin:$PATH"
+```
+
+Verify installation:
+
+```bash
+carson version
+```
+
+Expected result:
+- Carson version is printed.
+- The `carson` command is available in your shell.
+
+## Configure your first repository
+Assume your repository path is `/local/path/of/repo`.
+
+Prepare your global lint policy baseline first:
+
+```bash
+carson lint setup --source /path/to/ai-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.
+
+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.
+
+Run baseline initialisation:
+
+```bash
+carson init /local/path/of/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
+
+After `init`, commit generated `.github/*` changes in your repository.
+
+## Pin Carson in CI
+Use the reusable workflow with explicit release pins:
+
+```yaml
+name: Carson policy
+
+on:
+  pull_request:
+
+jobs:
+  governance:
+    uses: wanghailei/carson/.github/workflows/carson_policy.yml.8.1
+    secrets:
+      CARSON_READ_TOKEN: ${{ secrets.CARSON_READ_TOKEN }}
+    with:
+      carson_ref: "v1.0.0"
+      carson_version: "1.0.0"
+      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.
+
+## Daily operations
+Start of work:
+
+```bash
+carson sync
+carson lint setup --source /path/to/ai-policy-repo
+carson audit
+```
+
+Before push or PR update:
+
+```bash
+carson audit
+carson template check
+```
+
+If template drift is detected:
+
+```bash
+carson template apply
+```
+
+Before merge recommendation:
+
+```bash
+gh pr list --state open --limit 50
+carson review gate
+```
+
+Scheduled late-review monitoring:
+
+```bash
+carson review sweep
+```
+
+Local branch clean-up:
+
+```bash
+carson prune
+```
+
+## Exit contract
+- `0`: success
+- `1`: runtime or configuration error
+- `2`: policy blocked (hard stop)
+
+Treat exit `2` as a mandatory stop until the policy violation is resolved.
+
+## Troubleshooting
+`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
+- Respond with a valid disposition comment using the required prefix.
+- Re-run `carson review gate`.
+
+Template drift blocks
+
+```bash
+carson template apply
+carson template check
+```
+
+## Offboard from a repository
+To retire Carson from a repository:
+
+```bash
+carson offboard /local/path/of/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`
+- Release notes: `RELEASE.md`

data/README.md

@@ -0,0 +1,48 @@
+# Carson
+
+Carson is an outsider governance runtime for teams that need predictable GitHub policy controls without placing Carson-owned tooling inside client repositories.
+
+## Introduction
+Repository governance often drifts over time: local protections weaken, review actions are missed, and policy checks become inconsistent between contributors.
+Carson solves this by running from your workstation or CI, applying a deterministic governance baseline, and managing only selected GitHub-native policy files where necessary.
+This model is effective because ownership stays explicit: Carson runtime assets remain outside host repositories, while merge authority remains with GitHub branch protection and human review.
+
+## Quickstart
+Prerequisites:
+- Ruby `>= 4.0`
+- `gem` and `git` available in `PATH`
+- `gh` available in `PATH` for PR/check reporting (recommended, not required for core local commands)
+
+```bash
+gem install --user-install carson -v 1.0.0
+carson version
+carson lint setup --source /path/to/ai-policy-repo
+carson init /local/path/of/repo
+```
+
+Expected result:
+- `carson version` prints `1.0.0` (or newer).
+- `carson lint setup` seeds `~/AI/CODING` from your explicit source.
+- Ruby lint policy data is sourced from `~/AI/CODING/rubocop.yml`; Ruby lint execution stays Carson-owned.
+- Policy files live directly under `~/AI/CODING/` (no per-language subdirectories).
+- `carson init` aligns remote naming, installs Carson-managed hooks, synchronises managed `.github/*` files, and runs an initial audit.
+- Your repository is ready for daily governance commands.
+
+## Where to Read Next
+- User manual: `MANUAL.md`
+- API reference: `API.md`
+- Release notes: `RELEASE.md`
+
+## Core Capabilities
+- Outsider boundary enforcement that blocks Carson-owned host artefacts (`.carson.yml`, `bin/carson`, `.tools/carson/*`).
+- Deterministic governance checks with stable exit codes for local and CI automation.
+- Ruby lint governance from `~/AI/CODING/rubocop.yml` with Carson-owned execution and deterministic local/CI blocking.
+- Hard policy block when a client repository contains repo-local `.rubocop.yml`.
+- Non-Ruby lint language entries remain present but disabled by default in this phase.
+- Managed `.github/*` template synchronisation with drift detection and repair.
+- Review governance controls (`review gate`, `review sweep`) for actionable feedback handling.
+- Local branch hygiene and fast-forward sync workflow (`sync`, `prune`).
+
+## Support
+- Open or track issues: <https://github.com/wanghailei/carson/issues>
+- Review version-specific upgrade actions: `RELEASE.md`