hivecommons-hive · Oct 31, 2026 · Oct 31, 2026 · Oct 31, 2026 · Oct 31, 2026
@@ -49,7 +49,7 @@ brew install hivecommons/hive/crux
 go install github.com/hivecommons/crux/cmd/crux@latest
 
 # Container image (amd64 and arm64; tmux is already inside)
-docker run --rm ghcr.io/hivecommons/crux:0.1.0 --help
+docker run --rm ghcr.io/hivecommons/crux:0.2.0 --help
 ```
 
 Or download a release archive from the
@@ -62,13 +62,13 @@ flags below are required: cosign refuses to run without them, and a
 wildcard would accept a signature from anyone. To check:
 
 ```sh
-# from the v0.1.0 release page, download these three files first
+# from the v0.2.0 release page, download these three files first
 cosign verify-blob checksums.txt \
   --bundle checksums.txt.sigstore.json \
   --certificate-identity-regexp '^https://github\.com/hivecommons/crux/\.github/workflows/release\.yml@' \
   --certificate-oidc-issuer https://token.actions.githubusercontent.com
 sha256sum -c checksums.txt --ignore-missing
-tar xzf crux_0.1.0_linux_amd64.tar.gz
+tar xzf crux_0.2.0_linux_amd64.tar.gz
 ./crux --version
 ```
 
@@ -79,15 +79,15 @@ the selected archive against its signed checksum before extracting it:
 
 ```sh
 # Apple Silicon example; use darwin_amd64 in both places on Intel
-grep 'crux_0.1.0_darwin_arm64.tar.gz$' checksums.txt | shasum -a 256 -c -
-tar xzf crux_0.1.0_darwin_arm64.tar.gz
+grep 'crux_0.2.0_darwin_arm64.tar.gz$' checksums.txt | shasum -a 256 -c -
+tar xzf crux_0.2.0_darwin_arm64.tar.gz
 ./crux --version
 ```
 
 The container image is signed the same way:
 
 ```sh
-cosign verify ghcr.io/hivecommons/crux:0.1.0 \
+cosign verify ghcr.io/hivecommons/crux:0.2.0 \
   --certificate-identity-regexp '^https://github\.com/hivecommons/crux/\.github/workflows/release\.yml@' \
   --certificate-oidc-issuer https://token.actions.githubusercontent.com
 ```
@@ -124,7 +124,7 @@ From a second terminal, while it is running:
 
 ```sh
 crux ps                             # what is running
-crux logs scout -n 50               # the last 50 lines of its screen
+crux logs -n 50 scout               # the last 50 lines of its screen
 crux kick scout "look at issue 42"  # send it work
 crux stop scout                     # stop it
 ```
@@ -199,11 +199,12 @@ lists the controls, which ones belong to Crux, and what is still missing.
 
 Global flags: `--workdir`, `--defs` (same as `--config`), `--socket`,
 `--local`, `--server`, `--token`. Environment variables that stand in for
-them: `CRUX_DEFS`, `CRUX_SOCKET`, `CRUX_SERVER`, `CRUX_TOKEN`.
+them: `CRUX_DEFS`, `CRUX_SERVER`, `CRUX_TOKEN`. (`CRUX_SOCKET` is not used for
+the global `--socket`; it sets the listening socket for `crux serve --socket`.)
 
 ## Status
 
-Current release: v0.1.0. This is early software.
+Current release: v0.2.0. This is early software.
 
 What works today: the `crux` CLI (`run`, `ps`, `logs`, `kick`, `stop`),
 `crux serve` with its HTTP+JSON API and Go client, remote mode with

@@ -19,9 +19,11 @@ The root [`server.json`](https://github.com/hivecommons/dibs/blob/main/server.js
 Committing this file does not publish it; publication happens through the
 `MCP Registry` workflow described below.
 
-The listing is titled **Dibs (Hive Commons)** to distinguish it from the
-unrelated 1stDibs marketplace. Version `0.1.0` corresponds to the MCP
-implementation's `v0.1.0` in `pkg/mcpserver/server.go`. The endpoint uses
+The listing is titled **Dibs (Hive Commons)** to distinguish it from
+unrelated registry entries with the same name, such as the 1stDibs
+marketplace and other coding-agent tools called dibs. Version `0.1.0`
+corresponds to the MCP implementation's `v0.1.0` in
+`pkg/mcpserver/server.go`. The endpoint uses
 Streamable HTTP; no installable package is needed. Its optional, secret
 `Authorization` header takes the complete `Bearer <token>` value described
 in the [README](/docs/dibs/readme#token). Public ideas and repo venues can be read

@@ -175,8 +175,9 @@ Gemini CLI, Codex, and other MCP clients can submit ideas without leaving the ag
 
 Dibs is listed in the official MCP Registry as `dev.hivecommons/dibs`
 ([registry entry](https://registry.modelcontextprotocol.io/v0.1/servers?search=dev.hivecommons%2Fdibs)).
-Search for that full name: a plain `dibs` search also returns the unrelated
-1stDibs marketplace. How the listing is published is covered in
+Search for that full name: a plain `dibs` search also returns unrelated
+servers with the same name, including the 1stDibs marketplace and other
+coding-agent tools called dibs. How the listing is published is covered in
 [MCP Registry publishing](/docs/dibs/mcp-registry).
 
 Available tools:

@@ -11,9 +11,21 @@ catch mistakes are put in place. Hive enforces each level in code: the level
 decides which agents run, in which policy mode, with which GitHub permissions.
 Background: [the ACMM paper](https://arxiv.org/abs/2604.09388).
 
+**Terms used in the tables:** a **PR** is a pull request proposing a code
+change; **CI** is continuous integration (automated checks); **GH Auth** means
+GitHub credentials. **Beads** are internal work-ledger entries, not GitHub
+issues. The **KB** is the knowledge base of reusable facts; an **RFC** is a
+request for comments on a proposed design. For a first deployment's trust
+choices, start with [Securing your hive](/docs/hive/securing-your-hive).
+
 ## Policy Modes
 
-Each agent runs in one of four modes, controlling what actions it can take on GitHub.
+The four policy tiers below describe the main autonomy ladder. The roster also
+uses `issues-only` for measured/`ISSUES_ONLY` and `issues+prs` for
+`ISSUES_AND_PRS` (PR creation without merge authority). `converse` is an
+orthogonal comments/reviews capability, not a fifth autonomy level: the reviewer
+remains advisory but can authenticate to post reviews. Always read the role's
+level-specific qualifications, not just its template's `full` suffix.
 
 | Mode | Suffix | Beads | Issues | PRs | Merge | GH Auth |
 |------|--------|-------|--------|-----|-------|---------|
@@ -84,7 +96,22 @@ Delivery agents open GitHub issues — bugs, docs gaps, CI problems, security vu
 
 ### L5 — Semi-Autonomous (Semi-Automated) (14 agents)
 
-Agents open issues AND pull requests. Agent PRs get literal `hold` from the level gate — humans batch-review and approve. The dashboard `hive-pause/<hive-id>` label is a separate manual hold, and `hive/<hive-id>` is provenance only. Architect produces RFCs, strategist coordinates across agents, and reviewer works the hold-gated PR queue every 30 minutes, and adjudicator works escalated (`needs-human`) hive PRs through the reviewer lane every 30 minutes (recommend-close only; closing is operator-only below L6). Dedupe runs once a day, reads every open issue and PR, and posts one consolidation checklist issue per repository (near-duplicates, same-root-cause clusters, unlinked PR/issue pairs, already-resolved items), parked with `--needs-decision`; it never closes or edits anyone else's items. The system proposes; it does not merge autonomously.
+**Permission boundary:** agents open issues and PRs, but do not merge
+autonomously. Agent PRs get literal `hold` from the level gate for human
+batch-review and release. The dashboard `hive-pause/<hive-id>` is a separate
+manual hold; `hive/<hive-id>` records provenance only.
+
+**Specialist lanes:**
+
+- Architect produces RFCs; strategist coordinates across agents.
+- Reviewer works the hold-gated PR queue every 30 minutes.
+- Adjudicator works escalated (`needs-human`) Hive PRs through the reviewer
+  lane every 30 minutes. It may recommend closure, but below L6 only an operator
+  closes them.
+- Dedupe runs daily, reads all open issues/PRs, and posts one consolidation
+  checklist per repository (near-duplicates, common root causes, unlinked
+  PR/issue pairs and already-resolved items), parked with `--needs-decision`.
+  It never closes or edits anyone else's items.
 
 | Agent | Mode | Template |
 |-------|------|----------|
@@ -105,7 +132,56 @@ Agents open issues AND pull requests. Agent PRs get literal `hold` from the leve
 
 ### L6 — Autonomous (15 agents)
 
-Existing autonomous lanes can open issues, create PRs, and auto-merge on green CI. Auto-merge is off below L6; switching to L6 turns it on for every active repository, after which owners can toggle repositories individually. L6 PRs do not get the level hold, except outreach PRs into a repository the hive does not manage, which are still held for human review; outreach PRs into the hive's own repos auto-merge like any other lane's. Contributor PRs can merge through the contributor lane when the author has an operator-trusted tier or the conservative `auto_merge.contributor_tier.auto_promote_after_merged` clean-history ratchet admits them; reviewer verdict, CI, diff fences, soak and branch protection still apply. Hive never needs App Actions write for `action_required` workflow runs: when trusted same-repo bot/App/registry-trusted clanker PRs hit the workflow-approval banner, Hive posts `/ok-to-test` once per head and the repository's self-contained `hive-ok-to-test` workflow approves those runs with its `GITHUB_TOKEN`; if the workflow is absent or a `sentinel-alert` is present, Hive surfaces `workflow-approval-required:<ctx>` / stage 085 for a human decision. Outreach handles community engagement. Reviewer stays advisory unless the self-authored review gate is enforcing: `review.require_approval: true` (or `governor.review_gate.mode: enforce`) makes the App self-authored sweep require same-head aggregate approval, while `requires_human`/incomplete verdicts can be cleared by a trusted human's normal GitHub Approve review on that exact head. For Hive-authored PRs, `review.self_authored_decision_policy: resolve` (the default) lets the reviewer resolve every decision question itself except those in a named risk class (permissions/credentials, security, sensitive paths, data loss/irreversible, merge/trust policy, external side effects, licensing/legal, unverifiable) or marked `hive-decision-risk: high`; set `escalate` to park every decision question at 085. Swarm `changes_requested`/`reject` still requires a fix or direct human merge. Use actual holds or GitHub branch rules for a universal merge stop. Adjudicator is the reviewer lane: it repairs, de-escalates, or recommends closing (and may close) escalated `needs-human` hive PRs, and never merges. Dedupe posts the same daily consolidation checklist as at L5 and stays recommendation-only. Telemetry and operations remain paused and use `ISSUES_AND_PRS`, so they never merge their own PRs.
+**Permission boundary:** autonomous delivery lanes can open issues/PRs and
+eligible PRs can merge on green CI. Auto-merge is off below L6. Switching to
+L6 enables it for every active repository; owners can then toggle repositories
+individually. L6 does not remove other merge gates or grant every role merge
+authority.
+
+#### Destination and author exceptions
+
+- **Outreach:** no level hold for PRs into a repository managed by this hive.
+  Outreach PRs into another repository remain held for human review at every
+  level, including L6.
+- **Contributors:** the contributor lane admits operator-trusted authors or
+  those admitted by the conservative
+  `auto_merge.contributor_tier.auto_promote_after_merged` clean-history ratchet.
+  Review, CI, diff fences, soak and branch protection still apply.
+- **Nonmerging roles:** reviewer never merges. Adjudicator repairs,
+  de-escalates, recommends closure and may close escalated `needs-human` Hive
+  PRs at L6, but never merges. Dedupe stays recommendation-only. Telemetry and
+  operations stay paused and use `ISSUES_AND_PRS`, despite their `full`
+  template names; they never merge their own PRs.
+
+#### Review and decision gates
+
+The reviewer role remains advisory. Its verdict becomes an enforced merge gate
+when `review.require_approval: true` or `governor.review_gate.mode: enforce`
+is set. The App sweep checks current-head aggregate approval on self-authored,
+trusted-bot and trusted-author paths; it is not scanner-only.
+A trusted human merger's GitHub **Approve** review on that exact head can
+override any swarm outcome, including `changes_requested`/`reject`; the audit
+records who overrode which verdict. Other holds, CI, author admission, path
+fences and GitHub rules still bind. A head-bound `/hive decision approve`
+on an eligible Hive-authored PR can also answer `requires_human`; bare
+`/hive approve` cannot. See [the L6 gate contract](/docs/hive/running-at-level-6#does-the-hive-reviewer-stop-a-merge).
+
+For Hive-authored PRs, `review.self_authored_decision_policy: resolve`
+(default) lets the reviewer resolve non-risk decision questions. The exceptions
+are permissions/credentials, security, sensitive paths, data loss/irreversible
+actions, merge/trust policy, external side effects, licensing/legal,
+unverifiable claims, or `hive-decision-risk: high`. Set `escalate` to park
+every decision question at PR stage 085. Use actual holds or GitHub branch
+rules for a universal merge stop.
+
+#### Workflow approval, not App Actions-write permission
+
+For trusted same-repo bot/App/registry-trusted clanker PRs with
+`action_required` workflow runs, Hive posts `/ok-to-test` once per head.
+The repository's self-contained `hive-ok-to-test` workflow approves the runs
+using its own `GITHUB_TOKEN`; the App needs no Actions-write grant. If that
+workflow is missing or `sentinel-alert` is present, Hive surfaces
+`workflow-approval-required:<ctx>` / PR stage 085 for human action.
 
 | Agent | Mode | Template |
 |-------|------|----------|
@@ -170,7 +246,16 @@ predate hive's first sight of, or write access to, the repo.
 4. **Mode escalation is per-agent.** At L4, some agents are measured (issues only) while others are holdgated (issues + PRs). The level defines the mix.
 5. **Knowledge priming works at all levels.** The `${KNOWLEDGE}` template variable injects relevant facts from git sources and wiki layers regardless of the agent's mode.
 6. **Brainstorm is always advisory.** It produces KB facts and beads, never GitHub issues or PRs. Its role evolves from inception (L1) to ongoing ideation (L2+), but its mode stays advisory at all levels.
-7. **Reviewer is in every pack from L2 up and never merges.** It joined the L5 and L6 rosters in [#8023](https://github.com/hivecommons/hive/issues/8023) and the L2, L3 and L4 rosters in [#13574](https://github.com/hivecommons/hive/issues/13574) (community vote 2026-10-22: review-first entry point at L2 and every level above), at a 30-minute cadence in every governor mode. At L2 it is COMMENT-only; at L3 and L4 it reviews the `hold`-gated queue with exactly the authority those levels already grant — comment and route to a human, no lgtm/approve/merge. Only L1 (observe-only) omits it, so an operator who wants repo-grounded PR review there creates it by hand and a pack apply leaves that agent's mode, model, backend, and pause state alone. Its mode stays `ADVISORY` at every level, including L6: it reads the queue, comments, and returns a verdict. `requires_human` or `reject` stops scanner eligibility only when `review.require_approval: true` requires same-head approval; the App auto-merge sweep does not read those verdicts. Use a hold or GitHub branch rule when merging must stop. See [Running at Level 6](/docs/hive/running-at-level-6#does-the-hive-reviewer-stop-a-merge).
+7. **Reviewer is in every pack from L2 up and never merges.** It runs every
+   30 minutes in every governor mode. At L2 it is COMMENT-only; at L3/L4 it
+   comments on the held queue and routes to a human, with no lgtm/approve/merge
+   authority. L1 omits it; a manually created L1 reviewer's mode, model,
+   backend and pause state survive pack apply. Its mode remains `ADVISORY`,
+   including at L6. This role restriction is separate from the enforcing
+   review gate described above, which **does** read verdicts on the App sweep.
+   Use a hold or GitHub branch rule for a universal stop.
+   Roster history: [#8023](https://github.com/hivecommons/hive/issues/8023)
+   and [#13574](https://github.com/hivecommons/hive/issues/13574).
 8. **Telemetry and operations are L5/L6-only opt-in agents.** Below L5 they are absent from the pack roster and dashboard, do not spawn panes, and cannot be kicked. At L5–L6 they use a paused cadence in every governor mode until an operator opts in; they may open issues and PRs but never merge.
 
 ## ioscan hardening defaults per level
@@ -184,8 +269,8 @@ the pack only supplies the default when the hive leaves the key unset.
 | `ioscan.canaries` | **on** | **on** | Plants a per-kick `HIVE-CANARY-*` marker and scans agent egress for it. Default flipped on ([#7083](https://github.com/hivecommons/hive/issues/7083)) now that the egress scan is encoding-aware ([#6701](https://github.com/hivecommons/hive/issues/6701), [#6720](https://github.com/hivecommons/hive/issues/6720)). | `ioscan.canaries: false` |
 | `ioscan.fail_mode` | `open` | **`closed`** (set by the L5/L6 packs' `governor.ioscan_fail_mode`) | `open` redacts a Critical injection finding and continues the kick; `closed` blocks the kick and records an `ioscan_fail_closed` audit entry. | `ioscan.fail_mode: open` (or `closed` to opt in below L5) |
 
-`fail_mode: closed` is the default only at L5–L6 because those are the levels
-where agents can merge, so a Critical finding that slips through has the highest
+`fail_mode: closed` is the default only at L5–L6, where agent PR creation is
+broadest and L6 also permits merges, so a Critical finding that slips through has the highest
 blast radius. **The tradeoff is real and worth stating plainly: under `closed`,
 every Critical false-positive becomes a stalled queue item that an operator must
 clear by hand.** A hive that cannot absorb that operational load should set

@@ -4,11 +4,16 @@
 
 Status: Accepted
 
+An **Architecture Decision Record (ADR)** explains why a durable technical
+choice was made. This series is for maintainers; for setup and daily operation,
+start with the relevant operator guide.
+
 ## Context
 
 Hive's reference architecture documents the current system model, including the
-single-container process model, deterministic pipeline, layered guardrails, ACMM
-levels, beads ledger, hub/spoke topology, and observability surfaces. Those docs
+single-container process model, deterministic work pipeline, layered guardrails,
+[ACMM autonomy levels](/docs/hive/acmm-policy-matrix), the [beads work ledger](/docs/hive/adr/0004-beads-work-ledger),
+[hub/spoke fleet topology](/docs/hive/adr/0014-hub-spoke), and monitoring surfaces. Those docs
 explain how the system works, but they do not preserve why durable choices were
 made or what trade-offs future maintainers should keep in mind.
 

@@ -4,6 +4,15 @@
 
 Status: Accepted (retroactive)
 
+**MITM** means **man-in-the-middle**: a local proxy inspects agent requests to
+GitHub and blocks writes outside the agent's allowed mode. Here it is an
+intentional enforcement point, not an external attacker.
+
+**Prerequisites:** [ACMM](/docs/hive/acmm-policy-matrix) is the autonomy-level model.
+**Egress** means outgoing traffic; a local **CA** (certificate authority)
+lets the proxy inspect HTTPS, and **iptables** supplies the Linux traffic
+redirect. Installing a proxy alone does not force traffic through it.
+
 ## Context
 
 Hive agents can run powerful coding CLIs in tmux sessions. A malicious prompt or
@@ -16,6 +25,9 @@ The deterministic pipeline and merge gate produce the list of PRs that may merge
 
 ## Decision
 
+Enforce GitHub write permissions outside the model: route agent API traffic
+through a deny-by-default proxy, and reserve PR creation/merge for Hive's relays.
+
 Keep a local MITM proxy in the agent egress path for `api.github.com`. The proxy
 classifies REST and GraphQL requests by method/path/body and requires the
 minimum ACMM mode for each write. It denies unknown writes by default, hard-denies the REST