README.md

Design documents

Longer-form design records for work that needed a written argument before it was built: the problem, the constraint that shaped the answer, and the phases the work was cut into. They are the reference record for a decision, not operator documentation — the operator-facing page for a shipped feature lives in src/docs/ and is the one to read first.

Unlike an ADR, which is deliberately short and captures one decision, a design document here carries the full reasoning and is not rewritten as later stages ship. So each entry below states its status, and that status is the thing to check before treating a page as current behaviour:

• Shipped — the described behaviour is live.
• Partly shipped — some phases landed; the page still describes work that does not exist yet, and says which.
• Design only — accepted plan, no implementation. Read it as intent.
• Historical — kept as an accurate record of something already decided; details reflect the era they were written in, on purpose.

Records

• Crux: the agent runtime boundary — Stage 1 shipped (v5); Stage 2 blocked on pkg/config. RFC #13536: names the agent runtime inside Hive (pkg/agent and its ring) as Crux, lists what stays in Hive, records the staged plan (in-repo boundary → nested module → crux serve) and the naming decision. Inbound and outbound ratchets in src/internal/testutil/crux_*_ratchet_test.go, the tmux funnel, crux.Runtime, Crux-owned value types, CI path filters and the crux CLI are live; the nested module waits on an agent-runtime config leaf (the doc lists the measured outbound edges and prerequisites).

• Crux: generic tool policy for the MITM proxy — Design only (proposed). #14228, child of #14138: a shared operation vocabulary with per-forge adapters, a relay(<command>) verdict, deny-by-default for unrecognised operations, and the proxy's evaluation pipeline written down once. It also covers migrating behind a parity test and treating #14211 as the first non-GitHub adapter.

• PR follow-up session resume - shipped (v5, default off). #9583: ties each agent-opened PR to the CLI session that authored it (a pkg/turn envelope per PR) and feeds CI failures, changes-requested reviews, new review-bot threads and comments from people with write access back into that session without /clear while it is still live. When the session is gone (a restart or the next regular kick), the follow-up takes the fix-before-new path and the agent's next kick carries a compact handoff note of the PR's original reasoning. Pointers are pruned on merge or close; a live-review soak is the remaining follow-up.

• Achievement system 2.0 — shipped (v5). Spektacular-ready spec for #8832: teamwork-first Solo/Dual/Fireteam/Raid tiers, local-model achievements, the “local always wins” mastery tier, dark-pattern guardrails, anti-gaming rules, data sources, and shipped dossier/leaderboard rollout.

• External workflow admission - Gate 0 decided; Gate 1 pilot shipped (v5, default off). Records the #8201 Gate 0 selection for #8302 (option 2, one bounded report-only Flue generation workflow through the existing contributor protocol, the source-to-guarantee matrix, native Flue receipt probe, conformance split) and the #8361 Gate 1 pilot: the engine-neutral pkg/extwork binding, the Flue adapter and deterministic fixture, the side-effect inventory, operational status and recovery, and the local-versus-binding comparison, and the OMP workbench as the second host behind the same adapter (#8361 step 9, answering #6899: relay-channel frames, accept before context, progress events, receipt binding, confinement note). Publication remains deferred.

• Mobile checkpoint payload — shipped (v5). The single server-owned RunCheckpointPayload behind GET /api/runs/{key}/checkpoint that mobile, chat, push and PWA checkpoint prompts render instead of rebuilding run state per surface (src/pkg/dashboard/api_runs_checkpoint.go).

• Headroom library boundary — shipped (v5). The rotation.HeadroomSource seam (#8753) that lets the provider headroom probers live in the standalone ccleft library while pkg/rotation keeps the Hive-facing reading types (src/pkg/rotation/ccleft.go).

• Run artifacts — shipped (v5). How long-running runs keep review state in the existing plan and lease artifacts with no new store, CRD, DSL, or GitHub credential path: multi-repo wave annotations and the wave barrier (#8388), deterministic offline finding identity (#8396), the receipt-chain provenance guard that refuses a kick on a stale plan (#8402), and the informational Hive-Run/Hive-Plan/Hive-Spec commit trailers the dashboard trace resolves (#8389). The operator page for the stage runner itself is src/docs/spektacular.md.

• Escalation surfaces: email and push — partly shipped (v6). Track 6 of the v6 epic (#7563): a severity-routed pkg/escalate fan-out feeding SMTP mail (immediate escalations + daily digest) and push/on-call sinks (ntfy, Pushover, PagerDuty), with inbound reply-to-act email deliberately last and defaulting off. The outbound half landed on v6 in #7618; the inbound reply-to-act path is still unbuilt.

• Slack integration on the chat spine — shipped (v6). Track 3 of the v6 epic (#7563): Socket Mode transport as a pure chat.Backend, mrkdwn translation at Send, fail-closed allowlist kept in the spine. The backend landed on v6 in #7585, on the spine from #7572; the Events API accelerator remains future work.

• Gate-integrity invariants for agent lanes — design only / proposed. Names the write-gate invariants for agent lanes: no history rewrites on branches a lane did not create, no agent sign-off on other authors' commits, and ACMM demotion for gate manipulation.

• Capability-aware contributor task assignment: the hub/relay decision boundary — proposed (awaiting sign-off on #6825). Grounds RFC #6825 in the v5 contributor protocol: the hub owns selection while the relay owns launch and veto, capability matching fails closed the way the quota guard's unknown ⇒ HOLD does, mixed-version behaviour reuses the #6954 relay_capabilities/DeclaresCapability matrix, and the #6541 in-flight quota park is resolved toward a first-class capacity verdict rather than task_failed/environment. Self-declared capability stays input, never authority. Leaves the tier vocabulary, evidence source, and lease-accounting for the park path as open questions for maintainers.

• Automatic repo ACMM onboarding reconciler — declined (RFC #6235 closed; #6111 on hold). Design for per-repo ACMM targets, gap-to-work reconciliation, explicit agent-actionable / needs-human / waived classification, and the anti-gaming controls required before agents generate onboarding PRs. Credits RFC #6235 and relates it to #6111, #6264, and #6208.

• Hub master secret rotation — partly shipped. Why every signing value on the platform (heartbeat bearer, session cookie, session and SSO Ed25519 seeds, impersonate, terminal, invite keys) is a pure function of one master with no generation marker, which makes rotation a fleet-wide flag day, and the generations design that ends it. The foundational generations code and the session-cookie domain have landed (src/pkg/hub/hub_generations*.go, hub_cookie_generations.go); the remaining per-domain adoptions listed under "Follow-on PRs" are still pending.

• Wrapped master delivery to push-reported spokes — design only. Read it after master-key-rotation.md: rotation is complete on the hub and delivers nothing to the two thirds of the fleet on push-reported clusters, which the hub cannot write to by design. Records Option D — the spoke generates a keypair, publishes the public half over its own outbound heartbeat, and the hub seals each new master to it — and why Options A and B were rejected. Earlier unwired wrapkey primitives were removed as dead code in #5697, so no sealing primitive or spoke-side wrapping-key lifecycle is currently implemented.

• PR reach telemetry — partly shipped. The design behind attributing merged code to what is actually running, and the anchoring rule that governs it: merged ≠ deployed ≠ running, so reach must attribute to the commit executing in the binary, never to the merge or publish event. Phase 1 (version-stamped spans, hive.component attribute) and phase 2a (per-component reach counters) have landed; phases 2b (#3994) and 2c (#3995) are pending, and this is the page to read before implementing them. Its v2/pkg/... path examples are deliberately historical — PRs merged before the v2/ → src/ rename report those paths from the forge API forever, and the component mapper still handles both eras (src/pkg/reach/mapping.go).

• Sourcing token metering from ccusage behind a tokens.Source seam — proposed. Design for replacing most hand-written token parsing with a pinned offline ccusage subprocess behind a tokens.Source seam, while preserving Hive's attribution layer, native-versus-estimated cost labeling, and Bob coverage. Credits RFC #6234 and incorporates the v5 #6142 scanner cleanup.

• Knowledge system and the ACMM developer journey — partly shipped. The layered llm-wiki knowledge base — layers, subscriptions, the pre-seeded deployment vault, and the extraction/promotion APIs — as the mechanism for making Hive useful from ACMM Level 1 upward. The wiki layers, the seed vault, and programmatic extraction are live; the scheduler.RunCurator(schedule) wiring this document plans is not implemented, so knowledge.curator.schedule is accepted and defaulted but read by nothing. See Knowledge curator for the programmatic path that does work today.

• The Tool-Approval Desk — shipped (vertical slice), default-off. RFC #4000: one decision point every approval-shaped request resolves through, replacing four independently-grown gates with one testable function, keyed on the hive's ACMM level, with operator policy expressed as data and an auditable record of why each action was allowed or blocked.

• RFC: re-entrant conversation-as-state agent turn model — design only / proposed (RFC #4002). The original RFC text: moving agent runtime state out of persistent tmux-hosted CLI processes into serialized, re-entrant turn state. Read the staged follow-ups — the state inventory below, the turn-model spike, and the handoff evaluation — for what has actually been investigated since.

• Agent state inventory — where in-process suspended state lives today — historical (stage 1 of RFC #4002). Docs-only inventory of the state suspended inside agent processes and tmux memory buffers, verified symbol-by-symbol against v5 at the time of writing; the first step of the maintainer-agreed sequence inventory → journaled prototype → handoff evaluation.

• The agent turn model and where in-process state lives — spike / investigation, steps 1 and 2 complete. A cited map of how hive drives an agent turn today and which state does not survive restart, plus an isolated pkg/turn prototype: serialized conversation and operation state, a re-entrant structured Step, atomic scrubbed persistence, and a replay test that kills a contribute-shaped turn at every operation boundary. It is not wired to the tmux loop or contributor relay, and takes no production decision. Read it before steps 3-4, particularly for the unresolved fork: backend-specific resume envelopes versus an API-shaped backend hive owns.

• Evaluating a handoff path for the re-entrant turn model — spike / investigation, no decision taken. Step 3 of the same RFC. Its finding is that hive built handoff's two hard mechanisms twice: as of #6056 pkg/convergence/mutation (#4255) is wired around the runtime external-effect boundary, while pkg/turn remains a second journal, and nothing imports either. No single store has all three properties handoff needs — atomic claim, cross-process serialization, corruption-resistant persist — and the three partial implementations each hold a different two. Recommends no queue, and not yet, with ordered prerequisites, and narrows the beads-checkpointing challenge to the one variable still undecided.

• Copilot per-repo cost capture at the MITM proxy — investigation, no decision taken. Phase 4 of epic #4836, which asked whether Copilot token usage can be captured per request with repo context and timestamps at the proxy. Its answer is a recommendation against building phase 4 as scoped: per-request usage is available and already captured (src/crux/proxy/github_proxy_copilot.go:236), but per-request repo context is not available at the proxy in any form, and the nearest substitute — a "last api.github.com repo seen" from ExtractRepo — is an inference from read traffic, weaker than the audited repo= events phase 3 already joins against. Read it for the one separable finding that is worth doing: the proxy has the timestamps and InferenceSink discards them, so persisting per-request usage with its timestamp would move Copilot from "structurally impossible" to phase 3's existing join, in pkg/tokens only and off the request path.

• GitHub @-mention triggers — shipped (v6), all three phases. The first inbound GitHub trigger: a human summons an agent by mentioning the App on an issue or PR, mirroring the Linear agent-session path (pkg/linearagent) that already exists. Poll-first transport so it works on push-reported spokes, a mention grammar with ask <agent> routing under the linear.session_agent resolution rule, a kick built like the Linear responder's, replies through Converse on the existing watcher write path with no new outbound surface, and seven guards each mapped to a mechanism that already has a runtime (dashboard role list, review_bots loop list and per-thread cap, ioscan input enforcement). Records the #5591 lesson: the channel type ships with its runtime or not at all. Credits RFC #7483. Phases 1–3 landed on v6 in #7582, #7597, and #7623; the maintainer questions the page raised are all answered there.

• Discord reaction-consensus issue promotion — proposed. Design for turning Discord community reaction consensus into the same approval label that project.issue_filter.require_labels already uses, while keeping the bot credential-free and having Hive perform the audited, server-side allowlisted label write. Credits RFC #6239 and records the Discord intents/partials trap before implementation.

• hive tui — a terminal dashboard for Hive — shipped (v1). The design record for the k9s-style terminal client tracked in #4907: scope, the fixed architecture decisions, the default 2x2 pane layout, the keybinding table, and the golden-file testing convention. Every v1 sub-issue has landed; src/docs/hivectl.md is the operator reference for what actually shipped and the one to read first — this page is read afterward, for the reasoning and the two corrections it carries against the sub-issue bodies: their v2/... paths are pre-#3996 spellings that map to src/pkg/tui/..., and dashboard/openapi.json — which the epic names as the contract for every client task — originally published 32 of the dashboard's 298 routes and no write operations at all, closed by #5023.

• Agent host confinement on the default (unconfined) launch path — investigation, no decision taken. #4918: an agent doing correct, benign work on an assigned third-party repo ran that repo's own test suite, which reached the operator's real bootloader via rpm-ostree kargs, stopped only by polkit. Maps the default tmux launch path (src/pkg/agent/manager.go, bin/agent-launch.sh) against the three deployment modes (hub pod, containerized contribute-hive, contribute-hive ... local) and establishes precisely what #4938's merged host-state denylist covers — the reported command family, on the Bash tool surface, by bare command word — and what it leaves open: absolute-path/wrapper invocation, unlisted polkit-reachable actions, non-Bash tool surfaces, and plain filesystem writes outside any denied command. Surveys confinement options (Podman sandbox, bwrap/systemd-run, seccomp, dedicated low-privilege UID, a disposable VM) with real costs, and recommends closing the existing Podman sandbox's double opt-in gate (src/pkg/config/config.go) for contribute-hive once its CI coverage gap is closed, keeping the denylist as the floor elsewhere.

Adding a document here

Add the page, then add a line above saying what a reader gets from it and its status. A design document that outlives its implementation is normal and fine; a design document a reader mistakes for current behaviour is not, which is what the status is for.

Pages in this directory are reached through this index rather than through src/docs/documentation-map.md directly, the same delegation adr/ uses. That is also why the docs-index reminder workflow does not flag them: it is scoped to the top level of src/docs/ on purpose, so a directory with its own README never trips it.