GloriousFlywheel Source Default-Branch Proof Package 2026-04-17

Snapshot date: 2026-04-17

Purpose

Define the smallest credible package that makes GloriousFlywheel prove its own normal self-hosted contract on a normal default-branch path.

Companion notes:

• gloriousflywheel-contract-remediation-packages-2026-04-17.md
• gloriousflywheel-tier-scorecard-and-template-remediation-2026-04-17.md
• gloriousflywheel-exception-register-and-promotion-rules-2026-04-17.md

Owner surfaces:

• #210
• #214

Current State

The source repo currently spreads proof across these surfaces:

• .github/workflows/validate.yml
  • hosted config, OpenTofu, markdown, and link validation
  • shared self-hosted app and MCP checks on tinyland-docker
• .github/workflows/test-arc-runners.yml
  • strongest self-hosted proof
  • verifies tinyland-nix, tinyland-nix-heavy, and tinyland-docker
  • uses ./.github/actions/setup-flywheel
  • currently gated to feat/arc-runners plus workflow_dispatch
• .github/actions/nix-job/action.yml
  • already bootstraps Nix explicitly
  • already calls ./.github/actions/setup-flywheel
  • already wires Attic configuration
• .github/actions/docker-job/action.yml
  • already calls ./.github/actions/setup-flywheel

Hosted-first surfaces that should remain visibly out of scope for this package:

• .github/workflows/build-image.yml
• .github/workflows/release.yml
• .github/workflows/pages.yml
• .github/workflows/flakehub-publish.yml

Problem

The source repo cannot currently make this sentence true:

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

Today that proof still depends on:

• branch-gated runner validation
• hosted default-branch authority for many visible checks
• split proof across validation and soak-style workflows

Recommendation

Do not fold everything into validate.yml.

Create one new default-branch workflow whose purpose is explicitly:

• platform proof
• not docs
• not release
• not image publication
• not general hosted utility work

Recommended file:

• .github/workflows/platform-proof.yml

Reason:

• validate.yml should keep representing broad repository validation
• a dedicated proof workflow makes exceptions easier to name and defend
• the platform claim becomes explicit instead of buried inside mixed jobs

Proposed Workflow Shape

Trigger

• push on main
• pull_request
• optional workflow_dispatch

Jobs

proof-docker

Runs on:

• tinyland-docker

Uses:

• ./.github/actions/docker-job

Purpose:

• prove shared Docker runner availability
• prove Bazel cache injection is visible
• run one representative lightweight app or MCP command

Suggested command shape:

• app install plus typecheck or test
• or a smaller repository-level smoke command that still touches the platform

proof-nix

Runs on:

• tinyland-nix

Uses:

• ./.github/actions/nix-job

Purpose:

• prove explicit Nix bootstrap
• prove setup-flywheel cache hints
• prove Attic and Bazel-related environment survives into a real job

Suggested command shape:

• nix flake check --print-build-logs

proof-nix-heavy

Runs on:

• tinyland-nix-heavy

Uses:

• ./.github/actions/nix-job

Purpose:

• prove the heavy lane is routable on the default branch
• prove one heavy-ish build path
• keep #214 grounded in the same default-branch proof surface

Suggested command shape:

• nix build .#runner-dashboard --print-build-logs
• plus one short environment probe for CPU and memory

Optional proof-summary

Runs on:

• ubuntu-latest

Purpose:

• only summarize results
• do not use this as an authority job

Exact File Changes

New File

• .github/workflows/platform-proof.yml

Existing Files To Adjust

• .github/workflows/test-arc-runners.yml
  • either reduce to manual soak lane
  • or remove branch-only authority once platform-proof.yml exists
• .github/workflows/validate.yml
  • keep broad validation
  • optionally add a note in comments or docs that platform proof moved to the new workflow

Existing Local Actions To Reuse

• .github/actions/nix-job/action.yml
• .github/actions/docker-job/action.yml
• .github/actions/setup-flywheel/action.yml

What This Package Should Not Try To Solve

Do not widen this package into publication or docs policy.

Keep these as named hosted exceptions for now:

• GitHub Pages deploy
• FlakeHub publish
• image build and cosign publish
• release tagging and GitHub Release creation
• external link checking if hosted networking remains the better fit

This package is about proving the platform, not pretending every workflow belongs on self-hosted infrastructure today.

Risks

1. False Negatives From Making The Proof Path Too Heavy

If the new default-branch proof path tries to do too much, it will become a performance or capacity complaint instead of a platform proof.

Mitigation:

• keep commands small
• prove the lane and cache contract, not the entire repo release process

2. Duplicating Work With validate.yml

If the new workflow repeats the same app checks already in validate.yml, the repo gains cost without gaining clarity.

Mitigation:

• choose representative proof commands, not full duplicates

3. Hiding Hosted Exceptions Again

If hosted publication workflows are partially moved or renamed in the same PR, the repository can become harder to explain, not easier.

Mitigation:

• keep this package narrow and explicit

Acceptance Criteria

• main has one explicit default-branch workflow proving:
  • tinyland-docker
  • tinyland-nix
  • tinyland-nix-heavy
• that workflow uses local GloriousFlywheel actions, not ad hoc shell glue
• no one has to cite feat/arc-runners to explain source-repo self-dogfood
• hosted publication and docs paths remain clearly named exceptions

Verification

Expected checks after implementation:

1. the new workflow triggers on main and pull requests
2. each self-hosted lane shows:
   • runner identity
   • explicit bootstrap where relevant
   • injected cache variables where relevant
3. the old test-arc-runners.yml either:
   • becomes manual-only soak coverage
   • or is clearly redundant and removable

Rollback

If the new proof path proves noisy or fragile:

• keep the file
• reduce job payloads
• do not fall back to feature-branch-only proof unless the failure is clearly a platform outage

The point is to preserve default-branch authority, not to re-hide the problem.