Skip to content

📝 RFC: cut over Crux development to hivecommons/crux on 2026-11-16 #17004

Open

Description

@clubanderson

Refs hivecommons/crux#114 · RFC #13536 · tracker #14138 · publishing doc src/docs/crux-publish.md

Status: RFC only. Per the maintainer, nothing is ported until 2026-11-16. This issue is the plan, the inventory and the checklist; no branch, PR, tag, workflow change or crux push has been made for it. The flip is Monday 2026-11-16; 11-09 → 11-13 is prep and the window for the phase-1 work-services PRs (S0/S1/S2/S7) to land in hive src/crux.

Goal

Make hivecommons/crux the source-of-truth repository for the Crux agent runtime. Development moves there; hive consumes github.com/hivecommons/crux as an ordinary Go dependency. The publish/sync pipeline (src/scripts/crux-publish.sh + .github/workflows/crux-sync.yml) is retired.

1. Inventory of the coupling (measured on origin/v5 @ 22f9f1d59, 2026-11-07)

Module graph

Piece Today
src/go.work use ( . ./crux ) — the two-module workspace (#13536 Stage 2)
src/go.mod:100,102 require github.com/hivecommons/hive/crux v0.0.0-00010101000000-000000000000 + replace github.com/hivecommons/hive/crux => ./crux
src/crux/go.mod module github.com/hivecommons/hive/crux, go 1.26.10, 49 packages, 791 .go files, requires nats-server/v2 v2.15.2 + nats.go v1.55.0 (the lanes JetStream code)
Crux → root module imports 0 (src/crux never imports `github.com/hivecommons/hive/pkg

Import sites in the root module (src/, excluding src/crux)

  • 279 Go files import github.com/hivecommons/hive/crux… (128 non-test, 151 test).
  • 422 import lines, across 36 distinct crux packages. Top: crux 160, crux/cruxtest 61, crux/logscrub 32, crux/toolapprove 24, crux/watchdog 17, crux/config 12, crux/proxy 11, crux/agentparse 10, crux/runtime 9, crux/openrouter 8, crux/api/callback 8, crux/watsonx 7, crux/effects 7, crux/claude 6, crux/api 6, crux/skillreg 5, crux/pushbroker 5 … crux/lanes 2, crux/kubejob 2, crux/agent/tmux 1.
  • Non-Go references to the old module path: src/go.mod, src/go.work, src/internal/testutil/dashboard_import_allowlist.txt (lists github.com/hivecommons/hive/crux + crux/<pkg> as allowed dashboard imports), src/docs/design/crux.md, src/docs/crux-cli.md, src/docs/crux-serve.md, src/docs/crux-publish.md, src/scripts/crux-publish.sh, src/scripts/test-crux-publish-keep.sh.

Publish pipeline (hive side)

  • src/scripts/crux-publish.sh (136 lines): clears a crux checkout except KEEP=(.git .github .goreleaser.yaml Dockerfile Dockerfile.goreleaser LICENSE README.md .gitignore .golangci.yml .dockerignore runbooks), rsyncs src/crux in, moves src/crux/README.md → docs/MODULE.md, rewrites github.com/hivecommons/hive/crux → github.com/hivecommons/crux in go.mod and every *.go, writes .hive-sync, then GOWORK=off go build ./... && go vet ./... && go mod tidy.
  • .github/workflows/crux-sync.yml: triggers push: branches [v5], paths: src/crux/**, src/scripts/crux-publish.sh, the workflow, push: tags crux/v*, workflow_dispatch (has dry_run). Secrets: CRUX_SYNC_TOKEN (fallback TOPUP_PUSH_TOKEN). One commit per sync onto crux main as hive-release[bot]; a crux/vX.Y.Z tag pushes tag vX.Y.Z to crux at the already-synced commit (never moves main). Registered in .github/release-lines.yml:148-152 as crux-sync.yml: [-v4].
  • Last five runs today (2026-11-07 04:22 → 15:02 UTC) all success; crux main = fe54cd5 = hive c549296b8cfb (per .hive-sync).

Crux repo today (hivecommons/crux)

  • Default branch main, public, issues on. Every commit is a sync commit (🌱 sync: hive@<sha> (src/crux)); .hive-sync says "File issues and pull requests in hivecommons/hive".
  • Releases: v0.1.0 (2026-10-25), v0.2.0 (2026-10-29), v0.3.0 (2026-11-04, hive a6fc111b02ad). main is 25 sync commits ahead of v0.3.0.
  • Hand-maintained scaffolding: .github/workflows/{ci,release,sync-guard}.yml, .github/scripts/{check-action-pins,check-file-size-ratchet,coverage-floors}.sh (+ self-tests), .github/go-file-size-ratchet.txt, .goreleaser.yaml, Dockerfile, Dockerfile.goreleaser, .golangci.yml, runbooks/, README.md.
  • ci.yml already runs: "Module is standalone" (GOWORK=off), go test -short -race all-but-agent on ubuntu+macos, ./agent/... on ubuntu-24.04 with tmux, coverage floors (coverage-floors.sh with THRESHOLD=90 and per-package floors crux/agent=89 crux/proxy=89 crux/sandbox=98 crux/pushbroker=99 crux/kubejob=90 cmd/crux=75 crux/cli=92 — identical to hive's coverage-hourly.yml), golangci-lint, govulncheck, gosec, action-pins, Go file-size ratchet, crux serve smoke (scripts/smoke.sh).
  • sync-guard.yml: fails any PR from a non-hive-release[bot] actor that touches anything outside the scaffolding allowlist and comments "open this against hivecommons/hive". This must go on flip day or nobody can develop there.
  • release.yml + .goreleaser.yaml: on tag v* → darwin/linux × amd64/arm64, cosign, GitHub release, ghcr.io/hivecommons/crux. Unaffected by the cutover.
  • Labels already present: full stage/*, role/*, author/*, dco/no-dco, needs-rebase, size/* — i.e. hive already manages hivecommons/crux (recent crux PRs fix: split long kick messages into sub-kicks for reliable delivery #109–fix: remove lock button, use pin-in/out pill as toggle #123 are by app/hivecommons-hive; crux#66 appeared in the hive dashboard). Open: only crux#114 (RFC, stage/010-actionable, approved-direction). No open PRs.
  • Missing in crux: changelog.d/ + fragment guard, DCO check (hive's dco/no-dco labels are applied by hive, but no required status), CONTRIBUTING/AGENTS guidance, docs beyond docs/MODULE.md + runbooks.

Hive CI / build surfaces that address ./crux/...

  • v2-ci.yml:195-214,244: builds ./cmd/crux (root host) and (cd crux && GOWORK=off go build ./cmd/crux); runs (cd crux && GOWORK=off go test -race ./lanes ./api ./serve); crux smoke (working-directory: src/crux); go vet ./... ./crux/....
  • v2-tests.yml:94-203, 838-1001: crux/agent sliced N ways (TEST_PACKAGE=github.com/hivecommons/hive/crux/agent, go test -c -race -cover ./crux/agent); .github/scripts/crux-scope.sh (72 lines) classifies PR diffs as crux-only / mixed / non-crux; .github/scripts/affected-go-packages.sh:25-151 lists ./crux/... and treats crux/go.mod|go.sum as module-graph changes.
  • coverage-hourly.yml:196,222-322,348-371: tests ./crux/... and keys floors as crux/<pkg> (the 7 floors above).
  • crux-file-size-ratchet.yml: sparse-checks-out src/crux and runs crux's ratchet script pinned to crux 13372ca7 (2026-10-29).
  • go-security-analysis.yml:194,276-327: govulncheck ./... ./crux/..., a separate "Scan crux module" gosec step working-directory: src/crux, CodeQL/args: ./... ./crux/....
  • Docker: src/Dockerfile:40 COPY src/crux/go.mod src/crux/go.sum ./crux/ (needed because of the replace), :86 builds /crux from root ./cmd/crux (hive's host binary, src/cmd/crux/definitions.go), :564 ships /usr/local/bin/crux; src/Dockerfile.contributor:43,51,553 builds ./crux/cmd/crux (the module's own binary) for the contributor image; .oss-scanner/Dockerfile:57-84 builds/tests ./crux/... and names ./crux/proxy/... ./crux/logscrub/... ./crux/pushbroker/... ./crux/sandbox/... ./crux/toolapprove/...; src/scripts/generate-notice.sh:175 (NOTICE generation over ./... ./crux/...).
  • Justfile:344-2482 only invokes the crux binary (cline-turn) — unaffected by module path.
  • Docs: 22 files under src/docs/ carry 165 src/crux/... citations (design/crux.md, crux-cli.md, crux-serve.md, crux-publish.md, security-model.md, design/agent-host-confinement.md, design/crux-tool-policy.md, adr/0026-…, troubleshooting.md, …). src/scripts/check-docs-citations.py verifies every repo-local path:line citation exists → all 165 become DRIFT the moment src/crux is deleted (it ignores URLs, so the fix is to rewrite them to https://github.com/hivecommons/crux/blob/<tag>/<path>#L<n>). AGENTS.md:10-11 and CONTRIBUTING.md:24,64-68 describe the two-module workspace.
  • Guards: src/scripts/ edits require re-pinning TRUSTED_SCRIPTS_TREE in .github/scripts/integration-governance.cjs:12 (deleting crux-publish.sh/test-crux-publish-keep.sh is such an edit). changelog-fragment-guard has no path filter (job-level), so the flip PR needs a changelog.d/ fragment. src/pkg/fleetreport/{fleetreport.go:753-810,slogfeed/slogfeed.go:31} cite src/crux/... in comments only. No sentinel allowlist references src/crux.
  • Branch lines: v6-topup.yml forward-merges v5 → v6, so v6 also carries src/crux and will receive the flip by forward-merge; v4 has no src/crux.

Hive-managed-repo knob

project.repos in hive.yaml (src/pkg/config/config.go:1005, ProjectConfig.Repos; per-agent repos: allowlist in src/docs/agent-configuration.md:283, docs/per-repo-agents.md). The hive-on-hive fleet already lists hivecommons/crux (evidence above). After the flip the change is policy, not config: agents may open code PRs against crux once sync-guard.yml is removed; specialists that today are scoped repos: [hive] for crux work should add crux.

2. The plan

Owners

  • Maintainer (@clubanderson): approves the freeze, cuts tags, flips sync-guard, merges the flip PR, re-pins TRUSTED_SCRIPTS_TREE.
  • Crux CI port: one PR against crux (scaffolding only, allowed by sync-guard) — lanes/api/serve integration lane, changelog.d/ + guard, DCO/emoji conventions, CONTRIBUTING.
  • Hive flip PR: one PR against hive v5 (goes to v6 by forward-merge).
  • Hive agents: keep triaging crux issues/PRs as today; no new config until the flip.

Phase 0 — prep (Mon 11-09 → Fri 11-13; no cutover work merges)

  • Land phase-1 work-services PRs in hive src/crux (S0, S1 feat/crux-caller-principal — currently one local, unpushed commit 6190572ff; S2 feat/crux-contained-run — empty worktree; S7). Each publishes to crux main automatically via crux-sync. Deadline: Fri 11-13 18:00 UTC; anything not merged by then is re-targeted to crux after the flip (its import paths are rewritten with the same sed as §flip step 3).
  • Crux-side CI port PR (scaffolding only, passes sync-guard): add test (lanes/api/serve) -race -timeout 3m lane mirroring v2-ci.yml:203-205; add changelog.d/ + a port of changelog-fragment-guard; add DCO (git commit -s) requirement to CONTRIBUTING + a DCO status (hive's dco label flow already exists); .github/release-lines.yml equivalent is not needed (single main). Coverage floors already match hive's; note them as per-package floors in the crux README.
  • Import-rewrite dry run on a scratch branch (not pushed): the sed in §flip step 3 leaves 0 old imports in the root module (verified 2026-11-07 then reverted); the build must be re-verified on flip day against the real tag because the dry run also needs replace github.com/hivecommons/crux => ./crux or the tag to exist.
  • Write the docs-citation rewrite (165 citations → crux blob URLs pinned to the flip tag) as a script in the flip PR.
  • Confirm CRUX_SYNC_TOKEN/TOPUP_PUSH_TOKEN still have Contents:write on crux (needed once more for the final publish and the rc/v0.4.0 tag).

Phase 1 — freeze and last publish (Fri 11-13 after the last phase-1 merge; or Mon 11-16 08:00 ET if S-PRs slip)

  1. Announce freeze: no PR touching src/crux/** merges after this point (hive-side: ask the sentinel/merge-train to hold src/crux PRs; simplest is a maintainer /hold).
  2. Confirm the last crux-sync push run is green and crux main .hive-sync names the frozen hive sha.
  3. Tag the release candidate from hive so the existing tag path does the work: git tag crux/v0.4.0-rc.1 <frozen-v5-sha> && git push origin crux/v0.4.0-rc.1 → crux v0.4.0-rc.1 lands at the matching main commit; release.yml builds binaries/image.
  4. Disable the publish workflow: unset GITHUB_TOKEN && gh workflow disable crux-sync.yml --repo hivecommons/hive (reversible; the file is deleted in the flip PR).

Phase 2 — flip crux to source of truth (Mon 11-16, morning)

In hivecommons/crux (one PR, then direct commits by maintainers are fine):

  1. Delete .hive-sync; delete .github/workflows/sync-guard.yml; set branch protection on main (required: CI, coverage floors, DCO, changelog guard).
  2. docs/MODULE.md → becomes the real module README content; strip the "Synced from hive … edit it there" banner; README "File issues in hive" → "here".
  3. Tag v0.4.0 on the rc commit once CI is green: git tag -s v0.4.0 v0.4.0-rc.1^{} && git push origin v0.4.0 (crux release.yml cuts the release; bump Formula/crux.rb in hivecommons/homebrew-hive).

Phase 3 — flip hive to consume crux (Mon 11-16, same day, one PR ⚠️ crux: consume github.com/hivecommons/crux@v0.4.0, retire src/crux)

Exact sequence, run from src/ on a fresh origin/v5 worktree:

OLD=github.com/hivecommons/hive/crux NEW=github.com/hivecommons/crux TAG=v0.4.0
# 1. drop the nested module from the workspace and the replace
cat > go.work <<'EOF'
go 1.26.10

use .
EOF
sed -i '' -e "/^require ${OLD//\//\\/} v0.0.0-00010101000000-000000000000$/d" \
          -e "/^replace ${OLD//\//\\/} => .\/crux$/d" go.mod
# 2. delete the vendored copy (49 pkgs, 791 files)
git rm -rq crux
# 3. rewrite the 422 import lines in 279 files (anchored on the quote; same two substitutions crux-publish.sh uses)
grep -rl --include='*.go' "\"$OLD" . | xargs sed -i '' -e "s#\"$OLD/#\"$NEW/#g" -e "s#\"$OLD\"#\"$NEW\"#g"
sed -i '' "s#$OLD#$NEW#g" internal/testutil/dashboard_import_allowlist.txt
# 4. pull the dependency
go get $NEW@$TAG && go mod tidy
gofmt -l . | head   # expect nothing: sed keeps import blocks sorted (hive/crux → crux sorts earlier; run gofmt -w on any listed file)
# 5. prove it
go build ./... && go vet ./... && go test -short ./pkg/dashboard/... ./cmd/crux/...
grep -rn "\"$OLD" --include='*.go' . | grep -q . && echo "rewrite incomplete" && exit 1

Then, in the same PR:

  • CI: v2-ci.yml — drop the standalone-module build (cd crux && GOWORK=off …), the ./lanes ./api ./serve lane, the crux smoke, ./crux/... from go vet; v2-tests.yml — delete the crux/agent slice jobs (TEST_PACKAGE=…/crux/agent), delete .github/scripts/crux-scope.sh and its callers, drop ./crux/... + crux/go.mod|go.sum from .github/scripts/affected-go-packages.sh; coverage-hourly.yml — drop ./crux/... from the two go test lines and the 7 crux/*/cmd/crux floors (keep cmd/crux=75 if the root host binary stays); delete crux-file-size-ratchet.yml; go-security-analysis.yml — drop ./crux/... and the "Scan crux module" step; .github/release-lines.yml — remove the crux-sync.yml entry (the guard fails on a registered-but-missing workflow).
  • Workflows/scripts: git rm .github/workflows/crux-sync.yml src/scripts/crux-publish.sh src/scripts/test-crux-publish-keep.sh; re-pin TRUSTED_SCRIPTS_TREE in .github/scripts/integration-governance.cjs:12 to git rev-parse HEAD:src/scripts of the post-merge tree.
  • Docker: src/Dockerfile:37-40 and src/Dockerfile.contributor:43 — remove COPY src/crux/go.mod src/crux/go.sum ./crux/; Dockerfile.contributor:51 — build the crux CLI with go install github.com/hivecommons/crux/cmd/crux@$TAG (or go build github.com/hivecommons/crux/cmd/crux from the root module, which now requires it); .oss-scanner/Dockerfile:57-84 — drop ./crux/... and the five ./crux/<pkg>/... entries (the scanner can only see first-party source); src/scripts/generate-notice.sh:175 — drop ./crux/....
  • Docs: rewrite the 165 citations in 22 src/docs files to https://github.com/hivecommons/crux/blob/$TAG/<path>#L<n> and run src/scripts/check-docs-citations.py; rewrite src/docs/crux-publish.md into a short "Crux lives at hivecommons/crux; how hive bumps it" page; update AGENTS.md:10, CONTRIBUTING.md:24,64-68, src/docs/design/crux.md header; add changelog.d/changed-<n>-crux-cutover.md.
  • Expect the v5 → v6 forward-merge (v6-topup.yml) to carry the flip; if v6 has diverged in src/crux, resolve by taking v5's deletion.

Phase 4 — process after the flip

  • Branch model: crux main only, tags vX.Y.Z (semver, v0.4.x for fixes); hive stays v5 and bumps with go get github.com/hivecommons/crux@vX.Y.Z PRs (a crux-pin-bump workflow modelled on cli-pin-bump is a follow-up, not part of the flip).
  • Triage: hive agents already see crux via project.repos; after sync-guard is gone, PRs may be authored there. Carry over: emoji-prefixed titles, git commit -s (DCO), changelog.d/ fragments, Refs #n citations. Crux issues no longer need mirroring into hive; crux#114 stays the work-services tracker in crux.
  • Releases: unchanged (release.yml, goreleaser, cosign, ghcr, homebrew formula bump in hivecommons/homebrew-hive).

Phase 5 — rollback (if the flip PR cannot go green on 11-16)

  1. Do not merge the hive flip PR; gh workflow enable crux-sync.yml --repo hivecommons/hive restores publishing (nothing in hive was deleted until the flip PR merges).
  2. Re-add sync-guard.yml in crux from fe54cd5 (git checkout fe54cd5 -- .github/workflows/sync-guard.yml) and restore .hive-sync with the next sync run (workflow_dispatch).
  3. v0.4.0-rc.1/v0.4.0 remain valid tags of the frozen tree either way.
  4. If the flip merged and must be undone: git revert the flip commit on v5 (it is one commit; src/crux comes back at the frozen sha), re-pin TRUSTED_SCRIPTS_TREE, re-enable the workflow.

3. Day-by-day checklist

  • Mon 11-09 — Confirm this RFC; confirm CRUX_SYNC_TOKEN scope; open crux scaffolding PR (CI lanes, changelog.d/+guard, DCO/CONTRIBUTING).
  • Tue 11-10 — Merge crux scaffolding PR; S1 (feat/crux-caller-principal) pushed + PR in hive; S0 PR in hive.
  • Wed 11-11 — S2 (feat/crux-contained-run) PR in hive; local scratch dry run of §Phase 3 steps 1–5 against crux main via a temporary replace (not pushed); draft the citation-rewrite script and the flip PR description.
  • Thu 11-12 — S7 PR in hive; verify each S-PR's sync run went green on crux main.
  • Fri 11-13 — Freeze after the last S-PR merges (deadline 18:00 UTC); tag crux/v0.4.0-rc.1 from hive; confirm crux v0.4.0-rc.1 release built; gh workflow disable crux-sync.yml.
  • Sat/Sun — nothing (if an S-PR slipped, the freeze moves to Mon 08:00 ET and the rc is tagged then).
  • Mon 11-16 (flip) — crux: delete .hive-sync + sync-guard.yml, protect main, tag v0.4.0; hive: open the flip PR with the §Phase 3 sequence, CI/Docker/docs/guards edits, TRUSTED_SCRIPTS_TREE re-pin, changelog fragment; merge when green; watch v6-topup; bump homebrew formula; update crux#114 that development now happens in crux.
  • Tue 11-17 — follow-ups: crux-pin-bump workflow, per-agent repos: additions, delete crux/v* tags? (no — keep; they are history), close this issue.

4. Risks (top first)

  1. In-flight phase-1 PRs (S0/S1/S2/S7) vs the freeze. S1 exists only as one unpushed local commit, S2 has no commits yet, S0/S7 have no branches. Anything not merged into hive src/crux by Fri 11-13 must be re-targeted at crux with its imports rewritten (same sed, applied to the PR branch) — and reviewed again under crux's CI. Mitigation: hard deadline + the Monday-morning freeze fallback.
  2. Scale of the hive flip PR: 279 files / 422 import lines + ~10 CI/Docker/script files + 22 doc files (165 citations) + TRUSTED_SCRIPTS_TREE + release-lines.yml in a single PR that must pass changelog-fragment-guard, the citations guard, the governance guard and the full test matrix (which itself is being edited). A missed ./crux/... in any .github/scripts/*.sh makes affected-go-packages.sh fall back to "full" or fail. Mitigation: the Wed 11-11 scratch dry run and the grep-guard in step 5.
  3. Version skew during the transition: between the rc tag and the flip, crux main must not move (sync disabled, sync-guard still on), otherwise v0.4.0 ≠ the tree hive was last tested against. After the flip, hive pins a tag while crux main advances — every crux change hive needs now requires a crux release + a hive bump PR (slower than today's in-tree edit). The lanes NATS code (nats-server/v2 v2.15.2, deflaked 3× this week) is the most likely source of "fix needed in both places" churn.
  4. replace directives: none should survive the flip; a lingering replace github.com/hivecommons/crux => ./crux would silently build against a deleted directory in Docker (GOWORK=off). Guard: grep -c '^replace' go.mod = 0 in the flip PR.
  5. Docker/image build: src/Dockerfile:86 builds hive's host ./cmd/crux (stays); Dockerfile.contributor:51 builds the module binary — switching it to the dependency changes the binary shipped at /usr/local/bin/crux in the contributor image to exactly v0.4.0. Justfile cline-turn callers are unaffected.
  6. v6 forward-merge: the flip lands on v6 via v6-topup.yml; a concurrent src/crux change on v6 would conflict with the deletion.
  7. Crux CI covers less than hive's matrix in one respect: hive slices crux/agent N-ways and runs the dedicated lanes/api/serve race lane; crux runs ./agent/... in one ubuntu-24.04 job. Port the lane in Phase 0; accept a longer single agent job or slice it later.
  8. Sync-guard removal timing: deleting it before the rc tag lets a stray PR change the tree under the tag; deleting it after the flip blocks developers. Order in Phase 2 is deliberate.

Activity

  1. added
    kind/designCreated by Hive for agent-filed issue provenance
    proposalRFC / design proposal for discussion
    on Nov 7, 2026
  2. added
    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.
    on Nov 7, 2026
  3. hivecommons-hive commented on Nov 7, 2026

    @hivecommons-hive
    Contributor

    🔓 Claim by @Danathar released (lease revoked).

    Claim history
    • 2026-11-07 18:42 UTC — claimed by Karibhou (contributor on hive hosted-available-oke-11-placeholder-r05x)
    • 2026-11-07 18:48 UTC — released by Karibhou (contributor; lease revoked)
    • 2026-11-08 09:04 UTC — claimed by scanner (agent on hive hosted-available-oke-11-placeholder-r05x)
    • 2026-11-14 18:53 UTC — claimed by Danathar (contributor on hive hosted-available-oke-11-placeholder-r05x)
    • 2026-11-14 18:56 UTC — released by Danathar (contributor; lease revoked)
  4. added
    stage/020-claimedClaimed by the scanner or a relay contributor
    and removed
    stage/010-actionableTriaged; eligible for the hive to pick up
    on Nov 7, 2026
  5. Karibhou commented on Nov 7, 2026

    @Karibhou
    Contributor

    Checked on 2026-11-07. There is nothing in hivecommons/hive that can ship yet for this RFC.

    • What's needed first: The hive flip PR (§Phase 3) runs go get github.com/hivecommons/crux@v0.4.0. hivecommons/crux has no v0.4.0 or v0.4.0-rc.1 tag yet; its only tags are v0.3.0, v0.2.0 and v0.1.0. That tag only exists after the Phase 1 freeze and rc tag (11-13) and the Phase 2 crux flip (11-16). Until then the import rewrite can't build without a replace to ./crux, and the RFC says that replace must not survive the flip.
    • Date gate: The body says that, per the maintainer, nothing is ported until 2026-11-16.
    • The remaining Phase 0 items aren't hive PRs. The CI scaffolding PR goes to hivecommons/crux, the dry run is a scratch branch that is never pushed, the citation-rewrite script is part of the flip PR itself, and the token-scope check and freeze can only be done by a maintainer.
    • upstream/v5 @ 7a9293564 still has src/crux/go.mod and the two-module src/go.work, so the inventory in the RFC still applies.

    I'm marking this blocked until crux v0.4.0 is tagged and the 11-16 window opens. After that, the §Phase 3 sequence can be run as one PR against v5.

    — hive: backend=omp model=anthropic/claude-opus-5-5


    🐝 Hive Agent: contributor | SHA: unknown

  6. added
    blockedWaiting on something outside this repository; not contributor work until a human clears the label
    and removed
    blockedWaiting on something outside this repository; not contributor work until a human clears the label
    stage/020-claimedClaimed by the scanner or a relay contributor
    on Nov 7, 2026
  7. hivecommons-hive commented on Nov 7, 2026

    @hivecommons-hive
    Contributor

    Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

    Unblocked: the blocked label was applied by the hive without a blocked-on marker, so nothing could lift it. This issue is actionable again.

    • scanner (2026-11-11 00:41 UTC): ## Wed 11-11 prep (hive): dry-run counts, citation-rewrite script draft, flip PR description draft

      This covers the part of the Wed 11-11 checklist item that the hive can do. Nothing was pushed. No branch, PR, tag or workflow change was made. All work happened in a throwaway local clone of v5 @ 978540d39, which was reset with git checkout -- . and then deleted.

      I did not run a build, vet, test, tidy or lint. The dry run used only sed and grep. As the RFC requires, build re-verification is deferred to flip day (§Phase 3 steps 4–5 against the real v0.4.0 tag). That is also why steps 1, 2 and 4 (go.work/go.mod edits, git rm crux, go get) were not exercised here.

      1. Dry-run counts (§flip step 3 import sed, root module = src/ minus src/crux)

      11-07 (RFC) 11-11 (978540d39)
      Go files importing "github.com/hivecommons/hive/crux… 279 289
      Import lines 422 439 (+1 string constant, see below)
      Quoted old-path references left after the sed 0 0 ✅
      Go files still containing the old path text — 1 (src/internal/testutil/dashboard_import_ratchet_test.go:18-19, a comment only, stale wording to fix in the flip PR)
      • The sed also rewrites the string constant dashboardCruxImportPrefix in dashboard_import_ratchet_test.go:21 to "github.com/hivecommons/crux". That change is intended because it has to match the rewritten dashboard_import_allowlist.txt (11 lines). Calling it out because reviewers will see a non-import line in the diff.
      • In total the sed changed 290 files and 451 lines: 440 lines in 289 .go files and 11 lines in the allowlist.

      Non-Go files outside src/crux that still name github.com/hivecommons/hive/crux after the sed. The flip PR must edit or delete each one:
      src/go.mod (100, 102) · src/go.work (comment line 6) · src/scripts/crux-publish.sh · src/scripts/test-crux-publish-keep.sh · .github/scripts/crux-scope.sh · .github/workflows/crux-sync.yml · .github/workflows/v2-tests.yml · .github/workflows/integration-candidate.yml · .github/workflows/integration-technical-v2-tests.yml · src/docs/crux-cli.md · src/docs/crux-publish.md · src/docs/crux-serve.md · src/docs/design/crux.md · src/docs/knowledge/go-workspace-two-modules.md · CONTRIBUTING.md · docs/development.md · CHANGELOG.md (history, leave as-is).

      Surfaces added since the 11-07 inventory that address ./crux, src/crux or crux/go.sum:

      • .github/workflows/integration-candidate.yml (working-directory: src/crux, go vet ./... ./crux/..., TEST_PACKAGE=…/crux/agent)
      • integration-technical-v2-ci.yml
      • integration-technical-v2-tests.yml
      • integration-technical-go-security-analysis.yml
      • price-table-refresh.yml:71 (src/crux/go.sum)
      • .github/CODEOWNERS:24 (src/crux/proxy/**)

      Also, .github/release-lines.yml:164 is now crux-sync.yml: [-v4, -v6].

      Docs citations into src/crux/. I used check-docs-citations.py's own CITATION_RE and path resolver (imported only; I did not run the checker). There are 142 citations in 10 files today, down from the RFC's 165 in 22:

      • 141 are src/crux/… and 1 is the src-relative crux/logscrub/redaction.go:55 in security.md.
      • By shape: 100 single lines, 39 ranges and 2 comma lists. None are inside fenced blocks.
      • By file: design/agent-turn-model.md 99, design/agent-host-confinement.md 15, design/copilot-cost-capture.md 11, design/cli-memory-drain.md 6, design/github-mention-triggers.md 5, design/agent-turn-handoff.md 2, and 1 each in design/README.md, scale-envelope.md, security.md, skills.md.

      There are also 241 path-only src/crux/… mentions with no line number. The citations guard does not check these, but they become dead paths after the deletion. They are mostly in design/crux.md, crux-cli.md and crux-serve.md, which the flip PR rewrites anyway.

      2. Citation-rewrite script draft

      I ran the draft below on the scratch clone; it only edits text. Result: 142 citations rewritten in the 10 files (136 lines). A second run rewrote 0 citations and exited 0, so it is idempotent. Nothing that the guard's regex would match was left behind.

      The new link text, crux/PATH#LN, has no :LINE, so check-docs-citations.py ignores it the same way it ignores URLs. Example: src/crux/agent/manager_tmux.go:178-186 becomes [crux/agent/manager_tmux.go#L178-L186](https://github.com/hivecommons/crux/blob/v0.4.0/agent/manager_tmux.go#L178-L186).

      src/scripts/crux-citation-rewrite.sh (draft, 51 lines)
      #!/usr/bin/env bash
      # crux-citation-rewrite.sh — rewrite src/docs citations into the retired
      # src/crux tree to pinned hivecommons/crux blob URLs (#17004 §Phase 3).
      #
      # Usage: src/scripts/crux-citation-rewrite.sh [tag] [docs-dir]
      #        (defaults: v0.4.0, src/docs; run from the repository root)
      #
      # `src/crux/P:SPEC` and src-relative `crux/P:SPEC` (optionally backticked)
      # become `[crux/P#LN](https://github.com/hivecommons/crux/blob/TAG/P#LN)`.
      # SPEC is the check-docs-citations.py grammar: N, N-M, N–M, or a comma list.
      # The link text carries no `:LINE`, so the citations guard (which ignores
      # URLs) no longer treats it as a repo-local path. Fenced blocks are skipped.
      # Idempotent; exits non-zero if any src/crux citation survives.
      set -euo pipefail
      
      TAG=${1:-v0.4.0}
      DOCS=${2:-src/docs}
      BASE="https://github.com/hivecommons/crux/blob/${TAG}"
      [ -d "$DOCS" ] || { echo "crux-citation-rewrite: no docs dir $DOCS" >&2; exit 2; }
      
      CITE='(?<![\w./@:-])`?(?:src/)?crux/([A-Za-z0-9_./-]+\.[A-Za-z0-9]+):(\d+(?:(?:-|–)\d+)?(?:,\d+(?:(?:-|–)\d+)?)*)`?'
      total=0
      while IFS= read -r -d '' f; do
        n=$(BASE="$BASE" CITE="$CITE" perl -i -ne '
          BEGIN { $n = 0; $fence = 0; $re = qr/$ENV{CITE}/; }
          if (/^\s*(```|~~~)/) { $fence = !$fence; print; next; }
          unless ($fence) {
            s{$re}{
              my ($p, specs) = ($1, split /,/, $2);
              $n++;
              join ", ", map {
                my ($s, $e) = split /-|–/, $_;
                my $anchor = defined $e ? "L$s-L$e" : "L$s";
                "[crux/$p#$anchor]($ENV{BASE}/$p#$anchor)";
              } specs;
            }ge;
          }
          print;
          END { print STDERR "$n\n"; }
        ' "$f" 2>&1 >/dev/null)
        if [ "$n" -gt 0 ]; then
          echo "  $n  $f"
          total=$((total + n))
        fi
      done < <(find "$DOCS" -name '*.md' -print0 | sort -z)
      echo "crux-citation-rewrite: rewrote $total citation(s) to $BASE"
      
      if left=$(grep -rnP --include='*.md' "$CITE" "$DOCS"); then
        echo "::error::src/crux citations remain (fenced or unparsed):" >&2
        echo "$left" >&2
        exit 1
      fi

      Two things to note if this script is added under src/scripts/:

      • It is part of the TRUSTED_SCRIPTS_TREE re-pin.
      • It only needs to run once, on flip day. Either commit it and delete it in the same PR, or run it and keep only its output.

      3. Flip PR description draft

      Title: ⚠️ crux: consume github.com/hivecommons/crux v0.4.0 as a dependency; retire src/crux and the publish pipeline
      ## Why
      
      Crux development moves to hivecommons/crux (RFC #17004). Hive stops vendoring the runtime as the nested
      module `src/crux` and consumes `github.com/hivecommons/crux@v0.4.0` as an ordinary Go dependency.
      The publish pipeline (`crux-publish.sh` + `crux-sync.yml`) is retired. ⚠️ because this deletes `src/crux`
      (49 packages / ~790 files) and rewrites every crux import in the root module. Crux `v0.4.0` was tagged
      from the frozen tree (`v0.4.0-rc.1` = the frozen hive `v5` commit), so behaviour is unchanged.
      
      ## Changes (§Phase 3, in order, run from `src/`)
      
      - [ ] 1. `go.work` → `use .` only; drop `require`/`replace github.com/hivecommons/hive/crux` from `go.mod`
      - [ ] 2. `git rm -r crux`
      - [ ] 3. Import rewrite `github.com/hivecommons/hive/crux` → `github.com/hivecommons/crux` (289 files / 439 import lines as of 11-11)
            + `internal/testutil/dashboard_import_allowlist.txt` + ratchet-test prefix/comment
      - [ ] 4. `go get github.com/hivecommons/crux@v0.4.0 && go mod tidy`; `gofmt -l .` empty
      - [ ] 5. `go build ./... && go vet ./... && go test -short ./pkg/dashboard/... ./cmd/crux/...`
      - [ ] CI: `v2-ci.yml`, `v2-tests.yml`, `coverage-hourly.yml`, `go-security-analysis.yml`, `integration-candidate.yml`,
            `integration-technical-{v2-ci,v2-tests,go-security-analysis}.yml`, `price-table-refresh.yml` (`src/crux/go.sum`):
            drop `./crux/...`, `working-directory: src/crux`, the `crux/agent` slices and the lanes/api/serve lane;
            delete `crux-file-size-ratchet.yml` and `.github/scripts/crux-scope.sh` (+ callers);
            drop `./crux/...` and `crux/go.mod|go.sum` from `.github/scripts/affected-go-packages.sh`;
            remove `crux-sync.yml` from `.github/release-lines.yml`; drop `src/crux/proxy/**` from `.github/CODEOWNERS`
      - [ ] Workflows/scripts: `git rm .github/workflows/crux-sync.yml src/scripts/crux-publish.sh src/scripts/test-crux-publish-keep.sh`
      - [ ] Docker: `src/Dockerfile` / `src/Dockerfile.contributor` drop `COPY src/crux/go.mod src/crux/go.sum ./crux/`;
            contributor image builds `github.com/hivecommons/crux/cmd/crux` from the module graph;
            `.oss-scanner/Dockerfile` and `src/scripts/generate-notice.sh` drop `./crux/...`
      - [ ] Docs: `src/scripts/crux-citation-rewrite.sh v0.4.0` (142 citations / 10 files → crux blob URLs);
            rewrite `src/docs/crux-publish.md` as "how hive bumps crux"; update `design/crux.md`, `crux-cli.md`,
            `crux-serve.md`, `knowledge/go-workspace-two-modules.md`, `AGENTS.md`, `CONTRIBUTING.md`, `docs/development.md`
      
      ## Guards (all must hold in this PR)
      
      - `grep -c '^replace' src/go.mod` → `0`
      - `grep -rn '"github.com/hivecommons/hive/crux' src --include='*.go'` → no output
      - `src/scripts/check-docs-citations.py` clean; `crux-citation-rewrite.sh` exits 0 (no `src/crux` citation left)
      - `.github/scripts/affected-go-packages.sh` on this diff resolves without `./crux/...` and does not fall back to "full" on a dangling path
      - `grep -rnE 'src/crux|\./crux/' .github src/Dockerfile* .oss-scanner src/scripts` → no output
      
      ## Governance
      
      - `src/scripts/` changes (two deletions + the rewrite script): re-pin `TRUSTED_SCRIPTS_TREE` in
        `.github/scripts/integration-governance.cjs:12` to `git rev-parse HEAD:src/scripts` of the final tree (maintainer).
      - Changelog: `changelog.d/changed-17004-crux-cutover.md`.
      - Lands on `v5`; reaches `v6` via `v6-topup.yml` (take v5's deletion on any `src/crux` conflict).
      - Rollback: `git revert` this single commit, re-pin `TRUSTED_SCRIPTS_TREE`, `gh workflow enable crux-sync.yml`.
      
      Refs #17004

      Still maintainer-only before 11-16: freeze, crux/v0.4.0-rc.1 tag, gh workflow disable crux-sync.yml, sync-guard removal and v0.4.0 tag in crux, and the TRUSTED_SCRIPTS_TREE re-pin. This issue stays open; per the checklist it closes on 11-17.

      — hive: agent=scanner

  8. 6 remaining items

  9. hivecommons-hive commented on Nov 8, 2026

    @hivecommons-hive
    Contributor

    Phase 0 status (2026-11-08): the crux-side CI port is done — hivecommons/crux#127 merged, adding the lanes/api/serve -race lane mirroring v2-ci.yml and a DCO check. changelog.d/ + fragment guard and CONTRIBUTING are deliberately left for the flip PR because those paths are sync-owned (outside crux-publish.sh's KEEP list) and would be wiped by the next sync.

    Everything else in Phase 0–3 is either maintainer-only (RFC confirmation, CRUX_SYNC_TOKEN scope, freeze, rc tag, workflow disable, branch protection) or gated to 2026-11-16 per the body, so no hive PR is opened for this issue before then. The S-series work-services PRs land in hive src/crux independently (S3 is #17234).


    🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

    — hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88

  10. added
    stage/018-open-for-discussionOpen for discussion: proposal / design issue with no live claim; claimable, no agent work queued
    and removed
    stage/010-actionableTriaged; eligible for the hive to pick up
    on Nov 8, 2026
  11. hivecommons-hive commented on Nov 12, 2026

    @hivecommons-hive
    Contributor

    Thu 11-12 checklist (hive-side verification only; no branch, PR, tag or workflow change made):

    • crux-sync runs green: the last 10 crux-sync.yml runs on v5 (latest hive@efb2a0bab, 07:03 UTC today) all concluded success; crux main HEAD is e28a1e892 = 🌱 sync: hive@efb2a0bab5b6, interleaved with the hand-maintained scaffolding commit 48f9cefcf (crux#149, base-image digest pins).
    • crux main CI green: all 14 check-runs on HEAD pass, including the ported lanes/api/serve integration (-race) lane from crux#127, coverage floors, file-size ratchet, gosec/govulncheck, goreleaser snapshot and both crux serve smokes.
    • S-series: S3 (✨ crux: human gate service (S3) #17234) merged 11-08 and its sync is in crux main. No S0/S1/S2/S7 PR references this issue yet (timeline cross-refs checked); those are maintainer-owned per the body (S1 is a local unpushed commit), so the 11-13 18:00 UTC freeze deadline is the only hive-visible gate. Nothing for the hive to open before 11-16.

    🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: cf67d1ee6

    — hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88

  12. hivecommons-hive commented on Nov 14, 2026

    @hivecommons-hive
    Contributor

    @Danathar you now hold this issue (contributor on hive hosted-available-oke-11-placeholder-r05x); the claim ledger comment above tracks it. Reply /unclaim to release.

  13. added
    stage/020-claimedClaimed by the scanner or a relay contributor
    and removed
    stage/018-open-for-discussionOpen for discussion: proposal / design issue with no live claim; claimable, no agent work queued
    on Nov 14, 2026
  14. Danathar commented on Nov 14, 2026

    @Danathar
    Contributor

    Checked on Sat 2026-11-14 at 19:00 UTC. The §Phase 3 flip PR can't be opened yet: the Phase 1 freeze and tag haven't happened, and the existing v0.4.0 tag doesn't match v5.

    What a maintainer needs to decide or do before the flip PR (all maintainer-only per the RFC's Owners section):

    1. Freeze src/crux on v5.
    2. Cut a new tag from the frozen sha (for example crux/v0.4.1-rc.1 → v0.4.1, or v0.5.0). Re-using v0.4.0 isn't possible: it already exists at an older tree.
    3. Disable crux-sync.yml.
    4. Run Phase 2 in crux: remove sync-guard.yml and .hive-sync, then tag the release.

    After that, the Phase 3 sequence plus the 11-11 prep (citation-rewrite script, PR description draft) can be run as one PR against v5, with TAG set to whichever tag was chosen.

    — hive: backend=claude model=claude-opus-5-5


    🐝 Hive Agent: contributor | SHA: c98a5bb80

  15. added
    stage/045-needs-decisionIssue parked on a person: needs-human or a maintainer decision is owed before the hive picks it up
    and removed on Nov 14, 2026
  16. hivecommons-hive commented on Nov 14, 2026

    @hivecommons-hive
    Contributor

    What to reply

    • /hive approve: go with the recommendation
    • /hive decision <your instructions>: go ahead, following your instructions
    • /hive help: show these again

    If what this issue waited on has been done (a merged fix, or an action taken outside this repository), a maintainer can reply /fixed to close it as completed; Hive clears its park labels.

    Only a maintainer with write access can un-park; everything else is ignored. Full command reference: https://github.com/hivecommons/hive/blob/v5/src/docs/maintainer-commands.md.

  17. clubanderson commented on Nov 17, 2026

    @clubanderson
    MemberAuthor

    Status on 2026-11-17: the cut-over did not happen on 2026-11-16, and this is waiting on the owner, not on the hive.

    What the repositories show today

    • v5 still has src/crux, the two-module src/go.work and the replace to ./crux.
    • crux-sync.yml is still publishing: hivecommons/crux main received six sync commits today, the last at 15:52 UTC.
    • hivecommons/crux still has sync-guard.yml and .hive-sync, so nobody can develop there yet.
    • There is no freeze and no release candidate tag. The only v0.4.0 tag is from 2026-11-08 and is far behind v5; using it for the flip would silently revert the work merged since.
    • src/crux is busy: three pull requests touching it merged to v5 today.

    What is decided here: the 2026-11-16 date is void, and the plan itself is unchanged. Nothing was ported, so nothing needs undoing. The hive does not open the flip pull request until the freeze and a fresh tag exist; that order is what protects the merged work.

    What still needs the owner. The flip starts with four maintainer-only steps that cannot be taken back quietly: freeze src/crux on v5, cut a new tag from the frozen commit (v0.4.1 or v0.5.0, since v0.4.0 is taken), disable crux-sync.yml, and remove sync-guard.yml and .hive-sync in hivecommons/crux. The choice is when:

    • Option 1: flip on Monday 2026-11-23. Freeze src/crux by Friday 2026-11-20 18:00 UTC, tag from the frozen commit, and the hive opens the flip pull request against v5 on Monday using the prepared rewrite script and description. Consequence: Sessions and Betty changes that touch src/crux must land before Friday or wait and be opened in hivecommons/crux after the flip.
    • Option 2: defer until the Sessions and Betty work settles, and set the date then. Consequence: no freeze pressure on work in flight, but the two-repository sync, the stale v0.4.0 tag and the growing import count (279 files on 11-07, 289 on 11-11) carry on, and the flip gets a little larger each week.

    Recommendation: option 1. The preparation is done and current, crux CI already mirrors the hive's, and one week is enough to land what is in flight.

    To answer: reply /hive decision flip on 2026-11-23 (or another date), or /hive decision defer. Until then this stays parked and the hive opens nothing for it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.kind/designCreated by Hive for agent-filed issue provenanceproposalRFC / design proposal for discussionstage/045-needs-decisionIssue parked on a person: needs-human or a maintainer decision is owed before the hive picks it up

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions