Public-Release Readiness

Your galaxy is about to cross a one-way door. This page is the checklist that walks it across without leaving anything private on the other side.

You built something inside a client engagement. It works. Now you want to open it to the world — but the git history is full of a client's name, an endorser's email, cross-references to private tooling. You are afraid that one git push leaks something you can never take back.

This page is for you. Not "people releasing software" — you, standing at the door, holding a history you're a little ashamed to show, wanting a way across that doesn't burn you.

Here is the picture for the whole page:

flowchart LR
    subgraph private ["Private side — stays behind"]
        G["Your galaxy<br/>+ a backpack:<br/>names, emails,<br/>private tools"]
        ARCH["Frozen archive<br/>(read-only,<br/>full history)"]
    end
    subgraph membrane ["The membrane — nine guards"]
        M["A · B · C · D · E<br/>F · G · H · I"]
    end
    subgraph public ["Public side — what a stranger may see"]
        CLEAN["Your galaxy,<br/>clean.<br/>Backpack left<br/>behind."]
    end
    G -- "crosses" --> M
    M -- "waved through" --> CLEAN
    G -. "backpack drops off" .-> ARCH

A galaxy passes through a membrane. The backpack of private things — names, emails, the orchestrator's private tools — stays behind, frozen and archived. Nothing is thrown away. It just doesn't cross. That is the single most reassuring fact on this page, so it lives in the first screen, not buried in a footnote: you do not lose your history. You leave it home, safe, on the private side.

A checklist of nine phases reads as nine chances to fail. A membrane-crossing reads as one journey with nine guards who each say "clear." Same content, opposite feeling. You arrive scared; the page's job is to turn that fear into earned confidence. So the spine is the crossing, and each guard checks one thing and waves the galaxy through.

The lesson before the list: cosmon crossed its own membrane

Before any guard, one true story — because it teaches the thing that surprises everyone.

Cosmon's engine was about ninety percent built. Typed state machines, crash-recovery, the whole orchestration core — solid, tested, proven in daily use. By every instinct it was ready.

It was not ready. The front door leaked.

• There was no AGENTS.md — so a stranger's coding agent landing in the repo had no honest map of where to look.
• CLAUDE.md was a real file, not a symlink — so the same instructions lived in two places, already drifting apart.
• The handbook pointed a visitor's agent straight at cs and .cosmon/state/ — cosmon's own private orchestrator. A stranger can't run that. The front door was sending guests into the owner's private workshop.
• And client names were sitting in pixels — inside committed screenshots — where a text search for the client's name finds nothing. The scrub that reads text walks right past an image.

Here is the counter-intuition, and it is the whole reason this page exists:

The defects do not live in the code. They live in the first five minutes of a stranger's trust.

The engine was excellent. The front door wasn't ready. That gap — between a proven core and an un-crossed membrane — is exactly what the nine guards are built to close. Keep cosmon's own story in mind as you read them: every guard below is a lesson cosmon learned by failing it first.

The nine guards at the membrane

Here is the whole journey on one screen. Read it once, top to bottom, before any detail. The table is the index. The guards are the chapters.

Three of these run in order — a hard spine. The scrub (A) comes first, because nothing else is safe until the private things are out. The stranger's-eyes pre-mortem (C) and the front-door scrub (D) follow, because they read the cleaned repo. The rest — CI (B), the doc site (E), namespaces (G), standards honesty (H) — are a parallel finishing fan: independent guards that can all check at once once the spine holds.

flowchart LR
    A["A · scrub<br/>private out"] --> C["C · stranger's<br/>five minutes"]
    C --> D["D · front-door<br/>scrub"]
    D --> CROSS(["membrane<br/>crossed"])
    B["B · CI green"] --> CROSS
    E["E · site<br/>renders"] --> CROSS
    F["F · one-gesture<br/>release"] --> CROSS
    G["G · names<br/>claimed"] --> CROSS
    H["H · honest<br/>promises"] --> CROSS
    I["I · true<br/>making-of"] --> CROSS

Now, each guard.

Guard A — Is anything private still inside?

This is the guard you came here scared of, so it comes first.

Make a red list — every name, email, client, and private tool that must never appear in public. Then prove the public copy contains none of them: git log -p of the public copy turns up zero red-list terms.

Two ways across, depending on how the private stuff is spread:

• A few stray names, scattered thinly → rewrite them out with git filter-repo (token-replace plus a mailmap for the emails). The history keeps its shape; only the private words are gone.
• Smeared across hundreds of commits (cosmon's neighbour oxymake had the client's fingerprints in 411 places) → you can't pick them out one by one. Squash the whole history to a single commit. The public repo starts fresh, clean, at commit one.

Either way — and this is the reassurance, made concrete — the full original history lives on in a private, archived, frozen repo (<your-project>-archived-history, then gh repo archive to make it read-only). That is the backpack from the first picture. It stays behind. It is not deleted. You can always open it; a stranger never can.

The invariant, in plain words: never git push from the working repo that still holds the full history. The public copy comes from a clean clone — one with no private commits to leak in the first place.

Operator-only. Guard A's destructive work — filter-repo, squash, archive — is proposed by the fleet and pulled by your hand. Never automatic. The robot prepares the surgery; you make the cut.

Cleared when: the public log is clean and the frozen archive exists.

Guard B — Are all the lights green, for the right reason?

You glance at CI and every check is red. Panic? Look closer.

A private repo on a free plan runs out of Actions minutes. When that happens, every job fails — not because your code broke, but because of a billing message dressed up to look like a code failure. The trap is to pay to turn the lights green on a repo you're about to make public.

Don't. Actions is free and unlimited on a public repo. The red vanishes the moment you flip public. So the real check is one step back: on the last commit before the minutes ran out, were the code gates green?

While you're here, close the matching gap: your local Definition of Done must mirror every CI gate. Oxymake found out the hard way that its CI ran cargo doc -D warnings but its local checklist didn't — a red light invisible from the maker's desk. If CI checks it, your local recipe checks it too.

Cleared when: code gates green on the last good commit, and local checks mirror every CI gate.

Guard C — What does a stranger see in their first five minutes?

This is the guard that catches what cosmon's own story warned about: the defects live in the first five minutes of trust, not in the code.

Run a pre-mortem panel — cosmon's reusable deep-think formula, a roomful of personas reading the repo as a first-time visitor — through two pairs of eyes:

• The user who wants to try it: About → README → install → first run → docs. Does the path hold, or does it break at step three?
• The developer who wants to contribute: architecture, invariants, ADRs — and the path to plug in their own agent system, not yours.

The panel hands back a punch-list, sorted BLOCKER / MAJOR / MINOR, each item pinned to a file and a line. The verdict cosmon and oxymake both got is the one you should expect: the engine is usually excellent and proven; the front door is what isn't ready.

Cleared when: zero open BLOCKERs before the flip.

Guard D — Does your front door send strangers into your private house?

The sharpest guard, and the one most makers don't know they need.

Your repo's agent-facing surface — AGENTS.md — is a transport layer. It points at the one true source of instructions (man <tool>, <tool> help, CONTRIBUTING.md) and never paraphrases it. Paraphrase, and the two copies drift; a year later they contradict each other and nobody knows which is true. CLAUDE.md is a symlink to AGENTS.md — same file, one place.

The invariant, as one image: a stranger's agent must never be handed the keys to your private workshop. No public pointer to cs, to cosmon, to .cosmon/state/ — tools a stranger cannot run. Cosmon's handbook once pointed a visitor's agent at cs help; oxymake's did the same. Both were sending guests into a room only the owner can enter. That is exactly the leak this guard closes.

Cleared when: every instruction lives in exactly one place, and there is no public pointer to a tool a stranger can't run.

Guard E — Does the public site render cleanly?

Build the doc site (mdBook, or the equivalent), then deploy it to Cloudflare Pages on your project's domain. Tie the apex with a proxied CNAME so your existing email keeps working — the MX and SPF records survive the move.

Then check the rendering with Playwright, the way a real browser would see it:

• The mermaid diagrams render as pictures — not shown as raw code.
• No real console errors.
• Syntax highlighting is correct in the code blocks.

This is also cosmon eating its own dog food: the page you are reading right now passed this exact guard. The same pipeline that built this site is the one Guard E describes.

Cleared when: the site serves over HTTPS on the target domain, and the visual QA is clean.

Guard F — Can you ship a version with one gesture, safely?

A release should be one turnkey recipe — just tag-release X.Y.Z — that does the whole dance for you:

1. Guards: working tree clean, you're on main, the tag doesn't already exist, the CHANGELOG carries this version.
2. Preflight: test, clippy, fmt, doc — all green.
3. Ship: regenerate the man pages, bump the version, commit, annotated tag, push — and CI builds the release.

The invariant: this recipe runs only from a clean-history clone. Its own git push would leak the private history otherwise. (Guard A's clean clone is the soil this recipe must grow in.)

Cleared when: the documented recipe is the real recipe — no drift between what the docs say and what the command does — and a tag can never ship an untested binary.

Guard G — Are your names claimed?

On crates.io, npm, pypi — reserve your name before someone else takes it.

A placeholder package with publish = true holds the name; every internal library is marked publish = false so nothing internal can ever leak out through a stray publish. Two steps, never rushed: reserve first (a placeholder at v0.0.0), then publish the real package at release. The publish itself is a manual, one-shot gesture — never wired into CI, where a mis-fire would push the wrong thing to the world.

Cleared when: cargo package / npm pack --dry-run / python -m build pass, and the names are claimable.

Guard H — Are you promising only what you deliver?

If your galaxy aligns to a standard (a research project might align to FAIR4RS), climb an honesty ladder: promise only what actually ships today. Frame everything else as a named roadmap item — not a vague "we support X" that a careful reader will catch as false.

A false compliance claim is the one defect that erodes trust permanently. Better to under-promise and name the gap.

Cleared when: there is no over-promise, and every gap is a named roadmap item.

Guard I — Is the origin story true for the public repo?

If you squashed the history (Guard A), the public repo no longer holds the long trail of how it was built. So when you write the making-of, tell it accurately for the repo a stranger actually holds. The erased traces live in the private archive — don't claim they're "still in the repo" when they aren't.

Cleared when: the making-of reads true to someone holding only the public copy.

The membrane crossed — and what stays in your hands

Recall the first picture. On the public side: your galaxy, clean. On the private side: the frozen backpack, every private thing accounted for, nothing thrown away.

Now the honest line that earns long-term trust:

The fleet prepares and proposes every guard. But the gestures you can never take back stay under your finger, not the robot's.

The irreversible, operator-only gestures:

• Flip the repo to public.
• cargo publish (and npm / pypi publish).
• Push a release tag.
• Delete or recreate a repo.
• Change DNS.

The robot walks the galaxy all the way to the door, checks every guard, and tells you each one is clear. You open the door. That division — robot prepares, human commits the irreversible act — is the same discipline you'll meet on the next page, Modes de pilotage, where the robot runs free inside a fence but never opens the four gates alone.