Synced from Hive. This page is pulled from kubestellar/hive@v4 during the docs build. Edit the canonical source in the Hive repository.

ACMM Policy Matrix

Policy Modes

Each agent runs in of four modes, controlling what actions it can take on GitHub.

• 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 for the end-to-end workflow and API reference.

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.

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.

L4 — Security-Aware (Adaptive) (7 agents)

Delivery agents open GitHub issues — bugs, docs gaps, CI problems, security vulnerabilities. Quality, sec-check, and ci-maintainer may open PRs. Security agent joins.

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.

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.

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 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) 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 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:

governor:
  acmm:
    issue_tracker: work_source   # "" | github | work_source (default github)

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 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:

{"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 page for the exact thresholds per target level and what the GET /api/acmm-recommendation endpoint returns.