Skip to content

docs: how cascade is tested (two layers, reconcile gate, topology matrix) - #348

Merged
joshua-temple merged 1 commit into
mainfrom
docs/fleet-coverage
Jun 25, 2026
Merged

joshua-temple merged 1 commit into
mainfrom
docs/fleet-coverage

Conversation

@joshua-temple

Copy link
Copy Markdown
Collaborator

Problem

The docs site had no page explaining how cascade verifies its generated pipelines or what the fleet asserts. Adopters and contributors could not see the coverage stance or where the real-GitHub platform ceiling sits. Tracks #339.

Fix

Adds docs/src/content/docs/testing.md ("How it is tested"), wired into the sidebar between Architecture and Security & Hardening. The page covers:

  • The two test layers and why both exist: the hermetic act plus gitea harness (every PR; emission and structural asserts, conflict and retry injection) and the live fleet (real GitHub, every release-candidate tag, auto-promote only on a fully green fan-out), with unit tests on the pure logic underneath.
  • The reconcile gate: every dispatched and side-effect run is registered with an expected conclusion (including registered negatives), and a fail-closed job enumerates every run in the window so a green suite genuinely asserted everything it caused.
  • The topology matrix mapping each cascade-example-* repo to the shape it exercises.
  • An honest coverage stance: full coverage across the layers, with the documented real-GitHub platform ceiling (Environment approvals and wait timers, native Deployments API objects, the Verified badge, app-token mint, real cloud deploy outcomes) validated by design and inspection rather than execution.

Verification

  • Astro docs site builds clean (Node 22) with /testing/ emitted and the new sidebar entry present.
  • Markdown is well-formed; no em dashes, no forbidden terms.

… fleet coverage

Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>
@joshua-temple
joshua-temple merged commit 0bfad47 into main Jun 25, 2026
15 checks passed
@joshua-temple
joshua-temple deleted the docs/fleet-coverage branch June 25, 2026 01:19
@joshua-temple joshua-temple added the docs Improvements or additions to documentation label Jun 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant