GloriousFlywheel Cleanup Structure 2026-04-17

GloriousFlywheel Cleanup Structure 2026-04-17

Snapshot date: 2026-04-17

Purpose

Turn the post-reconciliation cleanup work into one explicit execution structure.

This note is the deeper internal companion to ../cleanup-program.md.

Use it for:

  • workstream boundaries
  • issue-to-deliverable mapping
  • merge order and proof expectations
  • deciding what belongs in the current cleanup cycle versus later product work

Current Baseline

Repo state after the slice PR wave:

  • docs/status/Bazel-identity cleanup is merged
  • backend and operator-path convergence is merged
  • dashboard auth/control/audit hardening is merged
  • dogfood/shared-runner contract cleanup is merged
  • no open PRs remain in the main repo

Live open issue set:

  • #213 runner workspace hygiene
  • #215 FlakeHub publication RFC boundary
  • #210 downstream adoption and migration kit
  • #211 GitHub-first forge boundary
  • #212 benchmark methodology
  • #66 pulp/package-management RFC
  • #44 GPU runner docs

This means the cleanup program is no longer “slice the worktree.” It is “execute the remaining issue lanes without blurring boundaries.”

Workstream Map

Workstream A: Runtime Integrity

Primary owner issues:

  • #213

Scope:

  • host-side workspace hygiene on honey
  • repo-owned ARC lane runtime truth
  • preserve the heavy-Nix proof on sting
  • separation of repo-owned versus personal lanes

Expected deliverables:

  • one runner-hygiene fix or operational runbook update
  • one heavy-lane validation proof point
  • one runtime contract update if live evidence changes the public story

Proof expectations:

  • live runtime audit evidence
  • successful downstream heavy-lane canary evidence
  • no reliance on theory alone for runner-envelope claims

Out of scope:

  • broad control-plane redesign
  • backend-family redesign
  • reopening honey versus cloud target debates

Workstream B: Downstream Contract And Product Boundary

Primary owner issues:

  • #210
  • #211

Scope:

  • downstream migration kit
  • canary expansion beyond the first tranche
  • GitHub-first docs and positioning cleanup
  • GitLab and Codeberg compatibility framing

Expected deliverables:

  • updated canary inventory and tranche state
  • tightened downstream examples and docs
  • clearly bounded compatibility guidance

Proof expectations:

  • downstream repo evidence, not only repo-local docs
  • docs and issue surfaces aligned with what the canaries actually show

Out of scope:

  • turning every downstream repo into the same workflow shape at once
  • treating compatibility forges as equal-maturity product surfaces

Workstream C: Builder And Publication Boundary

Primary owner issue:

  • #215

Scope:

  • narrow FlakeHub RFC
  • builder/publication wording cleanup
  • Bazel identity follow-through where needed

Expected deliverables:

  • one small RFC-style decision summary
  • one clean public explanation of acceleration versus publication
  • supporting doc cleanup where FlakeHub wording still leaks into runtime

Proof expectations:

  • every FlakeHub-facing statement stays consistent with:
    • workflow-owned Nix bootstrap
    • ARC horizontal scaling
    • Attic/Bazel as acceleration

Out of scope:

  • making FlakeHub part of the live runtime contract
  • using FlakeHub as the fix for runner sizing or bootstrap

Workstream D: Metrics And Long-Tail Platform Lanes

Primary owner issues:

  • #212
  • #66
  • #44

Scope:

  • benchmark methodology
  • package-management RFC work
  • GPU runner docs and later runner classes

Expected deliverables:

  • benchmark scorecard and method
  • scoped RFC outputs for the non-runner lanes

Proof expectations:

  • concrete methodology and comparison axes
  • no vague “competitiveness” notes without measurement structure

Out of scope:

  • distracting from the active runtime and adoption cleanup lanes

Merge And Review Order

Preferred execution order for new cleanup work:

  1. runtime integrity slices that unblock or validate honey
  2. downstream-contract slices that use live canary evidence
  3. publication-boundary slices that summarize and narrow, not expand
  4. benchmarking and longer-tail slices

If a change touches multiple workstreams, it should usually be split unless the shared code or docs are inseparable.

Canonical Outputs Per Workstream

These are the surfaces that should stay authoritative during cleanup:

  • Workstream A: current-state.md, roadmap.md, gloriousflywheel-builder-runtime-sprint-priorities-2026-04-16.md
  • Workstream B: cleanup-program.md, gloriousflywheel-downstream-adoption-and-migration-kit-2026-04-16.md
  • Workstream C: rfcs.md, architecture/bzlmod-topology.md
  • Workstream D: gloriousflywheel-runner-benchmark-methodology-2026-04-16.md

Other notes may support these, but should not quietly replace them.

Explicit Non-Goals For This Cleanup Cycle

Do not let this cleanup program drift into:

  • a fresh milestone taxonomy exercise
  • a new all-at-once runtime refactor
  • a public promise that GitLab, Codeberg, and GitHub are equally mature
  • FlakeHub-as-runtime or FlakeHub-as-bootstrap language
  • speculative storage or MinIO work without a separately scoped lane

Remaining Local-Only Paths

The repo still has intentionally local or not-yet-scoped paths outside this cleanup structure:

  • config/backends/
  • tofu/modules/minio-operator/
  • tofu/modules/minio-tenant/

Those should not be silently folded into unrelated cleanup PRs.

When reassessing cleanup progress, ask:

  1. which workstream moved
  2. what live proof changed
  3. which canonical surface was updated
  4. whether the change reduced ambiguity or only moved text around

GloriousFlywheel