GloriousFlywheel Contract Remediation Packages 2026-04-17

GloriousFlywheel Contract Remediation Packages 2026-04-17

Snapshot date: 2026-04-17

Purpose

Turn the tier scorecard into a small number of real implementation packages.

This note is intentionally narrow:

  • what exact files or workflow surfaces matter most
  • what those surfaces currently do wrong
  • what the first remediation packages should contain
  • which repos should pilot each package

Companion notes:

Narrowed Surface Map

Live inspection now shows the contract surface is smaller than it first looked.

Source Repo Surfaces That Matter

  • .github/workflows/validate.yml
  • .github/workflows/test-arc-runners.yml
  • .github/workflows/reusable-nix-check.yml
  • .github/actions/setup-flywheel/action.yml

Shared Reusable Workflow Surfaces That Matter

  • tinyland-inc/ci-templates/.github/workflows/js-bazel-package.yml
  • tinyland-inc/ci-templates/.github/workflows/npm-publish.yml

Important Narrowing Facts

  • js-bazel-package.yml is currently imported by exactly these downstream repos:
    • tinyvectors
    • scheduling-kit
    • acuity-middleware
  • no downstream repo currently imports npm-publish.yml
  • no downstream repo currently imports tinyland-inc/GloriousFlywheel/.github/workflows/reusable-nix-check.yml

Implication:

  • the real downstream contract debt is concentrated in one shared template
  • the Nix reusable workflow is not yet an adoption lever
  • npm-publish.yml is not currently the surface determining repo homogeneity

Package 1: Source Repo Default-Branch Proof Path

Owner Surfaces

  • #210
  • #214

Problem

GloriousFlywheel currently proves the platform in three disconnected ways:

  • hosted validation on main
  • partial shared-runner app checks on main
  • branch-gated ARC runner proof in test-arc-runners.yml

That means the source repo cannot make one coherent sentence true:

“Our normal default-branch CI proves our normal self-hosted contract.”

Desired Outcome

One ordinary default-branch workflow visibly proves:

  • shared Docker lane
  • shared Nix lane
  • heavy Nix lane
  • setup-flywheel cache injection
  • explicit Nix bootstrap truth

Minimal Patch Shape

  1. lift the useful assertions from test-arc-runners.yml into a default-branch workflow:
    • verify runner environment
    • verify Nix bootstrap
    • verify cache variables are injected
    • run one basic heavy-lane build
  2. keep hosted utility work visibly separate:
    • external links
    • docs deploy
    • release and image publication
  3. either:
    • remove the branch gate from test-arc-runners.yml
    • or replace it with a new default-branch proof workflow and leave the old file as a bench or soak lane

Acceptance Criteria

  • default-branch CI includes one shared-runner proof on:
    • tinyland-docker
    • tinyland-nix
    • tinyland-nix-heavy
  • no one has to cite a feature branch to explain self-dogfood
  • hosted jobs are classified as hosted exceptions, not silent drift

Package 2: js-bazel-package V2

Owner Surfaces

  • #210
  • #213

Problem

The current shared template still spreads three kinds of debt:

  • hosted fallback by default
  • persistent workspace hygiene
  • implicit rather than explicit platform contract

Desired Outcome

The template should make runner intent explicit and make self-hosted behavior look different from hosted behavior by design, not by accident.

Minimal Patch Shape

  1. add explicit runner intent
    • runner_mode: hosted | shared | repo_owned
    • keep runner_labels_json as a low-level override
  2. add explicit workspace intent
    • workspace_mode: isolated | persistent_compat
    • default new consumers to isolated
  3. integrate setup-flywheel on self-hosted modes
  4. define an isolated working directory under $RUNNER_TEMP or equivalent
  5. separate build validation from publish authority
    • self-hosted build and package validation
    • hosted publish only when provenance or platform limits require it

Acceptance Criteria

  • no default self-hosted path depends on clean: false
  • no repo is silently self-hosted or silently hosted
  • the workflow itself makes self-hosted cache behavior visible
  • hosted fallback becomes an explicit migration choice, not the default

Package 3: Template Pilot Wave

Owner Surface

  • #210

Pilot Repos

  • Jesssullivan/scheduling-kit
  • Jesssullivan/acuity-middleware
  • tinyland-inc/tinyvectors

Why These Three

  • all three are already on the same shared workflow family
  • scheduling-kit has verified repo-specific runner labels and no current hosted authority in inspected CI and publish paths
  • acuity-middleware has verified repo-specific runner labels and an explicit hosted deploy exception
  • tinyvectors is the clean control case because it imports the template but does not show repo-level runner labels today

Pilot Goals

  • scheduling-kit
    • prove the clean repo-owned lane path
  • acuity-middleware
    • prove the same path while preserving one explicit hosted deploy exception
  • tinyvectors
    • prove whether the template can promote a hosted template consumer into a verified self-hosted repo-owned consumer

Acceptance Criteria

  • at least one clean dedicated-lane pilot is documented and stable
  • at least one hybrid pilot keeps its hosted exception explicit and narrow
  • the remaining hosted template consumer either promotes cleanly or is left intentionally hosted with no ambiguity

Package 4: Reporting Model Repair

Owner Surfaces

  • #210
  • #212

Problem

Current planning language still too easily collapses:

  • runner adoption
  • cache adoption
  • template readiness
  • hybrid exceptions

into one misleading sentence.

Minimal Patch Shape

Every PM and status surface should report four numbers:

  1. real self-hosted runner dogfood
  2. hosted cache consumers
  3. hosted template consumers
  4. hybrid exception repos

Acceptance Criteria

  • no PM update uses one raw “adoption” number
  • the same repo cannot be double-counted as both hosted cache and runner dogfood in the same report

Packages We Should Not Lead With

npm-publish.yml

This is not currently a real downstream leverage surface because live search shows no downstream consumers.

It should be fixed only after the real shared template is fixed.

reusable-nix-check.yml

This is not currently a downstream leverage surface because live search shows no downstream consumers.

It should be treated as a future Nix-contract accelerant, not as the first adoption lever.

  1. source repo default-branch proof path
  2. js-bazel-package V2
  3. pilot in scheduling-kit and acuity-middleware
  4. decide whether tinyvectors promotes or stays explicitly hosted
  5. repair reporting to use the new tier model

Recommendation

If we stay disciplined, the program should behave like this:

  • use the source repo to prove the platform
  • use one shared template to spread the platform
  • use scheduling-kit and acuity-middleware to harden the template
  • use tinyvectors to test whether template consumers can be promoted cleanly
  • leave unused reusable surfaces out of the critical path

That is the shortest credible route from mixed adoption to homogeneous dogfooding.

GloriousFlywheel