From e9d2b22ed59977388f0967a7c508c253392e5e48 Mon Sep 17 00:00:00 2001 From: vjymisal0 Date: Sat, 29 Aug 2026 14:18:34 +0530 Subject: [PATCH] fix(hive): sync correct ADR knowledge-system path and restore internal links Signed-off-by: vjymisal0 --- docs/content/hive/acmm-policy-matrix.md | 205 ++ .../adr/0001-record-architecture-decisions.md | 28 + .../0002-mitm-proxy-network-enforcement.md | 36 + .../hive/adr/0003-acmm-autonomy-levels.md | 32 + .../hive/adr/0004-beads-work-ledger.md | 31 + .../hive/adr/0005-forge-abstraction.md | 36 + .../hive/adr/0006-planning-intelligence.md | 42 + docs/content/hive/adr/0007-token-mint.md | 43 + .../hive/adr/0008-ioscan-untrusted-input.md | 62 + .../hive/adr/0009-trajectory-review.md | 39 + .../adr/0010-escalation-circuit-breaker.md | 36 + .../content/hive/adr/0011-knowledge-system.md | 45 + docs/content/hive/adr/0012-skill-registry.md | 47 + docs/content/hive/adr/0013-cel-triggers.md | 40 + docs/content/hive/adr/0014-hub-spoke.md | 46 + .../hive/adr/0015-csp-style-src-scope.md | 102 + .../hive/adr/0016-csp-script-src-scope.md | 107 + .../hive/adr/0017-podman-quadlet-lifecycle.md | 212 ++ docs/content/hive/adr/readme.md | 57 + docs/content/hive/agent-configuration.md | 628 ++++++ docs/content/hive/architecture.md | 557 ++++-- docs/content/hive/backup-dr.md | 478 +++++ docs/content/hive/contributor-relay.md | 454 +++++ docs/content/hive/getting-started.md | 50 +- docs/content/hive/hivectl.md | 163 ++ docs/content/hive/landscape.md | 108 + docs/content/hive/manual-provisioning.md | 1776 +++++++++++++++++ docs/content/hive/net-admin-requirement.md | 151 ++ docs/content/hive/readme.md | 378 ++-- docs/content/hive/release-channels.md | 75 + docs/content/hive/roadmap.md | 53 + docs/content/hive/security-model.md | 182 ++ docs/content/hive/security-threat-model.md | 122 ++ docs/content/hive/troubleshooting.md | 415 ++++ scripts/sync-hive-docs.ts | 5 +- 35 files changed, 6396 insertions(+), 445 deletions(-) create mode 100644 docs/content/hive/acmm-policy-matrix.md create mode 100644 docs/content/hive/adr/0001-record-architecture-decisions.md create mode 100644 docs/content/hive/adr/0002-mitm-proxy-network-enforcement.md create mode 100644 docs/content/hive/adr/0003-acmm-autonomy-levels.md create mode 100644 docs/content/hive/adr/0004-beads-work-ledger.md create mode 100644 docs/content/hive/adr/0005-forge-abstraction.md create mode 100644 docs/content/hive/adr/0006-planning-intelligence.md create mode 100644 docs/content/hive/adr/0007-token-mint.md create mode 100644 docs/content/hive/adr/0008-ioscan-untrusted-input.md create mode 100644 docs/content/hive/adr/0009-trajectory-review.md create mode 100644 docs/content/hive/adr/0010-escalation-circuit-breaker.md create mode 100644 docs/content/hive/adr/0011-knowledge-system.md create mode 100644 docs/content/hive/adr/0012-skill-registry.md create mode 100644 docs/content/hive/adr/0013-cel-triggers.md create mode 100644 docs/content/hive/adr/0014-hub-spoke.md create mode 100644 docs/content/hive/adr/0015-csp-style-src-scope.md create mode 100644 docs/content/hive/adr/0016-csp-script-src-scope.md create mode 100644 docs/content/hive/adr/0017-podman-quadlet-lifecycle.md create mode 100644 docs/content/hive/adr/readme.md create mode 100644 docs/content/hive/agent-configuration.md create mode 100644 docs/content/hive/backup-dr.md create mode 100644 docs/content/hive/contributor-relay.md create mode 100644 docs/content/hive/hivectl.md create mode 100644 docs/content/hive/landscape.md create mode 100644 docs/content/hive/manual-provisioning.md create mode 100644 docs/content/hive/net-admin-requirement.md create mode 100644 docs/content/hive/release-channels.md create mode 100644 docs/content/hive/roadmap.md create mode 100644 docs/content/hive/security-model.md create mode 100644 docs/content/hive/security-threat-model.md create mode 100644 docs/content/hive/troubleshooting.md diff --git a/docs/content/hive/acmm-policy-matrix.md b/docs/content/hive/acmm-policy-matrix.md new file mode 100644 index 0000000000..19b0747378 --- /dev/null +++ b/docs/content/hive/acmm-policy-matrix.md @@ -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. diff --git a/docs/content/hive/adr/0001-record-architecture-decisions.md b/docs/content/hive/adr/0001-record-architecture-decisions.md new file mode 100644 index 0000000000..797d271ddf --- /dev/null +++ b/docs/content/hive/adr/0001-record-architecture-decisions.md @@ -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. diff --git a/docs/content/hive/adr/0002-mitm-proxy-network-enforcement.md b/docs/content/hive/adr/0002-mitm-proxy-network-enforcement.md new file mode 100644 index 0000000000..dbd1dfe418 --- /dev/null +++ b/docs/content/hive/adr/0002-mitm-proxy-network-enforcement.md @@ -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. diff --git a/docs/content/hive/adr/0003-acmm-autonomy-levels.md b/docs/content/hive/adr/0003-acmm-autonomy-levels.md new file mode 100644 index 0000000000..34a0c6fdb3 --- /dev/null +++ b/docs/content/hive/adr/0003-acmm-autonomy-levels.md @@ -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. diff --git a/docs/content/hive/adr/0004-beads-work-ledger.md b/docs/content/hive/adr/0004-beads-work-ledger.md new file mode 100644 index 0000000000..08cd7c8eae --- /dev/null +++ b/docs/content/hive/adr/0004-beads-work-ledger.md @@ -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. diff --git a/docs/content/hive/adr/0005-forge-abstraction.md b/docs/content/hive/adr/0005-forge-abstraction.md new file mode 100644 index 0000000000..f9563b6cc7 --- /dev/null +++ b/docs/content/hive/adr/0005-forge-abstraction.md @@ -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. diff --git a/docs/content/hive/adr/0006-planning-intelligence.md b/docs/content/hive/adr/0006-planning-intelligence.md new file mode 100644 index 0000000000..9b0972d9b1 --- /dev/null +++ b/docs/content/hive/adr/0006-planning-intelligence.md @@ -0,0 +1,42 @@ +> **Synced from Hive.** This page is pulled from [kubestellar/hive@v4](https://github.com/kubestellar/hive/blob/v4/src/docs/adr/0006-planning-intelligence.md) during the docs build. Edit the canonical source in the Hive repository. + +# ADR-0006: Planning intelligence with human review + +Status: Accepted (retroactive) + +## Context + +Large GitHub issues can be too vague for a single agent kick. Hive needs a way +to turn an epic into ordered, claimable work without letting an agent immediately +execute an unreviewed decomposition. The planning docs describe the flow: +architect decomposition, a draft plan hidden from `Ready()`, a plan-review gate, +and bounded stall replanning +([planning intelligence](https://github.com/kubestellar/hive/blob/v4/src/docs/planning-intelligence.md)). The package code records +the same metadata conventions and review transitions +([decompose](https://github.com/kubestellar/hive/blob/v4/src/pkg/planning/decompose.go), +[plan review](https://github.com/kubestellar/hive/blob/v4/src/pkg/planning/plan_review.go), +[stall replan](https://github.com/kubestellar/hive/blob/v4/src/pkg/planning/replan.go)). + +## Decision + +Use the existing `architect` lane to decompose an epic into child beads with +dependency edges and execution tags. Decomposition writes `parent_epic`, +`execution`, `plan_ref`, and `plan_status` metadata; draft plans keep children +out of ready queues until a human approves them. Reviewers may inspect, retag, +remove, approve, or reject children before work is released. + +The automatic issue-label entry point stays opt-in. `planning.plan_from_label` +defaults off because the label path can feed attacker-controlled issue text into +the architect prompt without per-kick review; even when enabled it is inert +below ACMM L5, where the architect is not scheduled. Approved plans that stop +making progress are re-kicked for unfinished work only, capped at five replans +before human escalation. + +## Consequences + +Hive can handle epics as DAGs instead of long-running, ambiguous agent sessions, +and operators get a clear approval point before work becomes claimable. The +system also preserves pause semantics: a paused architect queues decomposition +instead of being force-resumed. The cost is more state and review UI surface, +and deployments that opt into label planning must accept the prompt-injection +exposure of routing raw issue text to the architect. diff --git a/docs/content/hive/adr/0007-token-mint.md b/docs/content/hive/adr/0007-token-mint.md new file mode 100644 index 0000000000..85dfdce79c --- /dev/null +++ b/docs/content/hive/adr/0007-token-mint.md @@ -0,0 +1,43 @@ +> **Synced from Hive.** This page is pulled from [kubestellar/hive@v4](https://github.com/kubestellar/hive/blob/v4/src/docs/adr/0007-token-mint.md) during the docs build. Edit the canonical source in the Hive repository. + +# ADR-0007: Mint short-lived scoped agent credentials + +Status: Accepted (retroactive) + +For the operator-facing config reference (`mint:` block, key lifecycle, and +the trust boundary stated plainly), see [Token mint](https://github.com/kubestellar/hive/blob/v4/src/docs/token-mint.md). + +## Context + +Several v4 security fixes tightened token handling, including stopping full +installation-token exposure to agents, avoiding host CLI/PAT leakage, and +making shared App-token caches owner-only +(`security(H3 follow-up): stop leaking full installation token to agents via +HIVE_GITHUB_TOKEN`, `fix(contributor): stop leaking host CLI configs + PAT to +hub`, `fix(security): H3 — shared App-token cache owner-only + fail-loud +fallbacks`). Hive still needs a way to give agents cloud or registry authority +without distributing shared long-lived credentials. + +## Decision + +Introduce the mint as an opt-in short-lived credential issuer +([mint package](https://github.com/kubestellar/hive/blob/v4/src/pkg/mint/mint.go)). It signs scoped JWTs with bounded TTLs, +verification that fails closed, and a JWKS endpoint for downstream Workload +Identity Federation providers. Agent integration maps the same trust tiers used +by agent modes (`advisor`, `newcomer`, `contributor`, `trusted`) to explicit +scope strings such as `issues:read`, `contents:write`, and `pulls:merge` +([agent minting](https://github.com/kubestellar/hive/blob/v4/src/pkg/mint/agent.go)). + +The mint supplements, rather than replaces, the existing GitHub App token path. +When disabled, agent minting is a no-op. When enabled, empty agent identities, +unknown tiers, empty server secrets, bad signatures, and expired tokens all fail +toward least privilege or denial. + +## Consequences + +Leaked minted credentials have a bounded lifetime and a scope set tied to the +agent's trust tier, reducing blast radius compared with shared long-lived +tokens. JWKS-based verification also lets external brokers trust the hive +issuer without embedding private keys. The trade-off is another security +service and key lifecycle to operate, and the initial server still uses a +shared-secret caller gate until stronger caller identity verification is wired. diff --git a/docs/content/hive/adr/0008-ioscan-untrusted-input.md b/docs/content/hive/adr/0008-ioscan-untrusted-input.md new file mode 100644 index 0000000000..57f2ec7567 --- /dev/null +++ b/docs/content/hive/adr/0008-ioscan-untrusted-input.md @@ -0,0 +1,62 @@ +> **Synced from Hive.** This page is pulled from [kubestellar/hive@v4](https://github.com/kubestellar/hive/blob/v4/src/docs/adr/0008-ioscan-untrusted-input.md) during the docs build. Edit the canonical source in the Hive repository. + +# ADR-0008: Redact untrusted kick input with visible markers + +Status: Accepted (retroactive) + +## Context + +Hive builds agent kicks from issue titles, labels, comments, and other text that +may be controlled by an attacker. That text can carry prompt-injection phrases, +hidden Unicode, base64-encoded instructions, destructive commands, or secret +shapes. The ioscan package provides a pure scanner for input and output text +with structured findings and block decisions +([ioscan scanner](https://github.com/kubestellar/hive/blob/v4/src/pkg/ioscan/ioscan.go)). + +## Decision + +Scan untrusted kick-path text before injection and redact blocked content rather +than silently dropping the item or passing the raw payload through. `EnforceInput` +returns benign text byte-for-byte, but replaces blocked text with a visible +marker of the form `[ioscan: content withheld — ...]` that names the fired rules +without echoing the payload ([enforcement](https://github.com/kubestellar/hive/blob/v4/src/pkg/ioscan/enforce.go)). The +scheduler applies this to issue text and labels and writes an audit entry for +blocked findings when an audit sink is attached +([scheduler enforcement](https://github.com/kubestellar/hive/blob/v4/src/pkg/scheduler/ioscan_enforce.go)). + +The v4 base also includes the fail-safe default-on mode: absent `ioscan:` +configuration scans by default, while an explicit `ioscan.enabled: false` +opts out ([config](https://github.com/kubestellar/hive/blob/v4/src/pkg/config/config.go)). + +Operators may additionally enable `ioscan.canaries: true`. Hive then prepends a +random `HIVE-CANARY-...` marker to each kick with instructions that the agent +must never repeat it. Active canaries are kept in memory and persisted at +`/data/ioscan-canaries.json`; the GitHub MITM proxy scans outgoing issue/PR/ +comment writes, and advisory finding ingestion scans collected agent reports. A +leak records an `ioscan_canary_leak` audit event plus a critical advisory bead; +with `ioscan.fail_mode: closed`, the proxy rejects the GitHub write with 403. +Opaque git pushes cannot be inspected safely, so canary fail-closed mode blocks +`git-receive-pack` pushes rather than allowing an unscannable exfiltration path. + +Agent-derived advisory text is also scrubbed with `pkg/logscrub` before GitHub +publication so GitHub tokens, AWS access keys, bearer tokens, JWTs, and PEM +private-key blocks are redacted rather than echoed into comments. + +Hive also supports an optional semantic prompt-injection classifier under +`ioscan.classifier`. It runs after deterministic redaction, scrubs canaries +before any model call, caps segment size, caches verdicts by content hash, and +uses a per-eval budget. The first implementation is an LLM judge over the same +OpenAI-compatible model plumbing used by trajectory review; the interface is +small enough for a future local ONNX/DeBERTa backend. Classifier failures and +budget exhaustion fail open. Successful high-risk scores redact in open mode and +reuse the existing fail-closed kick-block/audit path in closed mode. + +## Consequences + +Agents can still see that an issue or label existed, but they do not receive the +raw injection or secret-bearing text. Visible markers make the behavior +auditable and reduce confusion compared with silent omission. The trade-off is +false positives: a legitimate title that matches a high-severity rule is +withheld until an operator investigates or disables ioscan explicitly. Output +enforcement exists as a pure helper, but the current ADR records the kick-input +path that is wired in this base. diff --git a/docs/content/hive/adr/0009-trajectory-review.md b/docs/content/hive/adr/0009-trajectory-review.md new file mode 100644 index 0000000000..f7a4be8264 --- /dev/null +++ b/docs/content/hive/adr/0009-trajectory-review.md @@ -0,0 +1,39 @@ +> **Synced from Hive.** This page is pulled from [kubestellar/hive@v4](https://github.com/kubestellar/hive/blob/v4/src/docs/adr/0009-trajectory-review.md) during the docs build. Edit the canonical source in the Hive repository. + +# ADR-0009: Trajectory review lane + +Status: Accepted (retroactive) + +## Context + +Per-action guards can miss goal drift: a session may take individually ordinary +steps while the overall sequence moves toward an unauthorized outcome. The +trajectory-review docs describe this as the case where only the direction of the +transcript reveals sandbox escape, scanner evasion, credential splitting, or a +goal adopted from repository content +([trajectory review](https://github.com/kubestellar/hive/blob/v4/src/docs/trajectory-review.md)). + +## Decision + +Run a periodic trajectory-review lane from the governor tick. The lane snapshots +running, non-exempt agents with their assigned intent and recent transcript, +sends a bounded transcript tail to a second model through the existing +OpenAI-compatible/LiteLLM endpoint, and asks for a compact JSON verdict +([reviewer](https://github.com/kubestellar/hive/blob/v4/src/pkg/trajectory/trajectory.go), +[lane](https://github.com/kubestellar/hive/blob/v4/src/pkg/trajectory/lane.go)). On divergence, the configured response is +to pause the agent and alert by default, or to alert only. The reviewer prompt +instructs the model to judge direction, not single commands, and to answer +non-divergent when unsure. + +Reviewer errors fail open. Endpoint outages, timeouts, non-OK responses, and +unparsable replies are logged and skipped so a broken oversight model cannot +pause an otherwise working fleet. + +## Consequences + +Hive gains semantic oversight for behavior that static rules and API gates do +not see, while still reusing existing pause, alert, and audit primitives. Cost +is bounded by transcript tail size, token cap, and cadence. The trade-off is +intentional: fail-open behavior means an unavailable or weak reviewer catches +less rather than halting work, and the lane can only judge rendered transcripts, +not hidden model reasoning. diff --git a/docs/content/hive/adr/0010-escalation-circuit-breaker.md b/docs/content/hive/adr/0010-escalation-circuit-breaker.md new file mode 100644 index 0000000000..269aad6dd3 --- /dev/null +++ b/docs/content/hive/adr/0010-escalation-circuit-breaker.md @@ -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/0010-escalation-circuit-breaker.md) during the docs build. Edit the canonical source in the Hive repository. + +# ADR-0010: Escalation circuit breaker for CI fix loops + +Status: Accepted (retroactive) + +## Context + +Hive agents can repair their own failing PRs, but an unbounded retry loop can +keep re-dispatching blind fixes without surfacing the root CI error. The +escalation package records the incident that forced this boundary: a console +test split kept `main` red for days while scanner fix PRs missed the one-line +failure in shard logs ([escalation package](https://github.com/kubestellar/hive/blob/v4/src/pkg/escalation/escalation.go)). + +## Decision + +Track red PRs in a persistent ledger keyed by `repo#number`. Each sweep records +distinct failing head SHAs, retains the last CI excerpt, clears history when a +PR goes green, and marks escalation once the threshold is crossed. The default +threshold is three distinct red SHAs. When escalation fires, Hive posts a comment +headed "Fix loop escalated — human attention needed", includes failing checks +and raw failure evidence when available, and applies the `needs-human` label so +future fix dispatch skips the PR. + +For unchanged red heads, track staleness separately and cap re-engagements at +three per current SHA. A branch that moves resets the re-engagement counter; a +permanently red, never-moving branch is not nudged forever. + +## Consequences + +The fleet stops spending cycles on fix loops that are not converging and gives a +human the evidence needed to unblock the PR. The ledger is deterministic and +language-agnostic: it keys on CI state, head SHAs, and elapsed time rather than +agent judgment. The trade-off is that some recoverable failures will require +manual label removal after the cap, and stale/failure detection depends on the +quality of CI observations and excerpts available during enumeration. diff --git a/docs/content/hive/adr/0011-knowledge-system.md b/docs/content/hive/adr/0011-knowledge-system.md new file mode 100644 index 0000000000..46da2a993c --- /dev/null +++ b/docs/content/hive/adr/0011-knowledge-system.md @@ -0,0 +1,45 @@ +> **Synced from Hive.** This page is pulled from [kubestellar/hive@v4](https://github.com/kubestellar/hive/blob/v4/src/docs/adr/0011-knowledge-system.md) during the docs build. Edit the canonical source in the Hive repository. + +# ADR-0011: Knowledge system for durable agent context + +Status: Accepted (back-filled) + +## Context + +Hive agents need project memory that outlives a single chat session, but prompt +context is scarce and unsafe to fill with every past note. The knowledge design +keeps that memory layered by scope and privacy — personal, project, org, and +community — and merges only relevant facts when preparing an agent kick +([knowledge design](https://github.com/kubestellar/hive/blob/v4/src/docs/design/knowledge-system.md)). The implementation also +needs to work when no external embedding service is available. + +## Decision + +Represent reusable lessons as typed facts with confidence, sources, tags, +relationships, usage counts, and layer metadata +([knowledge types](https://github.com/kubestellar/hive/blob/v4/src/pkg/knowledge/types.go)). Store local vault pages and +remote layer clients behind one `KnowledgeAPI`, and prime agents by formatting a +bounded set of selected facts into the kick prompt rather than letting agents +query the store directly ([knowledge API](https://github.com/kubestellar/hive/blob/v4/src/pkg/knowledge/api.go)). + +Use a deterministic term-frequency embedder as the default semantic signal: text +is tokenized, feature-hashed into a 256-dimensional vector, and L2-normalized, +with embeddings cached only for the search/reindex pass +([TF embedder](https://github.com/kubestellar/hive/blob/v4/src/pkg/knowledge/embedding.go)). Persist fact relationships in +a bbolt-backed graph store with SPO/POS/OSP indexes so facts can be traversed by +subject, predicate, or object ([graph store](https://github.com/kubestellar/hive/blob/v4/src/pkg/knowledge/graphstore.go)). +The retro lane ingests model-generated lessons only after length, secret, and +deduplication gates, then stores them as ordinary project facts derived from the +source bead or PR ([retro lessons](https://github.com/kubestellar/hive/blob/v4/src/pkg/knowledge/retro_lesson.go)). + +## Consequences + +Rationale not recorded beyond the implementation, linked code, and cited design notes. + +Agents can receive durable, source-backed context without depending on an LLM's +conversation memory or a hosted embedding API. Layer precedence and explicit +promotion preserve the privacy boundary described by the design while still +letting community and org knowledge flow down. The trade-off is a deliberately +simple retrieval model: hashed term-frequency vectors and tag/graph edges are +portable and inspectable, but lower quality than model embeddings, and stale or +incorrect facts still need curation rather than blind injection. diff --git a/docs/content/hive/adr/0012-skill-registry.md b/docs/content/hive/adr/0012-skill-registry.md new file mode 100644 index 0000000000..c2dba0f333 --- /dev/null +++ b/docs/content/hive/adr/0012-skill-registry.md @@ -0,0 +1,47 @@ +> **Synced from Hive.** This page is pulled from [kubestellar/hive@v4](https://github.com/kubestellar/hive/blob/v4/src/docs/adr/0012-skill-registry.md) during the docs build. Edit the canonical source in the Hive repository. + +# ADR-0012: Skill registry and BYO-agent contract + +Status: Accepted (back-filled) + +> **Operator guide:** [Skill registry](https://github.com/kubestellar/hive/blob/v4/src/docs/skills.md) covers the on-disk format +> and the current wiring status. This ADR records the decision; it is not an +> operator guide. + +## Context + +`AGENTS.md` can carry repo-local skill snippets, but inline snippets do not give +Hive a shareable catalog, version metadata, search, or a stable contract for +third-party agents. Hive also needs custom agents to be declared without binding +them to internal launcher structures. + +## Decision + +Introduce `skillreg` as a concurrency-safe registry of named, versioned skill +files plus a minimal bring-your-own-agent SDK contract +([skill registry](https://github.com/kubestellar/hive/blob/v4/src/pkg/skillreg/skillreg.go)). A skill is a Markdown body +with optional YAML front matter for name, version, description, and tags. Missing +skill directories, unreadable files, and malformed front matter are skipped with +logs so one bad catalog entry does not prevent Hive from loading. + +Resolve requested skills by preferring the curated registry over inline +`AGENTS.md` snippets, while falling back to repo-local skills the registry does +not know about. Version resolution supports latest, exact versions, wildcard, +caret-major, and greater-than-or-equal constraints, and `InjectionText` renders a +single Markdown block for the kick path. + +Define the BYO-agent contract as `AgentSpec`: name, backend, model, operating +mode, and default skills ([agent spec](https://github.com/kubestellar/hive/blob/v4/src/pkg/skillreg/agentspec.go)). YAML +agent specs are strict: malformed YAML, missing name/backend/model, or unknown +modes fail before an agent can launch silently. + +## Consequences + +Rationale not recorded beyond the implementation, linked code, and cited design notes. + +Skills become portable and discoverable without removing simple repo-local +snippets. Custom agents get a small, stable interface that catalogs and launchers +can share. The trade-off is that registry skills intentionally override inline +snippets, so catalog governance matters; and the current registry helper is a +contract and rendering layer, not a full package manager or deep launcher +integration. diff --git a/docs/content/hive/adr/0013-cel-triggers.md b/docs/content/hive/adr/0013-cel-triggers.md new file mode 100644 index 0000000000..792e0eafce --- /dev/null +++ b/docs/content/hive/adr/0013-cel-triggers.md @@ -0,0 +1,40 @@ +> **Synced from Hive.** This page is pulled from [kubestellar/hive@v4](https://github.com/kubestellar/hive/blob/v4/src/docs/adr/0013-cel-triggers.md) during the docs build. Edit the canonical source in the Hive repository. + +# ADR-0013: CEL triggers over normalized forge events + +Status: Accepted (back-filled) + +## Context + +Hive's built-in label and governor triggers cover common flows, but operators +need repo-specific trigger policy without hard-coding GitHub webhook details or +forking the governor. The trigger language must be expressive enough for labels, +branches, authors, draft status, and comments, while failing safely when an +operator writes a bad rule. + +## Decision + +Add CEL-based declarative triggers over a forge-neutral `NormalizedEvent` +([CEL trigger engine](https://github.com/kubestellar/hive/blob/v4/src/pkg/celtrigger/celtrigger.go)). Forge adapters map +native events onto stable kinds such as `issue.opened`, `pr.labeled`, +`pr.ready_for_review`, and `comment.created`; CEL expressions see only the +`event` object with normalized fields such as repo, labels, title, author, body, +state, branches, assignees, and comment. + +Compile every rule before use and require a boolean expression. Unknown fields, +parse errors, type errors, empty expressions, or non-boolean results reject the +engine at config load. Runtime evaluation errors are treated as no match. Matched +rules are returned in descending priority, and `MatchAgents` de-duplicates agent +names before the governor unions them with existing built-in triggers +([config wiring](https://github.com/kubestellar/hive/blob/v4/src/pkg/celtrigger/wire.go)). + +## Consequences + +Rationale not recorded beyond the implementation, linked code, and cited design notes. + +Operators can add declarative, forge-neutral trigger policy without changing Go +code, and bad rules fail closed before they can crash a running fleet. The same +normalized event model keeps the path open for GitLab or other forge adapters. +The trade-off is that CEL only sees fields Hive normalizes; new trigger needs may +require extending `NormalizedEvent`, and a malformed rule currently blocks the +whole configured CEL engine rather than being partially ignored. diff --git a/docs/content/hive/adr/0014-hub-spoke.md b/docs/content/hive/adr/0014-hub-spoke.md new file mode 100644 index 0000000000..29a1118d74 --- /dev/null +++ b/docs/content/hive/adr/0014-hub-spoke.md @@ -0,0 +1,46 @@ +> **Synced from Hive.** This page is pulled from [kubestellar/hive@v4](https://github.com/kubestellar/hive/blob/v4/src/docs/adr/0014-hub-spoke.md) during the docs build. Edit the canonical source in the Hive repository. + +# ADR-0014: Hub/spoke fleet over heartbeat callbacks + +Status: Accepted (back-filled) + +## Context + +Hive needs a shared fleet view without requiring every operator's cluster to be +reachable from the public hub. The architecture defines every hive as a spoke +and the hosted site as the hub, both running the same image with `HIVE_MODE=hub` +selecting the role ([architecture §8](/docs/hive/architecture#8-hub--spoke)). The hub +must maintain registry, leaderboard, provisioning, and operator controls even +for firewalled spokes. + +## Decision + +Use spoke-initiated heartbeats as the control channel. A spoke posts identity, +repos, ACMM level, agents, governor state, contributors, leaderboard, health, +version, image, and related status to `/api/heartbeat`; the hub persists a +sanitized registry entry and marks the spoke online +([heartbeat payload](https://github.com/kubestellar/hive/blob/v4/src/pkg/hub/heartbeat.go), [hub registry](https://github.com/kubestellar/hive/blob/v4/src/pkg/hub/server.go)). +The heartbeat response carries callbacks for upgrade, branch switch, GitHub App +config, banners, visibility, authorized users, project config, gateway config, +and restart requests, letting the hub act even when it cannot open a connection +back to the cluster. + +Keep hub and spoke roles in one deployable image, and report the spoke's actual +image reference so the hub can detect pinned or stale deployments. Merge public +spoke leaderboards centrally while excluding agent identities, and use +contributor counts plus active leaderboard tasks as evidence that the ClankeR +contributor relay is carrying work. Contributor relay credentials remain on the +contributor's machine; the hub sees trust tier, task counts, and current task +metadata, not the user's credential material. + +## Consequences + +Rationale not recorded beyond the implementation, linked code, and cited design notes. + +The fleet works through firewalls and NAT because all routine control flows ride +spoke-initiated HTTP. Operators get one registry, fleet-stats surface, and +leaderboard while individual hives retain local runtime state. The trade-off is +that heartbeat freshness and callback delivery become critical infrastructure: +missed beats make hives appear offline, callback actions are eventually delivered +rather than immediate, and the shared hub must carefully sanitize and bound every +spoke-reported field. diff --git a/docs/content/hive/adr/0015-csp-style-src-scope.md b/docs/content/hive/adr/0015-csp-style-src-scope.md new file mode 100644 index 0000000000..ef49667901 --- /dev/null +++ b/docs/content/hive/adr/0015-csp-style-src-scope.md @@ -0,0 +1,102 @@ +> **Synced from Hive.** This page is pulled from [kubestellar/hive@v4](https://github.com/kubestellar/hive/blob/v4/src/docs/adr/0015-csp-style-src-scope.md) during the docs build. Edit the canonical source in the Hive repository. + +# ADR-0015: Scope `style-src` as two directives and accept inline style attributes + +Status: Accepted + +## Context + +The dashboard's Content-Security-Policy carried one blanket `style-src 'self' +'unsafe-inline'` ([securityHeaders](https://github.com/kubestellar/hive/blob/v4/src/pkg/dashboard/server.go)). That single +token covered two different things with two different futures, and hid the fact +that only one of them is closable. + +[kubestellar/hive#3848](https://github.com/kubestellar/hive/issues/3848) asked +for the two to be separated and for the remaining allowance to be either removed +or accepted **with a written rationale**. This is that rationale. + +Measured on `v4` at the time of writing: + +| Inline style form | Count | Covered by a nonce or hash? | +| --- | --- | --- | +| `style="…"` attributes | 2061 | **No** | +| `