carson 3.30.1 → 3.30.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f1c9bdf439edf6f4c50dbf4c2640ec87cf0cf7f5aacd7960d16c2d32600a0c3
-  data.tar.gz: b82620a9e4524b9e08c7851f9de133967ce64284c7d2c57a71d87df7055ce8a1
+  metadata.gz: 414294f12e0a6e1560b7c60df2ee77676734a63f279e40675bd4d10b55660851
+  data.tar.gz: 2dafbe3def3939e75263fb47de9e474d073f083adbb8fb22ec997ff839727768
 SHA512:
-  metadata.gz: 9433570c67b8f8b793eba64969356c6ec92775515e8291079518b0be7a4f051183eb20e19d23e0d6456a38a95c875f06d9e6d7536b434c30ec69fe36d63b0c4e
-  data.tar.gz: 7b82e7e07750d8e0ac4d0502a95e86925e210c1cca5b0c0e33355604cc4910819f46c57b002c9b7d9fd8dd4c312b4bc4cfba26192875e1a23818498343a4b0d0
+  metadata.gz: fbc81621f5aa779bf26ef20316083c1e207266f99bbefaba4fa78eea4c475745c67f30410b66e4a29257ed88b54400068a8cfb6d40e1aabeda16615b9baad3bf
+  data.tar.gz: 973068e6d3e716f44e7a86fed848eeab6c5f26b95839e414061ed9f745ef5ed79a000ec60d753294cd27844bd6878beb14c3739ac24e4cdac04f2510592212d5

data/API.md

@@ -5,20 +5,25 @@ For operational usage and daily workflows, see `MANUAL.md`.
 
 ## Command interface
 
-Command form:
+Two-tier grammar:
 
 ```bash
-carson <command> [subcommand] [arguments]
+carson <command>                    # portfolio commands
+carson <repo> <command> [arguments] # repo-scoped commands (or from CWD)
 ```
 
+Portfolio commands: `list`, `onboard`, `offboard`, `refresh`, `version`.
+Repo-scoped commands: `carson <repo> <command>` or `carson <command>` when CWD is inside a governed repo.
+
 ### Setup commands
 
 | Command | Purpose |
 |---|---|
 | `carson setup` | Interactive quiz to configure remote, main branch, workflow, and canonical lint-policy path. Writes `~/.carson/config.json`. |
-| `carson onboard [repo_path]` | Apply one-command baseline setup for a target git repository. Auto-triggers `setup` on first run. Installs or refreshes Carson-managed global hooks. |
-| `carson refresh [repo_path]` | Re-apply hooks, templates, and audit after upgrading Carson. Auto-propagates template updates to the remote via worktree (branch workflow: PR on `carson/template-sync`; trunk workflow: push to main). |
-| `carson offboard [repo_path]` | Remove Carson-managed host artefacts, detach Carson hooks path, and deregister from `govern.repos`. |
+| `carson onboard <repo_path>` | Apply one-command baseline setup for a target git repository. Auto-triggers `setup` on first run. Installs or refreshes Carson-managed global hooks. |
+| `carson refresh` | Re-apply hooks, templates, and audit across all governed repos after upgrading Carson. Auto-propagates template updates to the remote via worktree (branch workflow: PR on `carson/template-sync`; trunk workflow: push to main). Skips repos with active worktrees or uncommitted changes. |
+| `carson offboard <repo_path>` | Remove Carson-managed host artefacts, detach Carson hooks path, and deregister from `govern.repos`. |
+| `carson list [--json]` | List all governed repositories. |
 
 ### Daily commands
 
@@ -38,33 +43,17 @@ carson <command> [subcommand] [arguments]
 | `carson worktree list [--json]` | Show every registered worktree with PR state and Carson's cleanup recommendation. |
 | `carson worktree remove <path_or_name>` | Remove a worktree safely and clean up its branch when allowed. |
 
-### Batch commands (Layer 2)
-
-All batch commands operate across every governed repository registered in `govern.repos`.
-
-| Command | Purpose |
-|---|---|
-| `carson refresh --all` | Re-apply hooks, templates, and audit across all governed repos. Skips repos with active worktrees or uncommitted changes. |
-| `carson audit --all` | Run governance audit across all governed repos. Reports pass/block/fail per repo. |
-| `carson sync --all` | Sync main branch across all governed repos. |
-| `carson prune --all` | Remove stale branches across all governed repos. |
-| `carson status --all [--json]` | Portfolio-wide delivery overview per governed repository. |
-| `carson template check --all` | Read-only template drift detection across all governed repos. |
-| `carson housekeep --all [--loop SECONDS]` | Attempt sync, then reap worktrees with strong abandonment evidence, reconcile integrated delivery worktree records from the ledger, and prune across all governed repos. Safe cleanup still runs when sync is blocked. |
-
-`--loop SECONDS` runs the housekeep cycle continuously, sleeping SECONDS between cycles. It requires `--all`, accepts only positive integers, and exits cleanly on `Ctrl-C` or `SIGTERM` with a cycle count summary.
-
-### Govern commands
+### Receive commands
 
 | Command | Purpose |
 |---|---|
-| `carson govern [--dry-run] [--json] [--loop SECONDS]` | Portfolio-level delivery oversight: assess active deliveries, integrate ready branches, dispatch revisions, and escalate blocked work. Live integrated rows include merge proof. |
+| `carson <repo> receive [--dry-run] [--json] [--loop SECONDS]` | Single-repo delivery triage: assess active deliveries, integrate ready branches, dispatch revisions, and escalate blocked work. Live integrated rows include merge proof. |
 
-`--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` or `SIGTERM` cleanly exits with a cycle count summary. SECONDS must be a positive integer.
+`--loop SECONDS` runs the receive cycle continuously, sleeping SECONDS between cycles. The loop isolates errors per cycle — a single failing cycle does not stop the daemon. `Ctrl-C` or `SIGTERM` cleanly exits with a cycle count summary. SECONDS must be a positive integer.
 
 Governed integration is fixed to `squash`. Non-squash `govern.merge.method` values are rejected by config validation.
 
-After a live integration attempt, govern reports the actual outcome. Failed merges stay held at gate instead of being reported as integrated.
+After a live integration attempt, receive reports the actual outcome. Failed merges stay held at gate instead of being reported as integrated.
 
 After CI and review pass, Carson still checks GitHub mergeability. Conflicting PRs exit as `Merge blocked` with an explicit merge-conflict summary. `BEHIND` is treated as freshness failure: Carson blocks and requires a branch refresh before it will continue.
 
@@ -93,9 +82,9 @@ In `--json` mode, `deliver` still suppresses human output. Every JSON result now
 }
 ```
 
-On `main`, `branch.merge_proof` is still present with `basis: "not_applicable"`. On non-main branches with no Carson delivery record, `branch.pull_request` and `branch.merge_proof` are `null`. `status --all` remains summary-only in v1 and does not include per-repo merge proof.
+On `main`, `branch.merge_proof` is still present with `basis: "not_applicable"`. On non-main branches with no Carson delivery record, `branch.pull_request` and `branch.merge_proof` are `null`.
 
-After a successful govern merge, Carson runs the same cleanup path as `housekeep`: sync, reap safe worktrees, then prune.
+After a successful receive merge, Carson runs the same cleanup path as `housekeep`: sync, reap safe worktrees, then prune.
 
 ### Review commands
 

data/MANUAL.md

@@ -130,7 +130,7 @@ These strategies are the audit lens for Carson. If behaviour departs from them,
 - **Main-tree protection** — on the governed main working tree, Carson blocks `git add` and `git commit` until the agent creates a Carson worktree for the task.
 - **Governed delivery** — completed work returns to shared truth through remote `main` via PR-based delivery. Carson owns the landing path.
 - **Active review gating** — when the repo uses PR-based delivery, review findings must be acknowledged before merge. Feedback is never silently buried.
-- **Portfolio triage** — `carson govern` applies the same discipline across multiple repositories: classify, merge, dispatch, or escalate.
+- **Portfolio triage** — `carson receive` applies the same discipline across multiple repositories: classify, merge, dispatch, or escalate.
 - **Template propagation** — Carson treats canonical policy files as managed infrastructure and keeps them consistent across repos.
 
 ### Safety Strategies
@@ -166,11 +166,11 @@ carson deliver --commit "fix: describe this delivery"
 # Output: merged into main, or an explicit deferred/blocked handoff
 ```
 
-**4. Inspect or wait when needed** — when `deliver` cannot merge immediately, Carson tells you whether the PR was deferred or blocked, whether merge was attempted, and which command to run next. `status` still shows the current branch, the next queued delivery, and blocked-delivery summaries for the repository. When the current branch has a Carson delivery record, `status` also shows Carson's last observed PR state and merge proof. Keep `govern` running when you want unattended portfolio reassessment and revision dispatch across governed repositories:
+**4. Inspect or wait when needed** — when `deliver` cannot merge immediately, Carson tells you whether the PR was deferred or blocked, whether merge was attempted, and which command to run next. `status` still shows the current branch, the next queued delivery, and blocked-delivery summaries for the repository. When the current branch has a Carson delivery record, `status` also shows Carson's last observed PR state and merge proof. Keep `receive` running when you want unattended portfolio reassessment and revision dispatch across governed repositories:
 
 ```bash
 carson status
-carson govern --loop 300
+carson receive --loop 300
 ```
 
 ### Recover a baseline-red governance check
@@ -280,28 +280,18 @@ carson review gate
 **Portfolio overview:**
 
 ```bash
-carson repos           # list all governed repositories
-carson repos --json    # machine-readable output
-carson status --all    # branch, worktrees, governance per repo
+carson list             # list all governed repositories
+carson list --json      # machine-readable output
 ```
 
-**Portfolio maintenance (Layer 2):**
-
-All `--all` commands run across every governed repository registered via `carson onboard`.
+**Portfolio maintenance:**
 
 ```bash
-carson refresh --all           # re-apply hooks, templates, audit across all repos
-carson sync --all              # fast-forward main across all repos
-carson audit --all             # governance audit across all repos
-carson prune --all             # remove stale branches across all repos
-carson template check --all    # detect template drift across all repos
-carson housekeep --all         # full maintenance cycle across all repos
-carson housekeep --all --loop 300   # housekeep every 5 minutes
+carson refresh                 # re-apply hooks, templates, audit across all repos
+carson list                    # list all governed repositories
 ```
 
-`refresh --all` checks each repo for safety before operating: repos with active worktrees or uncommitted changes are skipped with clear reasons. Other batch commands attempt each repo and report failures without stopping.
-
-`housekeep --all --loop SECONDS` runs the full housekeep cycle continuously, sleeping SECONDS between passes. It requires `--all`, accepts only positive integers, and exits cleanly on `Ctrl-C` or `SIGTERM` with a cycle count summary.
+`refresh` checks each repo for safety before operating: repos with active worktrees or uncommitted changes are skipped with clear reasons. Use `carson list --json` to script batch operations across governed repositories.
 
 **Periodic maintenance:**
 
@@ -310,28 +300,28 @@ carson review sweep    # update tracking issue for late review feedback
 carson prune           # remove stale local branches
 ```
 
-## Running Carson Govern Continuously
+## Running Carson Receive Continuously
 
-Use `--loop SECONDS` to run `carson govern` as a persistent daemon that cycles on a schedule:
+Use `--loop SECONDS` to run `carson receive` as a persistent daemon that cycles on a schedule:
 
 ```bash
-carson govern --loop 300              # cycle every 5 minutes
-carson govern --loop 300 --dry-run    # observe mode, no integration or revision dispatch
+carson receive --loop 300              # cycle every 5 minutes
+carson receive --loop 300 --dry-run    # observe mode, no integration or revision dispatch
 ```
 
 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` or send `SIGTERM` to stop — Carson exits cleanly with a cycle count summary.
 
-### Govern and Coding Agents
+### Receive and Coding Agents
 
-`carson govern` dispatches coding agents (Codex or Claude) when an active delivery is blocked by CI, review, or policy feedback. The agent receives the failure context and attempts a revision. If the agent succeeds, the delivery re-enters the governance pipeline. If it fails repeatedly or times out, the delivery is escalated for human attention.
+`carson receive` dispatches coding agents (Codex or Claude) when an active delivery is blocked by CI, review, or policy feedback. The agent receives the failure context and attempts a revision. If the agent succeeds, the delivery re-enters the governance pipeline. If it fails repeatedly or times out, the delivery is escalated for human attention.
 
-After a live merge attempt, govern reports the actual outcome. Failed merges stay held at gate instead of being reported as integrated. Successful integrations also report merge proof for the landed branch.
+After a live merge attempt, receive reports the actual outcome. Failed merges stay held at gate instead of being reported as integrated. Successful integrations also report merge proof for the landed branch.
 
 After CI and review pass, Carson still checks GitHub mergeability. Conflicting PRs exit as `Merge blocked` with an explicit merge-conflict summary. `BEHIND` is treated as a freshness failure, not a harmless squash detail: Carson blocks and requires a branch refresh before it will continue.
 
-After a successful govern merge, Carson runs the same cleanup path as `carson housekeep`: sync, reap safe worktrees, then prune.
+After a successful receive merge, Carson runs the same cleanup path as `carson housekeep`: sync, reap safe worktrees, then prune.
 
 The agent provider is configurable via `govern.agent.provider` (`auto`, `codex`, or `claude`). In `auto` mode, Carson selects the first available provider.
 
@@ -467,8 +457,7 @@ carson template check
 ```
 
 **Hook version mismatch after upgrade**
-- Run `carson refresh` to re-apply hooks and templates for the new Carson version.
-- Run `carson refresh --all` to refresh all governed repositories at once.
+- Run `carson refresh` to re-apply hooks and templates for all governed repositories.
 
 **Template auto-propagation**
 
@@ -487,7 +476,7 @@ To retire Carson from a repository:
 carson offboard /path/to/your-repo
 ```
 
-This removes Carson-managed host artefacts, unsets `core.hooksPath` when it points to Carson-managed global hooks, and deregisters the repository from `govern.repos` so `carson govern` and `carson refresh --all` no longer target it.
+This removes Carson-managed host artefacts, unsets `core.hooksPath` when it points to Carson-managed global hooks, and deregisters the repository from `govern.repos` so `carson receive` and `carson refresh` no longer target it.
 
 ## Related Documents
 

data/README.md

@@ -27,7 +27,7 @@ Carson lives on your workstation and in CI, never inside the repositories it gov
        │
        ├─ hooks ──────────────►  commit gates and command guards
        ├─ worktree flow ──────►  create → work → deliver → housekeep
-       └─ portfolio layer ────►  status --all | refresh --all | govern
+       └─ portfolio layer ────►  list | refresh | receive
 ```
 
 The outsider boundary still matters: Carson governs repositories without becoming a runtime dependency inside them.
@@ -75,12 +75,12 @@ When one Carson-governed required check is already red on the default branch and
 Single-repo depth comes first. Once multiple repositories are onboarded, the same discipline scales out across them:
 
 ```bash
-carson status --all
-carson refresh --all
-carson govern --dry-run
+carson list
+carson refresh
+carson receive --dry-run
 ```
 
-`carson govern` is the portfolio layer. It assesses active deliveries across governed repositories, integrates ready branches, dispatches revisions for blocked work, and escalates what still needs human judgement. Governed integration is squash-only and happens one repository at a time.
+`carson <repo> receive` triages active deliveries for one repository: integrates ready branches, dispatches revisions for blocked work, and escalates what still needs human judgement. Governed integration is squash-only. Use `carson list --json` to script receive across your portfolio.
 
 ## Where to Read Next
 

data/RELEASE.md

@@ -5,6 +5,40 @@ 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`.
 
+## Unreleased
+
+### Breaking
+
+- CLI grammar is now two-tier: portfolio commands (`list`, `onboard`, `offboard`, `refresh`, `version`) and repo-scoped commands (`carson <repo> <command>` or `carson <command>` from CWD)
+- `govern` renamed to `receive` — single-repo only, no portfolio iteration
+- `repos` renamed to `list`
+- `--all` removed from all repo commands; use `carson list --json` to script batch operations
+- `refresh` is now portfolio-only (always refreshes all governed repos)
+
+## 3.30.3
+
+### What changed
+
+- **Worktree branch resolution fixed** — `carson deliver` (and all other repo commands) now correctly resolve the current branch when running from inside a worktree. Previously, the CLI canonicalised the worktree path to the main tree root, causing the Git adapter to run all commands from the main tree. This meant `current_branch` returned `main` instead of the worktree's branch, blocking delivery with a false "cannot deliver from main" error.
+- **`onboard`/`offboard` use specified repo path** — Portfolio commands with a `<repo_path>` argument now use that path for the Runtime, not the invoking CWD. Previously the argument was parsed but ignored.
+- **`main_worktree_context?` correctly detects worktrees** — The dirty-tree audit guard now compares the actual working directory against the main worktree root, preventing false "main working tree has uncommitted changes" blocks when working in a worktree.
+- **CI smoke tests aligned with CWD governance** — All smoke test repos are now registered as governed, `offboard` calls pass the required `<repo_path>` argument, and legacy `govern` references are updated to `receive`.
+
+### No migration required
+
+- Existing workflows continue to work unchanged.
+
+## 3.30.2
+
+### What changed
+
+- **Recovery hints re-enter through Carson, not blocked raw commands** — Delivery error recovery messages no longer suggest raw `gh pr create`, `gh pr merge`, or `git rebase` commands. All recovery paths now guide the user back through Carson. Freshness blocks say "refresh this branch onto the target, then `carson deliver`" instead of teaching raw git recipes.
+- **Fast PR indentation guard restored** — The Ruby indentation guard in CI now correctly handles access modifier detection, fixing false positives that blocked PRs.
+
+### No migration required
+
+- Existing workflows continue to work unchanged.
+
 ## 3.30.1
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-3.30.1
+3.30.3

data/carson.gemspec

@@ -29,7 +29,7 @@ Gem::Specification.new do |spec|
 	spec.executables = [ "carson" ]
 	spec.require_paths = [ "lib" ]
 	spec.add_dependency "sqlite3", ">= 1.3", "< 3"
-	spec.files = Dir.glob( "{lib,exe,templates,hooks}/**/*", File::FNM_DOTMATCH ).select { |path| File.file?( path ) } + [
+	spec.files = Dir.glob( "{lib,exe,templates,config}/**/*", File::FNM_DOTMATCH ).select { |path| File.file?( path ) } + [
 		".github/workflows/carson_policy.yml",
 		"README.md",
 		"MANUAL.md",