From 092ce6bd4cfdae2d5a37fde3269f5078dca9b08a Mon Sep 17 00:00:00 2001 From: hivecommons-hive <280983584+hivecommons-hive@users.noreply.github.com> Date: Thu, 29 Oct 2026 06:33:03 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=96=20docs:=20resync=20the=20Hive=20do?= =?UTF-8?q?cs=20mirror=20from=20hive@v5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/content/crux/readme.md | 33 +++++ docs/content/dibs/mcp-registry.md | 18 ++- docs/content/dibs/readme.md | 50 ++++++- docs/content/dibs/roadmap.md | 13 +- docs/content/hive/acmm-policy-matrix.md | 33 +++++ docs/content/hive/agent-configuration.md | 27 +++- docs/content/hive/contributor-relay.md | 2 +- docs/content/hive/dashboard-sections.md | 78 ++++++++--- docs/content/hive/documentation-map.md | 3 +- docs/content/hive/hivectl.md | 8 +- .../hive/labels-and-control-signals.md | 88 +++++++++++-- docs/content/hive/security-model.md | 10 ++ docs/content/hotshot/linux.md | 47 +++++-- docs/content/hotshot/readme.md | 31 ++++- docs/content/hotshot/roadmap.md | 8 +- docs/content/hotshot/windows.md | 33 ++++- docs/content/pluk/readme.md | 38 +++++- docs/content/pluk/roadmap.md | 13 +- docs/content/promptargs/readme.md | 33 ++++- docs/content/rationguard/readme.md | 74 +++++++++-- docs/content/spektacular/getting-started.md | 123 +++++++++++++----- docs/content/spektacular/unknown-criteria.md | 22 +++- 22 files changed, 656 insertions(+), 129 deletions(-) diff --git a/docs/content/crux/readme.md b/docs/content/crux/readme.md index d0b6fd57..935fe34a 100644 --- a/docs/content/crux/readme.md +++ b/docs/content/crux/readme.md @@ -72,6 +72,18 @@ tar xzf crux_0.1.0_linux_amd64.tar.gz ./crux --version ``` +That archive example is for Linux on amd64. On macOS choose `darwin_arm64` +for Apple Silicon or `darwin_amd64` for Intel from the same release. Keep the +signature-verification command unchanged. macOS includes `shasum`, so verify +the selected archive against its signed checksum before extracting it: + +```sh +# Apple Silicon example; use darwin_amd64 in both places on Intel +grep 'crux_0.1.0_darwin_arm64.tar.gz$' checksums.txt | shasum -a 256 -c - +tar xzf crux_0.1.0_darwin_arm64.tar.gz +./crux --version +``` + The container image is signed the same way: ```sh @@ -117,6 +129,12 @@ crux kick scout "look at issue 42" # send it work crux stop scout # stop it ``` +While `crux run` is still active, `crux ps` should list `scout`; `crux logs +scout -n 50` should show the agent's startup or prompt. Output varies by +backend. If startup fails, check `command -v tmux` and `command -v copilot`, +then run and authenticate the agent CLI directly before retrying. Do not send +the example issue task until you have a repository and task you intend it to work on. + Agent files live under `--workdir` (default `$HIVE_WORK_DIR`, then `$HOME/.crux`). While `crux run` is in the foreground it opens a small control socket in that folder, and `ps`, `logs`, `kick` and `stop` use it @@ -127,6 +145,11 @@ to reach the live agent. `crux serve` keeps the runtime up and exposes it over HTTP+JSON, so other programs (or you, from another shell) can drive it: +The example assumes `/run/crux` already exists and is writable by the service +user; it is not normally writable by an ordinary macOS or Linux user. +For a local trial, use a socket path in a private directory you own instead +and set `CRUX_SERVER` to that same path. Do not make a shared socket world-writable. + ```sh # Serve on a unix socket. A unix socket is a file on disk that two # programs on the same machine use to talk to each other. @@ -206,6 +229,14 @@ The design record is ## What crux exposes +**Go integrator reference starts here.** If you only want to operate agents, +the [commands](#commands), [service setup](#run-it-as-a-service), and +[runbooks](https://github.com/hivecommons/crux/blob/main/runbooks/README.md) are enough. The remaining interfaces and routes +are for programs embedding or calling Crux. + +
+Advanced: Go interfaces, HTTP routes, host callbacks, and packages + Crux has three layers you can build on. Each one is a Go package in this repository. The first is the Go interface. The second is the same thing over HTTP. The third is what crux asks the host for in return. @@ -394,6 +425,8 @@ a refusal. - `hivecap`: the runtime-side adapters for the hive callback. - `serve`, `cli`, `cmd`: the HTTP server, the `crux` command, and the binary. +
+ ## Contributing The Go code in this repository is not edited here. It is a copy of diff --git a/docs/content/dibs/mcp-registry.md b/docs/content/dibs/mcp-registry.md index aa18e21f..95f4fa05 100644 --- a/docs/content/dibs/mcp-registry.md +++ b/docs/content/dibs/mcp-registry.md @@ -2,6 +2,17 @@ # Publishing Dibs to the MCP Registry +This is an operator procedure for publishing Dibs' listing in the Model +Context Protocol (MCP) registry, where agent clients discover the service. +To use Dibs from an agent, follow [client setup](/docs/dibs/readme#submit-ideas-from-your-agent) +instead; publishing a listing is not required. + +Before starting, have an up-to-date Dibs checkout, Git, GitHub CLI (`gh`), +`curl`, and `jq`; authenticate `gh` with an account allowed to run repository +workflows. DNS (Domain Name System) authentication also requires permission +to manage `hivecommons.dev` DNS records and the repository's Actions secrets. +Run checkout-relative commands from the repository root. + The root [`server.json`](https://github.com/hivecommons/dibs/blob/main/server.json) prepares the remote-only listing `dev.hivecommons/dibs`, using the namespace approved in [issue #375](https://github.com/hivecommons/dibs/issues/375#issuecomment-6215095421). @@ -43,11 +54,14 @@ gh workflow run mcp-registry-publish.yml --repo hivecommons/dibs ### DNS authentication key -Authentication is DNS-based: the apex TXT record on `hivecommons.dev` +Authentication is DNS-based: the apex TXT record (a text record on the bare +domain, not a subdomain) on `hivecommons.dev` (`v=MCPv1; k=ed25519; p=`) must match the Ed25519 private key (64 hex chars, as produced by the registry's [DNS authentication instructions](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/authentication.mdx#dns-authentication)) -stored in the `MCP_REGISTRY_PRIVATE_KEY` secret. To rotate, generate a new +stored in the `MCP_REGISTRY_PRIVATE_KEY` secret. Ed25519 is the signing-key +type; the public key goes in DNS, while the private key stays secret. +To rotate, generate a new key pair, replace the TXT record (remove the old one — a stale record is tried first and breaks verification), then update the secret. diff --git a/docs/content/dibs/readme.md b/docs/content/dibs/readme.md index 18aecaca..9949f6bb 100644 --- a/docs/content/dibs/readme.md +++ b/docs/content/dibs/readme.md @@ -8,7 +8,7 @@ [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/hivecommons/dibs/blob/main/LICENSE) -Marketplace of ideas for connecting ideators with hive-managed repositories. +A place to offer software ideas to projects and retain credit for them. > **Your idea, your credit, their code.** > @@ -16,16 +16,18 @@ Marketplace of ideas for connecting ideators with hive-managed repositories. Dibs is a two-sided marketplace that connects **ideators** — people who call dibs on ideas: great insight, but no time, tooling, or inclination to write -code — with **hive-managed repositories** whose AI agent swarms are hungry -for well-formed work. +code — with **hive-managed repositories**: projects that use Hive to run +coding agents under maintainer-chosen rules. 1. **Ideators post ideas** — public or private — in plain language / markdown. 2. **Repos opt in** to receive ideas, declaring topics and appetite. -3. **An LLM matches** ideas to repos that want them; both sides must say yes. +3. **A language model (LLM) matches** ideas to repos that want them; both the + idea contributor and the receiving project must accept the match. 4. On **mutual acceptance**, Dibs hands the ideator a **prefilled GitHub issue** — they file it themselves, under their own GitHub account, so the - issue is natively attributed to them (label `ideated`). The hive's AI - agents implement it. Dibs is just the matchmaker: it never files the + issue is natively attributed to them (label `ideated`). The receiving project + can then have its agents work on it under its own review rules. In this + default flow Dibs is just the matchmaker: it never files the issue for you. ## Ideators are first-class contributors @@ -43,7 +45,35 @@ public. Every implemented idea traces back to its ideator: the GitHub issue credits the idea's author, the resulting work carries that provenance, and the public **credit wall** (`/api/credits`, "Credit wall" in the UI) lists every ideator -whose idea shipped. An idea is a contribution. +with a settled idea: a GitHub issue URL has been recorded. This credits the +proposal, not proof that its implementation shipped or its issue was closed. +Settled ideas appear regardless of their visibility setting: settling a private +idea makes its credit facts (author, title/TLDR, target, issue URL, and time) +public, but not its body or private detail endpoint. + +## Try Dibs in your browser + +No local installation or Go toolchain is needed. Open +[dibs.hivecommons.dev](https://dibs.hivecommons.dev) to browse the public +surface; posting needs a Hive Hub sign-in and filing the issue needs a GitHub account. + +1. Sign in and describe your idea in plain language. Choose public or private + deliberately; unsettled private ideas are not included in the public wall. +2. Review suggested repositories and offer the idea to a suitable project. + For Hive-managed targets, both sides accept before issue filing. +3. Open the prefilled GitHub issue, review it, and file it yourself. +4. Confirm the resulting issue URL in Dibs. This step is **settlement**: + it records the handoff, not completion of the proposed work. Confirming also + publishes the credit facts above, even for an idea marked private. + +Non-Hive GitHub targets can skip the receiving-project acceptance step. +For settlement and privacy details, see the [consumer API](/docs/dibs/credit-wall-api). +To submit from a coding agent instead, see [MCP setup](#submit-ideas-from-your-agent). + +## Maintainer and developer reference + +The following sections cover running Dibs, its API, and local development, +not prerequisites for using the hosted site. ## Architecture @@ -297,6 +327,12 @@ still call `prompts/get` directly. ## Development +Requires Git and Go 1.27 or newer. Clone +`https://github.com/hivecommons/dibs.git`, then run these commands from the +checkout's top-level `dibs` folder. For authenticated local use, follow +[Running locally with sign-in](#running-locally-with-sign-in); fakehub is +for development only, not a production authentication service. + ```sh go test -race -count=1 ./... go run ./cmd/dibs # serves on :8080 at / diff --git a/docs/content/dibs/roadmap.md b/docs/content/dibs/roadmap.md index eee1ed6d..fcbfe16e 100644 --- a/docs/content/dibs/roadmap.md +++ b/docs/content/dibs/roadmap.md @@ -2,7 +2,8 @@ # Dibs Roadmap -Dibs is a marketplace for turning public ideas into claimable, settleable work. +Dibs connects idea contributors to projects. A project can accept an idea; +**settlement** records the resulting GitHub issue URL, not a completed implementation. This roadmap gives maintainers, ideators, and adopters a shared view of where the project is headed next. @@ -10,23 +11,23 @@ the project is headed next. - End-to-end ideation, matching, and settlement flows for GitHub issue-backed work. -- Intake support for common document formats with bounded PDF extraction and - malformed-input recovery. +- Idea intake from common document formats, with limits on PDF text extraction + and recovery when an uploaded document is malformed. - Repository registry, credit-wall mechanics, notifications, and guided server flows covered by automated tests. ## Near term 1. **Trust and abuse controls:** improve spam resistance for public idea intake, - including clearer moderation states and rate/quality signals for ideators. + including clearer moderation states and rate/quality signals for idea contributors. See the [proposed idea-intake trust design](https://github.com/hivecommons/dibs/blob/main/docs/idea-intake-trust.md); implementation follows in separate issues. -2. **Forge and repo coverage:** define what it takes to support non-GitHub issue +2. **Forge and repo coverage:** define what it takes to support issue hosts other than GitHub targets while growing the repository registry beyond hive-managed projects. 3. **Credit-wall integrations:** the [consumer API reference](/docs/dibs/credit-wall-api) documents eligibility, settlement state, rewards, and current experimental stability levels. Next, define compatibility guarantees and stabilize the - downstream contract. + promises made to applications that consume this API. ## Deferred / non-goals diff --git a/docs/content/hive/acmm-policy-matrix.md b/docs/content/hive/acmm-policy-matrix.md index 169683e3..200beaf2 100644 --- a/docs/content/hive/acmm-policy-matrix.md +++ b/docs/content/hive/acmm-policy-matrix.md @@ -125,6 +125,39 @@ Existing autonomous lanes can open issues, create PRs, and auto-merge on green C | operations (paused) | full | `operations-full.md` | | brainstorm | advisory | `brainstorm-advisory.md` | +## What hive will say on GitHub at each level + +ACMM constrains *agents*; the platform sweeps (sentinel, hold guard, stage +labels, supersession, …) are not agents and used to run unconditionally +over `project.repos`. Since the write-back containment gate +(`pkg/writeback`, see +[operator-reference.md](https://github.com/hivecommons/hive/blob/v5/src/docs/operator-reference.md#what-hive-writes-to-github-and-when)) +each *unsolicited* write-back kind has its own floor, and on a PR hive did +not open it additionally needs the review opt-in label +(`review.require_labels`, default `hive-review`). Hive-authored PRs and +issues, `/hive` command replies and dashboard-triggered actions are never +gated. Defaults (override under `writeback.kinds.`): + +| Write-back kind | L1–L3 | L4 | L5 | L6 | +| --- | --- | --- | --- | --- | +| `sentinel` comment + `sentinel-alert` label | dashboard only | dashboard only | opt-in label only | all PRs | +| `hold_gate_notice` (mergeability / drift) | — | hive PRs only | hive PRs only | hive PRs only | +| `stage_label`, `needs_decision_comment` on foreign PRs | internal tracking | internal tracking | opt-in label | opt-in label | +| `supersession_notice`, `duplicate_fix_notice`, `reporter_trust_hold`, `covered_by_pr_label`, `issue_close`, `parent_issue_edit`, `gate_comment` | — | — | opt-in label | opt-in label | +| `supersession_close`, `contributor_adopt`, `ci_rerun` | — | — | — | opt-in label | +| `verdict_label` | L3: opt-in label | opt-in label | opt-in label | opt-in label | +| `claim_comment` | — | opt-in label | opt-in label | opt-in label | +| `welcome_comment` | — | — | opt-in label | all items | +| `issue_file` (new hive-authored issues) | L3+ | yes | yes | yes | + +In practice: **L4 means hive files issues and talks only on its own PRs**; +**L5 adds comments and labels on PRs a maintainer labelled `hive-review`**; +**L6 lets sentinel and welcome comments reach unlabelled PRs**. A repo +listed only so an agent can file regression issues should carry +`writeback.per_repo..mode: issues-only`, which holds at every level. +`backfill: false` (default) additionally keeps every kind off items that +predate hive's first sight of, or write access to, the repo. + ## 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. diff --git a/docs/content/hive/agent-configuration.md b/docs/content/hive/agent-configuration.md index c883c99b..e4c061fd 100644 --- a/docs/content/hive/agent-configuration.md +++ b/docs/content/hive/agent-configuration.md @@ -129,7 +129,7 @@ older overlays, but new configs should use `bob.session_label`. # launch_cmd, prompt, tools, and skills at launch. ``` -The dashboard API can update this field through [`POST /api/effort/{agent}/{effort}`](https://github.com/hivecommons/hive/blob/v5/src/docs/api-reference.md#agents-and-controls). +The dashboard API can update this field through [`POST /api/effort/{agent}/{effort}`](https://github.com/hivecommons/hive/blob/v5/src/docs/api-reference/agents-and-controls.md). The dashboard shows a reasoning-effort dropdown next to the model picker for every method that has an effort control (`codex`, `agy`, `claude`, and `omp`). The value is validated at set time against the method's own set, so a `codex`-only level such as `minimal` is refused for a `claude` agent rather than stored and dropped at launch. For `omp`, the dropdown is per selected model: Hive reads `omp models --json` and uses that model's `thinking` levels, hiding the control for models that report no thinking support. Picking `default` clears the stored value; for `claude` and `omp` that means no effort flag at all and the CLI's own default. The dropdown persists through the same path as the model picker (`hive.yaml` plus the per-agent overlay under `agents_dir`), which is the durable path on a hosted spoke: a hand edit of the agent's file is reverted by the next sync, the dashboard write is not. Each dropdown change is recorded in the audit trail as `set_reasoning_effort` with the new value, like the other per-agent setting changes. The effort the agent was actually launched with is what the run rows and the `- hive:` PR trailer report, so a `claude` agent at `xhigh` shows `effort=xhigh` there and an agent with no stored effort shows none. @@ -1074,6 +1074,31 @@ The `hive/tracking` label also satisfies the tracker-issue check used by `/contr **Not the same thing as the contribute filters.** `hub.contribute_labels_mode` + its label list gate which issues are *handed out to external contributors* over `/contribute` — they have never gated the hive's **own** agents, so an operator who allow-listed a queue label there (a common setup for routing labeled issues to contributors) still had a hive whose own scanner could work every other open issue. `project.issue_filter.require_labels` is the agent-side gate; configure both if you want the same label to govern both lanes. +## Write-back containment (`writeback`) + +ACMM levels and label policy decide what *agents* may do. The `writeback` +block decides what the *platform* may say on GitHub without being asked: +sentinel alerts, hold-gate notices, stage labels, supersession and +duplicate notices, reporter-trust holds, and so on. Each kind has a minimum +level and, on PRs hive did not open, needs the review opt-in label +(`review.require_labels`, fallback `hive-review`): + +```yaml +writeback: + unsolicited: + min_level: 5 + require_labels: true + backfill: false + per_repo: + torch-spyre/torch-spyre: { mode: issues-only } + kinds: + sentinel: { min_level: 5, require_label: true, unlabeled_min_level: 6 } +``` + +Agent kicks on items already labelled for hive, hive's own PRs and issues, +and `/hive` command replies are never gated. The default matrix per level +is in [acmm-policy-matrix.md](/docs/hive/acmm-policy-matrix#what-hive-will-say-on-github-at-each-level). + ## When to add what | Add… | …when | diff --git a/docs/content/hive/contributor-relay.md b/docs/content/hive/contributor-relay.md index 310ba332..f4c8c436 100644 --- a/docs/content/hive/contributor-relay.md +++ b/docs/content/hive/contributor-relay.md @@ -1263,7 +1263,7 @@ That last line types a fresh prompt into a pane whose CLI is still mid-turn, int **A blip is not an abandonment until the grace window says so.** The re-adoption check above is zero-width for a `1006`: the hub processes the dead socket the instant its read fails, while the relay does not even start redialing for `BASE_RECONNECT_DELAY_MS` (1 s). So on a real network blip the release always won the race, and every blip wrote an `abandoned_disconnect` run row plus a "released: connection lost" activity row for a task that resumed one second later — 11 phantom rows across 17 completed tasks in one 3.5-hour run ([#7838](https://github.com/hivecommons/hive/issues/7838)). The visible booking now waits `HIVE_CONTRIBUTE_DISCONNECT_GRACE` (default 5 s); at the deadline the hub re-runs the re-adoption check and also asks whether a completion/failure row has since been written for the task id, and writes nothing if either is true. The short release cooldown — the double-assign hedge — is still booked immediately and still withdrawn by the resume, so the window is covered either way. -**Who wrote the PR does not change the stand-in rule.** Clanker PRs are adoptable on disconnect regardless of the owner's repo role: once the nudge window passes with the contributor's hive gone, the hub's hive adopts a maintainer's `author/clanker` PR exactly as it adopts anyone else's (`governor.labels.stage.adoption.maintainer_policy`, default `adopt`; `ask` parks it for an owner's Adopt, `never` opts out). +**Who wrote the PR does not change the stand-in rule.** Clanker PRs are adoptable on disconnect regardless of the owner's repo role: once the nudge window passes with the contributor's clanker gone, the hub's hive adopts a maintainer's `author/clanker` PR exactly as it adopts anyone else's (`governor.labels.stage.adoption.maintainer_policy`, default `adopt`; `ask` parks it for an owner's Adopt, `never` opts out). **The lease has to outlive the hub process.** Leases used to live only in the hub's memory, so a restart — which self-upgrade rolls ([#5391](https://github.com/hivecommons/hive/issues/5391)) make routine rather than rare — emptied the registry while every relay carried on working. After the roll *no* in-flight resume could match, and each one produced the same four lines above, this time for a reason the relay could do nothing about ([#5681](https://github.com/hivecommons/hive/issues/5681)). Observed 2026-09-02: revoked at 14:24:40, the same issue reassigned to the same relay at 14:24:44, discarding two and a half minutes of a turn that was progressing normally. The registry is now written to `/data/contributors/task-leases.json` (owner-only) on every assignment, renewal and release, and read back at startup, so a restart is just a longer-than-usual disconnect. diff --git a/docs/content/hive/dashboard-sections.md b/docs/content/hive/dashboard-sections.md index 2652a64a..c305482d 100644 --- a/docs/content/hive/dashboard-sections.md +++ b/docs/content/hive/dashboard-sections.md @@ -46,7 +46,8 @@ How many issues and pull requests Hive is tracking right now, and how many of th - **Total open issues** and **Total open PRs** count every open issue and every open pull request in the repositories you selected. Draft pull requests count too. - When the ForgeState cache (`forgestate.enabled: true`) has finished its first full scan of a repository, the two totals are read from that cache instead of from the GitHub search API. The cache is kept current by webhook events and its own low-rate refresh, so the totals do not cost a `/search/issues` request on every status refresh. The actionable, held, blocked and outside parts still come from Hive's own classification; whatever the cache counts that the classification has not placed yet lands in Outside's **hold-adjacent/other** part, so the sum always matches the total. - If GitHub rate-limits or fails the count request, the tiles keep the last good numbers and show **Counts stale since