Repository navigation
Description
src/docs/operator-reference.md keeps being touched by pull requests that are open at the same time. In the last 7 days 12 distinct PRs changed it, 58 pairs of them were open concurrently, and 0 merge conflicts or rebase failures were blamed on it. Every concurrent pair is a rebase someone (or the merge train) has to redo, and a 2053-line file makes each of those rebases slower and riskier.
This is a document, so the split is by section: each top-level ## area becomes its own file under a directory named after this one, with a short index page that links them (the way docs/api-reference.md became docs/api-reference/<area>.md). Keep every heading anchor reachable from the index.
Evidence
| metric | value |
|---|---|
| window | 7 days |
| distinct PRs | 12 |
| concurrent PR pairs | 58 |
| conflicts attributed | 0 |
| lines | 2053 |
| kind | doc |
| score | 87.0 |
PRs in window: #15405, #15442, #15449, #15450, #15455, #15468, #15471, #15485, #15486, #15491, #15497, #15506
Sections
Agent CLI session recyclingAgent Go toolchain shimApp self-merge sweep (auto_merge)Configuration blocksDelivery SLAFleet breakerGitHub API quotaGitHub API quota — who is spending it?Governor cadence and budgetImage provenance and tagsMerge-hotspot advisor (governor.hotspot_*)Minimum required configurationNotable fieldsOpen-PR dispatch guard and duplicate-fix sweep (scanner)OpenTelemetry: GitHub API spend and cache freshnessRuntime diagnostics (debug,GOMEMLIMIT,mem:log line)Scheduled-upgrade progress and historySelf-reported issuesShared-CI rerun sweep (shared_ci_rerun)Stage labels (governor.labels.stage)Supersession sweep (supersession_sweep)Suspicious-activity alerts (sentinel)What hive writes to GitHub, and when- ``HIVE_GITHUB_TOKEN
permissions - ``cmd/hive
flags and environment
Split proposal
src/docs/operator-reference/README.md— index linking every sectionsrc/docs/operator-reference/agent_cli_session_recycl.md— section “Agent CLI session recycling”src/docs/operator-reference/agent_go_toolchain_shim.md— section “Agent Go toolchain shim”src/docs/operator-reference/app_self_merge_sweep_aut.md— section “App self-merge sweep (auto_merge)”src/docs/operator-reference/configuration_blocks.md— section “Configuration blocks” and the 21 remaining sections
Don't splinter
- At most 4 resulting files, each at least 150 lines; fewer is better.
- No behaviour change; the package, its exported API and every import path stay the same.
- Tests move with the code they cover; no new test helpers.
- One PR; land it when the file has no open PRs against it.
Filed by the hive's merge-hotspot advisor (GET /api/hotspots). It will not file another issue for this file while this one is open.
Activity
hivecommons-hive commentedon Oct 29, 2026
🔒 Claimed by @Karibhou (contributor on hive hosted-available-oke-11-placeholder-r05x). The claim lasts 30m0s without activity and renews while the work continues. Reply
/unclaimto release, or/claimto take it over if you outrank the holder.hivecommons-hive commentedon Oct 29, 2026
🔓 Claim by @Karibhou released (lease expired).
📖 docs: split the operator reference
📖 docs: split the operator reference
📖 docs: split the operator reference
📖 docs: split the operator reference
📖 docs: split the operator reference (#15731)