hivecommons-hive · Aug 29, 2026 · Aug 29, 2026
@@ -0,0 +1,205 @@
+> **Synced from Hive.** This page is pulled from [kubestellar/hive@v4](https://github.com/kubestellar/hive/blob/v4/src/docs/acmm-policy-matrix.md) during the docs build. Edit the canonical source in the Hive repository.
+
+# ACMM Policy Matrix
+
+## Policy Modes
+
+Each agent runs in one of four modes, controlling what actions it can take on GitHub.
+
+| Mode | Suffix | Beads | Issues | PRs | Merge | GH Auth |
+|------|--------|-------|--------|-----|-------|---------|
+| **Advisory** | `-advisory.md` | Yes | No | No | No | No |
+| **Measured** | `-measured.md` | Yes | Yes | No | No | Yes |
+| **Holdgated** | `-holdgated.md` | Yes | Yes | Yes + `hold` label | No | Yes |
+| **Full** | `-full.md` | Yes | Yes | Yes | Yes (auto on green CI) | Yes |
+
+- **Advisory**: Agent observes and records findings as beads on the dashboard. No GitHub interaction.
+- **Measured**: Agent can file GitHub issues to make findings visible to the team. No code changes.
+- **Holdgated**: Agent can write code and open PRs, but every PR gets a `hold` label. A human must review and remove `hold` before merge. Agent never merges.
+- **Full**: Agent operates autonomously — opens PRs and merges on green CI. Highest trust level.
+
+## ACMM Levels
+
+### L1 — Inception (Assisted) (2 agents)
+
+A single interactive advisor helps with repo setup and architecture decisions. Guide agent makes advisory beads. Brainstorm agent handles project inception — turning raw ideas into structured KB facts and scaffold. No feedback loops. See the [Inception operator guide](https://github.com/kubestellar/hive/blob/v4/src/docs/inception.md) for the end-to-end workflow and API reference.
+
+| Agent | Mode | Template |
+|-------|------|----------|
+| guide | advisory | `guide-advisory.md` |
+| brainstorm | advisory | `brainstorm-advisory.md` |
+
+### L2 — Advisory (Instructed) (5 agents)
+
+Agents observe and report findings as advisory beads on the dashboard and tracking issue. No GitHub issues or PRs created. Humans decide what to act on.
+
+| Agent | Mode | Template |
+|-------|------|----------|
+| supervisor | advisory | `supervisor-nogithub.md` |
+| scanner | advisory | `scanner-advisory.md` |
+| quality | advisory | `quality-advisory.md` |
+| guide | advisory | `guide-advisory.md` |
+| brainstorm | advisory | `brainstorm-advisory.md` |
+
+### L3 — Quality-Gated (Measured) (6 agents)
+
+Quality agent opens GitHub issues and PRs about testing gaps, coverage, and CI workflows. All other agents remain advisory. CI-maintainer joins to monitor build health. Key artifact: measurement infrastructure.
+
+| Agent | Mode | Template |
+|-------|------|----------|
+| supervisor | advisory | `supervisor-nogithub.md` |
+| scanner | advisory | `scanner-advisory.md` |
+| ci-maintainer | advisory | `ci-maintainer-advisory.md` |
+| **quality** | **holdgated** | `quality-holdgated.md` |
+| guide | advisory | `guide-advisory.md` |
+| brainstorm | advisory | `brainstorm-advisory.md` |
+
+### L4 — Security-Aware (Adaptive) (7 agents)
+
+Delivery agents open GitHub issues — bugs, docs gaps, CI problems, security vulnerabilities. Only Quality, sec-check, and ci-maintainer may open PRs. Security agent joins.
+
+| Agent | Mode | Template |
+|-------|------|----------|
+| supervisor | advisory | `supervisor-nogithub.md` |
+| scanner | measured | `scanner-issues.md` |
+| ci-maintainer | holdgated | `ci-maintainer-holdgated.md` |
+| **quality** | **holdgated** | `quality-holdgated.md` |
+| guide | measured | `guide-issues.md` |
+| **sec-check** | **holdgated** | `sec-check-holdgated.md` |
+| brainstorm | advisory | `brainstorm-advisory.md` |
+
+### L5 — Semi-Autonomous (Semi-Automated) (11 agents)
+
+Agents open issues AND pull requests. All PRs get a hold label — humans batch-review and approve. Architect produces RFCs, strategist coordinates across agents. The system proposes; it does not merge autonomously.
+
+| Agent | Mode | Template |
+|-------|------|----------|
+| supervisor | advisory | `supervisor-nogithub.md` |
+| scanner | holdgated | `scanner-holdgated.md` |
+| ci-maintainer | holdgated | `ci-maintainer-holdgated.md` |
+| quality | holdgated | `quality-holdgated.md` |
+| guide | holdgated | `guide-holdgated.md` |
+| sec-check | holdgated | `sec-check-holdgated.md` |
+| architect | holdgated | `architect-holdgated.md` |
+| strategist | holdgated | `strategist-holdgated.md` |
+| telemetry (paused) | holdgated | `telemetry-holdgated.md` |
+| operations (paused) | holdgated | `operations-holdgated.md` |
+| brainstorm | advisory | `brainstorm-advisory.md` |
+
+### L6 — Fully Autonomous (12 agents)
+
+Existing autonomous lanes can open issues, create PRs, and auto-merge on green CI. No hold label. Outreach handles community engagement. Telemetry and operations remain paused and use `ISSUES_AND_PRS`, so they never merge their own PRs.
+
+| Agent | Mode | Template |
+|-------|------|----------|
+| supervisor | advisory | `supervisor-nogithub.md` |
+| scanner | full | `scanner-automerge.md` |
+| ci-maintainer | full | `ci-maintainer-full.md` |
+| quality | full | `quality-full.md` |
+| guide | full | `guide-full.md` |
+| sec-check | full | `sec-check-full.md` |
+| architect | full | `architect-full.md` |
+| strategist | full | `strategist-full.md` |
+| outreach | full | `outreach-full.md` |
+| telemetry (paused) | full | `telemetry-full.md` |
+| operations (paused) | full | `operations-full.md` |
+| brainstorm | advisory | `brainstorm-advisory.md` |
+
+## Example config alignment
+
+`src/hive.yaml.example` uses the built-in `quality` lane for automated test suites, coverage gates, and regression checks. There is no built-in `tester` lane in the ACMM packs, known-agent defaults, or shipped policy templates; operators who want a separate tester must define it as a custom agent with explicit metadata and a policy template.
+
+## Key Rules
+
+1. **All PRs are holdgated below L6.** No agent can auto-merge unless running at L6 (Fully Autonomous).
+2. **Advisory agents never get GH auth.** The `${GH_AUTH}` template variable is only injected into measured, holdgated, and full templates.
+3. **Supervisor uses no-GitHub advisory mode.** At every level, supervisor uses `supervisor-nogithub.md` in the built-in ACMM packs — it monitors agent health, not code.
+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. **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.
+
+## Where ACMM gap issues are filed
+
+The dashboard's ACMM evaluation lists each criterion a repo is missing, and
+the level dialog offers **Open Issue** (per criterion) and **Open All** (every
+failing criterion at that level). Both call `POST /api/acmm/issue`. By default
+the issue goes to the repo's **GitHub Issues** with the `acmm` and
+`ai-fix-requested` labels.
+
+A hive whose backlog lives in Linear (`governor.work_source.type: linear`) can
+file them there instead:
+
+```yaml
+governor:
+  acmm:
+    issue_tracker: work_source   # "" | github | work_source (default github)
+```
+
+| Value | Where the issue goes |
+|---|---|
+| `github` (or unset) | GitHub Issues on the criterion's repo — unchanged behavior. |
+| `work_source` | Wherever the backlog lives. Linear work source → Linear `issueCreate` on the team whose `teams[].repo` matches the criterion's repo (else the first team). GitHub / GitHub Projects / Jira / unset → GitHub Issues as above. |
+
+Any other value fails config validation at load time.
+
+The choice can also be made **per click**: the request body accepts an
+optional `tracker` field (`"github"` or `"work_source"`) that overrides the
+configured default for that one issue; an unknown value is a `400`. When the
+work source is Linear the level dialog shows a small **File in: GitHub /
+Linear** selector, pre-selected from the config, that sets this field. The
+response always says where the issue went:
+
+```json
+{"tracker": "linear", "issue_number": 42, "identifier": "ENG-42",
+ "issue_url": "https://linear.app/acme/issue/ENG-42/...", "team": "ENG"}
+```
+
+(`tracker: "github"` responses carry `issue_number` and `issue_url` as
+before.) `GET /api/acmm/evaluation` reports the effective default as
+`issue_tracker` (`github` | `linear`) plus `work_source_type`. Title and body
+are identical on both trackers; Linear uses `work_source.linear.api_key`, and
+the audit log records `tracker` alongside the URL either way.
+
+## Changing a hive's ACMM level
+
+Promoting or demoting a running hive between levels is a single operation — the
+hive reconciles its agent roster and per-agent modes to match the target level.
+
+**From the dashboard:** open the Governor config and set the ACMM level. This is
+the normal path.
+
+**Over the API:** `PUT /api/packs/level` with `{"level": N}` where N is 1–6.
+
+What happens when the level changes (`handlePackSetLevel` → `ApplyPack`):
+
+1. The new level is written to `acmm_level` in `hive.yaml` and persisted.
+2. Per-agent `mode` overrides are cleared so stale modes from the previous level
+   are not re-applied on the next config reload.
+3. `ApplyPack` cascades the target level's pack-defined agent fields (mode,
+   `kick_template`, description, …) into the live config **and reconciles the
+   roster** — adding every agent the level introduces (for example
+   architect/strategist at higher levels) and applying each agent's mode for
+   that level (advisory → measured → holdgated → full).
+
+Notes:
+
+- **Promotion adds agents and capability; demotion narrows it.** Moving up to L6
+  makes agents auto-merge on green CI; moving down returns them to holdgated or
+  advisory. The per-level capability grid is the table at the top of this page.
+- **Operator-created agents are preserved.** `ApplyPack` reconciles pack agents;
+  agents you created yourself are not removed by a level change (deletion is
+  tombstoned separately — see agent configuration).
+- On a hosted hive the level can also be hub/admin-managed; the ConfigMap seed is
+  authoritative for `acmm_level` on those (see the operator reference on config
+  precedence).
+
+## Automated level-up guidance
+
+A separate, advisory-only computation — the ACMM advisor (`pkg/acmmadvisor`) —
+can tell you whether a hive has earned progression to the next level, based on
+test coverage, green-CI streak, merge success rate, and backlog/hold signals.
+It never changes the applied level itself; changing the level is always the
+manual process described above. See the [ACMM advisor](https://github.com/kubestellar/hive/blob/v4/src/docs/acmm-advisor.md) page
+for the exact thresholds per target level and what the `GET
+/api/acmm-recommendation` endpoint returns.
@@ -0,0 +1,28 @@
+> **Synced from Hive.** This page is pulled from [kubestellar/hive@v4](https://github.com/kubestellar/hive/blob/v4/src/docs/adr/0001-record-architecture-decisions.md) during the docs build. Edit the canonical source in the Hive repository.
+
+# ADR-0001: Record architecture decisions
+
+Status: Accepted
+
+## 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
+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.
+
+## Decision
+
+Adopt lightweight ADRs under `src/docs/adr/`. Each ADR records one durable
+architecture decision with `Status`, `Context`, `Decision`, and `Consequences`.
+Retroactive ADRs may back-fill existing decisions when they are grounded in the
+reference architecture or code.
+
+## Consequences
+
+Future architectural changes have a stable place to record rationale without
+turning the reference architecture into a change log. ADRs are not a governance
+bottleneck: small implementation details can remain in PRs and code comments,
+while decisions that affect security boundaries, operator workflows, or public
+interfaces should get an ADR.
@@ -0,0 +1,36 @@
+> **Synced from Hive.** This page is pulled from [kubestellar/hive@v4](https://github.com/kubestellar/hive/blob/v4/src/docs/adr/0002-mitm-proxy-network-enforcement.md) during the docs build. Edit the canonical source in the Hive repository.
+
+# ADR-0002: MITM proxy network enforcement
+
+Status: Accepted (retroactive)
+
+## Context
+
+Hive agents can run powerful coding CLIs in tmux sessions. A malicious prompt or
+compromised agent may try to bypass shell wrappers and call GitHub APIs directly.
+The reference architecture therefore defines three guardrail layers keyed by the
+same per-agent mode: CLI tool-deny, scoped credentials, and a MITM GitHub proxy
+([architecture §5](/docs/hive/architecture#5-layered-guardrails-defense-in-depth)).
+The deterministic pipeline and merge gate produce the list of PRs that may merge
+([architecture §4](/docs/hive/architecture#4-the-deterministic-pipeline)).
+
+## Decision
+
+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
+`POST /pulls` and `PUT /pulls/{n}/merge` paths so those operations use Hive
+relays, and applies a configured repo allowlist. GraphQL mutations are
+mode-classified to the closest REST capability tier. Read-only GitHub requests
+remain available
+at advisory mode; `github.com` is tunneled opaquely for OAuth/git smart HTTP as
+documented in the architecture.
+
+## Consequences
+
+Network enforcement remains independent of prompt instructions and CLI wrapper
+behavior, so a bypass in one layer is still caught by another. The proxy also
+provides an auditable block point (`X-Hive-Proxy-Blocked`) and a place to close
+GraphQL/REST parity gaps. The trade-off is operational complexity: the container
+must install/trust a local CA, iptables redirection must work, and future GitHub
+write paths need explicit rules or relay handling.
@@ -0,0 +1,32 @@
+> **Synced from Hive.** This page is pulled from [kubestellar/hive@v4](https://github.com/kubestellar/hive/blob/v4/src/docs/adr/0003-acmm-autonomy-levels.md) during the docs build. Edit the canonical source in the Hive repository.
+
+# ADR-0003: ACMM autonomy levels
+
+Status: Accepted (retroactive)
+
+## Context
+
+Hive needs one operator-facing control for how autonomous agents may be. The
+reference architecture describes ACMM as the human-selected dial that maps to
+per-agent modes, and the policy matrix defines which agents may only advise,
+file issues, open hold-gated PRs, or auto-merge at each level
+([architecture §6](/docs/hive/architecture#6-acmm-controlling-agent-autonomy),
+[ACMM policy matrix](/docs/hive/acmm-policy-matrix)). The same modes feed the
+layered guardrails in [architecture §5](/docs/hive/architecture#5-layered-guardrails-defense-in-depth).
+
+## Decision
+
+Use ACMM levels L1-L6 as the public autonomy model. Levels map
+deterministically to per-agent modes: advisory, issues-only/measured,
+issues-and-PRs/holdgated, and issues-PRs-merge/full. Raising the level is a
+human decision. `supervisor` remains advisory at every level, and `brainstorm`
+never receives GitHub write authority.
+
+## Consequences
+
+Operators can reason about fleet risk through one level instead of many
+independent toggles. The same mode value drives prompt templates, credential
+scope, CLI deny lists, and proxy rules, which reduces configuration drift. The
+cost is that unusual deployments may need explicit per-agent overrides, and any
+new agent role must be placed deliberately in the matrix before it receives
+write or merge authority.
@@ -0,0 +1,31 @@
+> **Synced from Hive.** This page is pulled from [kubestellar/hive@v4](https://github.com/kubestellar/hive/blob/v4/src/docs/adr/0004-beads-work-ledger.md) during the docs build. Edit the canonical source in the Hive repository.
+
+# ADR-0004: Beads work ledger
+
+Status: Accepted (retroactive)
+
+## Context
+
+Hive agents need durable coordination state that is separate from GitHub's issue
+queue. The reference architecture describes beads as a git-backed JSON ledger
+per agent, with typed work items, priorities, dependencies, metadata, and
+actor-scoped ready queues ([architecture §7](/docs/hive/architecture#7-beads-the-work-ledger)).
+The deterministic pipeline can turn GitHub work into internal artifacts before
+agents act ([architecture §4](/docs/hive/architecture#4-the-deterministic-pipeline)).
+
+## Decision
+
+Use beads as Hive's internal work ledger. Agents claim ready work with their
+actor identity, record progress and dependencies in the ledger, and close beads
+when associated work is merged or otherwise complete. Advisory findings and
+blocked-write observations stay in the ledger/governor digest rather than being
+mirrored automatically to GitHub.
+
+## Consequences
+
+Hive gains a durable, inspectable coordination layer without requiring a central
+queue service. Agents can coordinate on dependencies and priorities even when the
+external GitHub issue does not map one-to-one to internal tasks. The trade-off is
+that operators must understand both GitHub issues/PRs and beads: beads are
+source-of-truth for internal agent work, while GitHub remains the public project
+interface.
@@ -0,0 +1,36 @@
+> **Synced from Hive.** This page is pulled from [kubestellar/hive@v4](https://github.com/kubestellar/hive/blob/v4/src/docs/adr/0005-forge-abstraction.md) during the docs build. Edit the canonical source in the Hive repository.
+
+# ADR-0005: Forge-neutral source control interface
+
+Status: Accepted (retroactive)
+
+## Context
+
+Hive's first production paths were GitHub-shaped, but the v4 package model
+needs agents and schedulers to reason about work without baking GitHub names
+into every interface. The forge package defines this boundary explicitly: it is
+"not hardcoded to GitHub" and exposes neutral repositories, issues, and change
+requests while concrete adapters handle GitHub, GitLab, and Gitea/Forgejo
+details ([forge package](https://github.com/kubestellar/hive/blob/v4/src/pkg/forge/forge.go)).
+
+## Decision
+
+Use a small `Forge` interface and forge-neutral data types (`Repo`, `Issue`,
+and `ChangeRequest`) for the common read path and safe write path. The interface
+covers repo lookup, open issue and change-request enumeration, comments,
+labels, and a neutral `SetHold` gate. `NewForge` selects a concrete adapter by
+kind, defaulting an empty kind to GitHub for existing deployments.
+
+Keep merge out of the core interface for now. `MergeOptions` and the optional
+`Merger` extension document the intended shape, but no adapter is required to
+pretend that GitHub merge methods, GitLab merge-request options, and Gitea merge
+styles are already neutral.
+
+## Consequences
+
+Most Hive code can depend on the work-item model instead of GitHub-specific API
+types, which makes GitLab and Forgejo support additive rather than a fork of the
+scheduler. The hold label gives the system one cross-forge merge gate primitive.
+The trade-off is an intentionally incomplete abstraction: callers that need a
+real merge still use a forge-specific client until Hive has enough semantics to
+standardize that operation honestly.