diff --git a/.github/workflows/vitest.yml b/.github/workflows/vitest.yml index c151fcb..50956c5 100644 --- a/.github/workflows/vitest.yml +++ b/.github/workflows/vitest.yml @@ -29,7 +29,9 @@ jobs: - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: - node-version: "20" + # jsdom 30 depends on undici 8, which requires Node >= 22.19 + # (Node 20 fails with "webidl.util.markAsUncloneable is not a function"). + node-version: "22" cache: "npm" - name: Install dependencies diff --git a/README.md b/README.md index efeb21b..8f63b7f 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ Official documentation site for [Hive Commons](https://hivecommons.dev), served - **[pluk](https://github.com/hivecommons/pluk)** — pub-sub event streaming for AI agent tmux sessions - **[rationguard](https://github.com/hivecommons/rationguard)** — detect and rebut rationalization patterns in AI agent output - **[promptargs](https://github.com/hivecommons/promptargs)** — template expansion for AI prompts +- **[Spektacular](https://github.com/hivecommons/spektacular)** — spec-driven development for AI coding agents (canonical site: [spektacular.dev](https://spektacular.dev)) ## How content is sourced @@ -22,7 +23,9 @@ at build time: - `scripts/sync-hive-docs.ts` pulls Hive docs from `hivecommons/hive` (`src/docs/`, branch `v5`; override with `HIVE_DOCS_OWNER` / `HIVE_DOCS_REPO` / `HIVE_DOCS_REF`). -- `scripts/sync-sibling-docs.ts` pulls the hotshot, pluk, rationguard, and promptargs docs from their repos. +- `scripts/sync-sibling-docs.ts` pulls the hotshot, pluk, rationguard, promptargs, and Spektacular docs from their repos. + Spektacular also pulls its tutorials from `hivecommons/spektacular-website` (MDX, converted to Markdown by + `scripts/mdx-to-markdown.ts`; override the ref with `SPEKTACULAR_WEBSITE_DOCS_REF`). Edit the canonical source in the project repository — not the synced copies under `docs/content/`. If a sync source is unreachable at build time, the committed copies diff --git a/docs/content/hive/acmm-policy-matrix.md b/docs/content/hive/acmm-policy-matrix.md index c67e830..45114f8 100644 --- a/docs/content/hive/acmm-policy-matrix.md +++ b/docs/content/hive/acmm-policy-matrix.md @@ -1,4 +1,4 @@ -> **Synced from Hive.** This page is pulled from [hivecommons/hive@v4](https://github.com/hivecommons/hive/blob/v4/src/docs/acmm-policy-matrix.md) during the docs build. Edit the canonical source in the Hive repository. +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/acmm-policy-matrix.md) during the docs build. Edit the canonical source in the Hive repository. # ACMM Policy Matrix @@ -15,14 +15,14 @@ Each agent runs in one of four modes, controlling what actions it can take on Gi - **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. +- **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. One exception: a hold the hive applied *for level reasons* is released automatically once the current level no longer calls for it — see the promotion note below. A hold **you** applied is never removed automatically. - **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/hivecommons/hive/blob/v4/src/docs/inception.md) for the end-to-end workflow and API reference. +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/hivecommons/hive/blob/v5/src/docs/inception.md) for the end-to-end workflow and API reference. | Agent | Mode | Template | |-------|------|----------| @@ -68,9 +68,9 @@ Delivery agents open GitHub issues — bugs, docs gaps, CI problems, security vu | **sec-check** | **holdgated** | `sec-check-holdgated.md` | | brainstorm | advisory | `brainstorm-advisory.md` | -### L5 — Semi-Autonomous (Semi-Automated) (11 agents) +### L5 — Semi-Autonomous (Semi-Automated) (12 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. +Agents open issues AND pull requests. All PRs get a hold label — humans batch-review and approve. Architect produces RFCs, strategist coordinates across agents, and reviewer works the hold-gated PR queue every 30 minutes. The system proposes; it does not merge autonomously. | Agent | Mode | Template | |-------|------|----------| @@ -82,13 +82,14 @@ Agents open issues AND pull requests. All PRs get a hold label — humans batch- | sec-check | holdgated | `sec-check-holdgated.md` | | architect | holdgated | `architect-holdgated.md` | | strategist | holdgated | `strategist-holdgated.md` | +| reviewer | converse | `reviewer-queue.md` | | telemetry (paused) | holdgated | `telemetry-holdgated.md` | | operations (paused) | holdgated | `operations-holdgated.md` | | brainstorm | advisory | `brainstorm-advisory.md` | -### L6 — Fully Autonomous (12 agents) +### L6 — Fully Autonomous (13 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. +Existing autonomous lanes can open issues, create PRs, and auto-merge on green CI. No hold label. Outreach handles community engagement. Reviewer stays advisory even here — its `requires_human` verdict is what pulls a PR out of the auto-merge lane. Telemetry and operations remain paused and use `ISSUES_AND_PRS`, so they never merge their own PRs. | Agent | Mode | Template | |-------|------|----------| @@ -101,6 +102,7 @@ Existing autonomous lanes can open issues, create PRs, and auto-merge on green C | architect | full | `architect-full.md` | | strategist | full | `strategist-full.md` | | outreach | full | `outreach-full.md` | +| reviewer | converse | `reviewer-queue.md` | | telemetry (paused) | full | `telemetry-full.md` | | operations (paused) | full | `operations-full.md` | | brainstorm | advisory | `brainstorm-advisory.md` | @@ -112,12 +114,43 @@ Existing autonomous lanes can open issues, create PRs, and auto-merge on green C ## 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. +2. **Advisory agents never get GH auth.** The `${GH_AUTH}` template variable is only injected into measured, holdgated, full, and converse templates. The converse tier is the one place an agent writes to GitHub without sitting on the mode ladder: `reviewer` is `mode: ADVISORY` plus the orthogonal `converse` capability ([#4492](https://github.com/hivecommons/hive/issues/4492)), which grants comments and PR reviews and nothing else — no issue creation, no relabelling, no push, no merge. It needs the auth block because posting a review *is* a GitHub write. 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. +7. **Reviewer is L5/L6-only by default and never merges.** It joined the L5 and L6 rosters in [#8023](https://github.com/hivecommons/hive/issues/8023) at a 30-minute cadence in every governor mode. Below L5 no pack lists it, so an operator who wants repo-grounded PR review creates it by hand and a pack apply leaves that agent's mode, model, backend, and pause state alone. Its mode stays `ADVISORY` at both levels, including L6: it reads the queue, comments, and returns a verdict, and it is that verdict — `requires_human` or `reject` — that pulls a PR out of the auto-merge lane. +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 + +Two `ioscan` hardening modes take their default from the pack governor rather +than being fixed globally. Both are overridable per hive in either direction — +the pack only supplies the default when the hive leaves the key unset. + +| Setting | L1–L4 default | L5–L6 default | What the default does | Override | +|---|---|---|---|---| +| `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 +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 +`ioscan.fail_mode: open` explicitly; an L1–L4 hive that wants the stricter +posture sets `ioscan.fail_mode: closed`. An explicit value always wins over the +pack default. The knob lives on the pack governor: + +```yaml +# packs/level-5.yaml (and level-6.yaml) +governor: + ioscan_fail_mode: closed # "" (open) below L5; closed at L5/L6 +``` + +## Which levels may publish audit findings + +The audit campaign's issue publisher ([audit-campaign.md](https://github.com/hivecommons/hive/blob/v5/src/docs/audit-campaign.md#publication)) files validated findings as issues only at **L3 and above**, the first level whose pack grants an agent the measured (issues) mode. At L1 and L2 every agent is advisory, so the publisher refuses with a typed error and an audit entry instead of filing. Security-sensitive findings never become public issues at any level; they go to `publication.private_channel` or are refused. Publication also requires `publication.enabled: true` and the `enforce` convergence mode; `shadow` records `withheld:mode` and writes nothing. ## Where ACMM gap issues are filed @@ -187,6 +220,13 @@ 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. + Promotion also **releases the level holds the hive itself applied** to open App + PRs that the new level no longer requires, so you do not have to clean them up + by hand after a level bump. Release is fail-closed: it applies only to + App-authored PRs carrying the hive's own attributable level-hold notice, only + when the most recent `hold` label event was applied by the App, and never while + a self-authorization hold applies. A hold a human applied — or re-applied after + the hive removed one — is never touched. - **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). @@ -200,6 +240,34 @@ 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/hivecommons/hive/blob/v4/src/docs/acmm-advisor.md) page +manual process described above. See the [ACMM advisor](https://github.com/hivecommons/hive/blob/v5/src/docs/acmm-advisor.md) page for the exact thresholds per target level and what the `GET /api/acmm-recommendation` endpoint returns. + +## Automatic autonomy-signal level changes + +The retro lane can also act on recorded autonomy signal findings. This policy is +additive and **off by default**: + +```yaml +autonomy: + auto_promote: false + auto_demote: false + promote_after: 3 + demote_on: rollback # rollback | rework | either + max_level: 6 + cooldown_days: 7 +``` + +When enabled, three consecutive qualifying repo-scoped retro findings promote +the repo by one level, never skipping a level and never above `max_level`. +A rollback finding demotes by one level immediately; demotions are not blocked +by cooldown. A pinned repo policy (`project.repo_policies[].acmm_pinned: true`) +is never moved automatically. + +Every automatic move writes a repo-keyed `project.repo_policies[]` record with +the last change, evidence bead IDs, and pin state, and also records an audit +entry plus a visible decision bead. The hive-wide `acmm_level` remains the +ceiling. Until the per-repo ACMM RFC (#6111) lands, Hive keeps this repo-keyed +seam and teaches the live proxy to apply the repo override on matching +repository requests so enforcement observes the decision without a restart. diff --git a/docs/content/hive/adr/0001-record-architecture-decisions.md b/docs/content/hive/adr/0001-record-architecture-decisions.md index f98fd75..90a3634 100644 --- a/docs/content/hive/adr/0001-record-architecture-decisions.md +++ b/docs/content/hive/adr/0001-record-architecture-decisions.md @@ -1,4 +1,4 @@ -> **Synced from Hive.** This page is pulled from [hivecommons/hive@v4](https://github.com/hivecommons/hive/blob/v4/src/docs/adr/0001-record-architecture-decisions.md) during the docs build. Edit the canonical source in the Hive repository. +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/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 diff --git a/docs/content/hive/adr/0002-mitm-proxy-network-enforcement.md b/docs/content/hive/adr/0002-mitm-proxy-network-enforcement.md index 9a3a00e..2f64f8f 100644 --- a/docs/content/hive/adr/0002-mitm-proxy-network-enforcement.md +++ b/docs/content/hive/adr/0002-mitm-proxy-network-enforcement.md @@ -1,4 +1,4 @@ -> **Synced from Hive.** This page is pulled from [hivecommons/hive@v4](https://github.com/hivecommons/hive/blob/v4/src/docs/adr/0002-mitm-proxy-network-enforcement.md) during the docs build. Edit the canonical source in the Hive repository. +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/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 diff --git a/docs/content/hive/adr/0003-acmm-autonomy-levels.md b/docs/content/hive/adr/0003-acmm-autonomy-levels.md index c22ac83..b0a2cbe 100644 --- a/docs/content/hive/adr/0003-acmm-autonomy-levels.md +++ b/docs/content/hive/adr/0003-acmm-autonomy-levels.md @@ -1,4 +1,4 @@ -> **Synced from Hive.** This page is pulled from [hivecommons/hive@v4](https://github.com/hivecommons/hive/blob/v4/src/docs/adr/0003-acmm-autonomy-levels.md) during the docs build. Edit the canonical source in the Hive repository. +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/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 @@ -10,7 +10,7 @@ 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), +([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). diff --git a/docs/content/hive/adr/0004-beads-work-ledger.md b/docs/content/hive/adr/0004-beads-work-ledger.md index 4dfc3b0..d459066 100644 --- a/docs/content/hive/adr/0004-beads-work-ledger.md +++ b/docs/content/hive/adr/0004-beads-work-ledger.md @@ -1,4 +1,4 @@ -> **Synced from Hive.** This page is pulled from [hivecommons/hive@v4](https://github.com/hivecommons/hive/blob/v4/src/docs/adr/0004-beads-work-ledger.md) during the docs build. Edit the canonical source in the Hive repository. +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/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 @@ -9,7 +9,7 @@ Status: Accepted (retroactive) 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)). +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)). diff --git a/docs/content/hive/adr/0005-forge-abstraction.md b/docs/content/hive/adr/0005-forge-abstraction.md index 5229b87..351632a 100644 --- a/docs/content/hive/adr/0005-forge-abstraction.md +++ b/docs/content/hive/adr/0005-forge-abstraction.md @@ -1,4 +1,4 @@ -> **Synced from Hive.** This page is pulled from [hivecommons/hive@v4](https://github.com/hivecommons/hive/blob/v4/src/docs/adr/0005-forge-abstraction.md) during the docs build. Edit the canonical source in the Hive repository. +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/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 @@ -11,7 +11,7 @@ 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/hivecommons/hive/blob/v4/src/pkg/forge/forge.go)). +details ([forge package](https://github.com/hivecommons/hive/blob/v5/src/pkg/forge/forge.go)). ## Decision diff --git a/docs/content/hive/adr/0006-planning-intelligence.md b/docs/content/hive/adr/0006-planning-intelligence.md index 27a4fee..bd8b795 100644 --- a/docs/content/hive/adr/0006-planning-intelligence.md +++ b/docs/content/hive/adr/0006-planning-intelligence.md @@ -1,4 +1,4 @@ -> **Synced from Hive.** This page is pulled from [hivecommons/hive@v4](https://github.com/hivecommons/hive/blob/v4/src/docs/adr/0006-planning-intelligence.md) during the docs build. Edit the canonical source in the Hive repository. +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/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 @@ -11,11 +11,11 @@ to turn an epic into ordered, claimable work without letting an agent immediatel 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/hivecommons/hive/blob/v4/src/docs/planning-intelligence.md)). The package code records +([planning intelligence](https://github.com/hivecommons/hive/blob/v5/src/docs/planning-intelligence.md)). The package code records the same metadata conventions and review transitions -([decompose](https://github.com/hivecommons/hive/blob/v4/src/pkg/planning/decompose.go), -[plan review](https://github.com/hivecommons/hive/blob/v4/src/pkg/planning/plan_review.go), -[stall replan](https://github.com/hivecommons/hive/blob/v4/src/pkg/planning/replan.go)). +([decompose](https://github.com/hivecommons/hive/blob/v5/src/pkg/planning/decompose.go), +[plan review](https://github.com/hivecommons/hive/blob/v5/src/pkg/planning/plan_review.go), +[stall replan](https://github.com/hivecommons/hive/blob/v5/src/pkg/planning/replan.go)). ## Decision diff --git a/docs/content/hive/adr/0007-token-mint.md b/docs/content/hive/adr/0007-token-mint.md index 05476d2..0e5538e 100644 --- a/docs/content/hive/adr/0007-token-mint.md +++ b/docs/content/hive/adr/0007-token-mint.md @@ -1,11 +1,11 @@ -> **Synced from Hive.** This page is pulled from [hivecommons/hive@v4](https://github.com/hivecommons/hive/blob/v4/src/docs/adr/0007-token-mint.md) during the docs build. Edit the canonical source in the Hive repository. +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/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/hivecommons/hive/blob/v4/src/docs/token-mint.md). +the trust boundary stated plainly), see [Token mint](https://github.com/hivecommons/hive/blob/v5/src/docs/token-mint.md). ## Context @@ -21,12 +21,12 @@ without distributing shared long-lived credentials. ## Decision Introduce the mint as an opt-in short-lived credential issuer -([mint package](https://github.com/hivecommons/hive/blob/v4/src/pkg/mint/mint.go)). It signs scoped JWTs with bounded TTLs, +([mint package](https://github.com/hivecommons/hive/blob/v5/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/hivecommons/hive/blob/v4/src/pkg/mint/agent.go)). +([agent minting](https://github.com/hivecommons/hive/blob/v5/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, diff --git a/docs/content/hive/adr/0008-ioscan-untrusted-input.md b/docs/content/hive/adr/0008-ioscan-untrusted-input.md index a0dff66..d29b43c 100644 --- a/docs/content/hive/adr/0008-ioscan-untrusted-input.md +++ b/docs/content/hive/adr/0008-ioscan-untrusted-input.md @@ -1,4 +1,4 @@ -> **Synced from Hive.** This page is pulled from [hivecommons/hive@v4](https://github.com/hivecommons/hive/blob/v4/src/docs/adr/0008-ioscan-untrusted-input.md) during the docs build. Edit the canonical source in the Hive repository. +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/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 @@ -11,7 +11,7 @@ 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/hivecommons/hive/blob/v4/src/pkg/ioscan/ioscan.go)). +([ioscan scanner](https://github.com/hivecommons/hive/blob/v5/src/pkg/ioscan/ioscan.go)). ## Decision @@ -19,14 +19,14 @@ 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/hivecommons/hive/blob/v4/src/pkg/ioscan/enforce.go)). The +without echoing the payload ([enforcement](https://github.com/hivecommons/hive/blob/v5/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/hivecommons/hive/blob/v4/src/pkg/scheduler/ioscan_enforce.go)). +([scheduler enforcement](https://github.com/hivecommons/hive/blob/v5/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/hivecommons/hive/blob/v4/src/pkg/config/config.go)). +opts out ([config](https://github.com/hivecommons/hive/blob/v5/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 diff --git a/docs/content/hive/adr/0009-trajectory-review.md b/docs/content/hive/adr/0009-trajectory-review.md index df032ee..bdc2d81 100644 --- a/docs/content/hive/adr/0009-trajectory-review.md +++ b/docs/content/hive/adr/0009-trajectory-review.md @@ -1,4 +1,4 @@ -> **Synced from Hive.** This page is pulled from [hivecommons/hive@v4](https://github.com/hivecommons/hive/blob/v4/src/docs/adr/0009-trajectory-review.md) during the docs build. Edit the canonical source in the Hive repository. +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/adr/0009-trajectory-review.md) during the docs build. Edit the canonical source in the Hive repository. # ADR-0009: Trajectory review lane @@ -11,7 +11,7 @@ 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/hivecommons/hive/blob/v4/src/docs/trajectory-review.md)). +([trajectory review](https://github.com/hivecommons/hive/blob/v5/src/docs/trajectory-review.md)). ## Decision @@ -19,8 +19,8 @@ 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/hivecommons/hive/blob/v4/src/pkg/trajectory/trajectory.go), -[lane](https://github.com/hivecommons/hive/blob/v4/src/pkg/trajectory/lane.go)). On divergence, the configured response is +([reviewer](https://github.com/hivecommons/hive/blob/v5/src/pkg/trajectory/trajectory.go), +[lane](https://github.com/hivecommons/hive/blob/v5/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. diff --git a/docs/content/hive/adr/0010-escalation-circuit-breaker.md b/docs/content/hive/adr/0010-escalation-circuit-breaker.md index a22e21f..f872c95 100644 --- a/docs/content/hive/adr/0010-escalation-circuit-breaker.md +++ b/docs/content/hive/adr/0010-escalation-circuit-breaker.md @@ -1,4 +1,4 @@ -> **Synced from Hive.** This page is pulled from [hivecommons/hive@v4](https://github.com/hivecommons/hive/blob/v4/src/docs/adr/0010-escalation-circuit-breaker.md) during the docs build. Edit the canonical source in the Hive repository. +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/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 @@ -10,7 +10,7 @@ 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/hivecommons/hive/blob/v4/src/pkg/escalation/escalation.go)). +failure in shard logs ([escalation package](https://github.com/hivecommons/hive/blob/v5/src/pkg/escalation/escalation.go)). ## Decision @@ -26,6 +26,31 @@ 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. +A PR escalating for the SECOND time — after the reviewer lane ([#5480]) already +repaired or de-escalated it once — gets a structured hand-off note instead of +the generic body. The ledger stamps the head SHA the reviewer left on the branch +and when its verdict was reconciled, and keeps both across the reset that +reconciliation performs, so the comment can say what was already tried, that the +attempt count is measured from the reviewer's pass, and that no further +automated pass is coming. One reviewer pass per PR is the whole ladder: without +the note, nothing distinguished that terminal hand-off from a first escalation +except the label set. + +[#5480]: https://github.com/hivecommons/hive/issues/5480 + +The `needs-human` label on the forge, not the ledger, is the authoritative +record that a PR has been escalated. The ledger is a cache of it: a PR that +wears the label reads as escalated even to an empty ledger (so the evidence +comment is never posted twice, whatever happens to `/data`), and a PR whose +confirmed label a human removes is un-parked with a fresh budget. A pass that +cannot conclude CI state (checks running, or the check-run fetch failed — both +surface as `pending`) leaves the ledger untouched; only a conclusive green +clears history. Entries are pruned 24h after their PR stops being enumerated, +not on the first pass that misses it. + +Dependency bots (`renovate[bot]`, `dependabot[bot]`, `mergeraptor[bot]`) are +not agent authors: their red PRs are not fix loops to break. + ## Consequences The fleet stops spending cycles on fix loops that are not converging and gives a diff --git a/docs/content/hive/adr/0011-knowledge-system.md b/docs/content/hive/adr/0011-knowledge-system.md index b8690df..317f3a8 100644 --- a/docs/content/hive/adr/0011-knowledge-system.md +++ b/docs/content/hive/adr/0011-knowledge-system.md @@ -1,4 +1,4 @@ -> **Synced from Hive.** This page is pulled from [hivecommons/hive@v4](https://github.com/hivecommons/hive/blob/v4/src/docs/adr/0011-knowledge-system.md) during the docs build. Edit the canonical source in the Hive repository. +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/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 @@ -10,27 +10,27 @@ 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/hivecommons/hive/blob/v4/src/docs/design/knowledge-system.md)). The implementation also +([knowledge design](https://github.com/hivecommons/hive/blob/v5/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/hivecommons/hive/blob/v4/src/pkg/knowledge/types.go)). Store local vault pages and +([knowledge types](https://github.com/hivecommons/hive/blob/v5/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/hivecommons/hive/blob/v4/src/pkg/knowledge/api.go)). +query the store directly ([knowledge API](https://github.com/hivecommons/hive/blob/v5/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/hivecommons/hive/blob/v4/src/pkg/knowledge/embedding.go)). Persist fact relationships in +([TF embedder](https://github.com/hivecommons/hive/blob/v5/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/hivecommons/hive/blob/v4/src/pkg/knowledge/graphstore.go)). +subject, predicate, or object ([graph store](https://github.com/hivecommons/hive/blob/v5/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/hivecommons/hive/blob/v4/src/pkg/knowledge/retro_lesson.go)). +source bead or PR ([retro lessons](https://github.com/hivecommons/hive/blob/v5/src/pkg/knowledge/retro_lesson.go)). ## Consequences diff --git a/docs/content/hive/adr/0012-skill-registry.md b/docs/content/hive/adr/0012-skill-registry.md index 8c7f225..ffe3f2c 100644 --- a/docs/content/hive/adr/0012-skill-registry.md +++ b/docs/content/hive/adr/0012-skill-registry.md @@ -1,47 +1,49 @@ -> **Synced from Hive.** This page is pulled from [hivecommons/hive@v4](https://github.com/hivecommons/hive/blob/v4/src/docs/adr/0012-skill-registry.md) during the docs build. Edit the canonical source in the Hive repository. +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/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/hivecommons/hive/blob/v4/src/docs/skills.md) covers the on-disk format +> **Operator guide:** [Skill registry](https://github.com/hivecommons/hive/blob/v5/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. +Hive a shareable catalog or version metadata. ## 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/hivecommons/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. +files ([skill registry](https://github.com/hivecommons/hive/blob/v5/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 +Requested skills are selected 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. +not know about. `Get` returns the newest loaded version, `List`/`Search` provide +catalog UX, 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/hivecommons/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. +The same package defines `AgentSpec`, the minimal BYO-agent contract: +name, backend, model, operating mode, optional launch command, prompt, tools, +and default skills. Agent configs opt into that contract with `agent_spec`, +which points at a YAML file or spec directory. + +## Status notes + +- Implemented in #6004: `agent_spec` is loaded through `skillreg.LoadAgentSpec` + on the pkg/agent launch path, and `hivectl agent specs list|search` exposes + the registry discovery surface. ## 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. +Skills become portable without removing simple repo-local snippets. The +trade-off is that registry skills intentionally override inline snippets, so +catalog governance matters. BYO-agent specs add launcher integration without +turning the registry into a package manager: Hive resolves a local declaration +and applies only the fields in the stable contract. diff --git a/docs/content/hive/adr/0013-cel-triggers.md b/docs/content/hive/adr/0013-cel-triggers.md index ba88bfa..9f4c082 100644 --- a/docs/content/hive/adr/0013-cel-triggers.md +++ b/docs/content/hive/adr/0013-cel-triggers.md @@ -1,4 +1,4 @@ -> **Synced from Hive.** This page is pulled from [hivecommons/hive@v4](https://github.com/hivecommons/hive/blob/v4/src/docs/adr/0013-cel-triggers.md) during the docs build. Edit the canonical source in the Hive repository. +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/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 @@ -15,7 +15,7 @@ operator writes a bad rule. ## Decision Add CEL-based declarative triggers over a forge-neutral `NormalizedEvent` -([CEL trigger engine](https://github.com/hivecommons/hive/blob/v4/src/pkg/celtrigger/celtrigger.go)). Forge adapters map +([CEL trigger engine](https://github.com/hivecommons/hive/blob/v5/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, @@ -26,7 +26,7 @@ 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/hivecommons/hive/blob/v4/src/pkg/celtrigger/wire.go)). +([config wiring](https://github.com/hivecommons/hive/blob/v5/src/pkg/celtrigger/wire.go)). ## Consequences diff --git a/docs/content/hive/adr/0014-hub-spoke.md b/docs/content/hive/adr/0014-hub-spoke.md index 3daebe5..62f411d 100644 --- a/docs/content/hive/adr/0014-hub-spoke.md +++ b/docs/content/hive/adr/0014-hub-spoke.md @@ -1,4 +1,4 @@ -> **Synced from Hive.** This page is pulled from [hivecommons/hive@v4](https://github.com/hivecommons/hive/blob/v4/src/docs/adr/0014-hub-spoke.md) during the docs build. Edit the canonical source in the Hive repository. +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/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 @@ -19,7 +19,7 @@ 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/hivecommons/hive/blob/v4/src/pkg/hub/heartbeat.go), [hub registry](https://github.com/hivecommons/hive/blob/v4/src/pkg/hub/server.go)). +([heartbeat payload](https://github.com/hivecommons/hive/blob/v5/src/pkg/hub/heartbeat.go), [hub registry](https://github.com/hivecommons/hive/blob/v5/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 diff --git a/docs/content/hive/adr/0015-csp-style-src-scope.md b/docs/content/hive/adr/0015-csp-style-src-scope.md index 6654956..dd0a874 100644 --- a/docs/content/hive/adr/0015-csp-style-src-scope.md +++ b/docs/content/hive/adr/0015-csp-style-src-scope.md @@ -1,4 +1,4 @@ -> **Synced from Hive.** This page is pulled from [hivecommons/hive@v4](https://github.com/hivecommons/hive/blob/v4/src/docs/adr/0015-csp-style-src-scope.md) during the docs build. Edit the canonical source in the Hive repository. +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/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 @@ -7,7 +7,7 @@ Status: Accepted ## Context The dashboard's Content-Security-Policy carried one blanket `style-src 'self' -'unsafe-inline'` ([securityHeaders](https://github.com/hivecommons/hive/blob/v4/src/pkg/dashboard/server.go)). That single +'unsafe-inline'` ([securityHeaders](https://github.com/hivecommons/hive/blob/v5/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. @@ -48,7 +48,7 @@ protection. Split the single `style-src` into the two directives CSP Level 3 provides, and state a different verdict for each. -``` +```text style-src 'self' 'unsafe-inline' ← CSP2 fallback, unchanged style-src-elem 'self' 'unsafe-inline' ← the 7