// SPDX-License-Identifier: CC-BY-SA-4.0
// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell
= Stable Release Gate
:toc: left
:sectnums:

No Hyperpolymath repository, specification, tool, service, library, or
multi-repo system may be tagged, described, or marketed as `v1.0.0` stable
until it passes a full audit. Feature completion is not enough.

`v1.0.0` means audited stability: the central claims are proven where they
must be proven, tested where they must be tested, benchmarked where they
claim performance, and verified in operation.

`v1.0.0` stable does NOT mean "full release". Full release is reserved for
projects that also achieve the broader best-practice operational bar tracked
on the roadmap: telemetry, observability, automatic evidence capture,
traceability, provenance, and mature release process tooling.

If the audit is incomplete, the project stays in `draft`, `alpha`, `beta`, or
`rc`. "Nearly ready" is pre-release status, not stable status.

If a repository, paper, or system is already labelled `stable`, `v1.0.0`, or
higher and then fails this gate, it MUST be demoted until the blockers are
closed. Retraction is the correct response to audit failure.

== 1. Scope

This gate applies to:

* Single repositories
* Monorepos
* Multi-repo systems with shared claims
* Specifications with reference implementations
* Release-tagged papers or artifacts tied to a software release

If a `v1.0.0` claim depends on more than one repository, the gate applies to
all repositories inside that claim boundary.

== 2. Non-Negotiable Rule

A stable release may claim only what is proven, tested, benchmarked, and
operationally verified. Any missing proof, missing test layer, placeholder
benchmark, broken build, errant execution path, or unresolved audit debt in
the claimed core blocks `v1.0.0`.

== 3. Hard Gates

=== 3.1 Proof Completeness

* Everything necessary to support the release's central correctness, safety,
  security, typing, protocol, or reversibility claims MUST be proven or
  removed from the stable claim set.
* `believe_me`, `sorry`, `Admitted`, `assert_total`, `postulate`,
  `unsafeCoerce`, `Obj.magic`, template placeholders, and open holes in
  claimed proof paths are stable-release blockers.
* `TODO`, `FIXME`, `XXX`, `HACK`, `STUB`, `PARTIAL`, unfinished marker tags,
  and equivalent scaffold residue in release paths are stable-release blockers.
* External assumptions are permitted only if they are explicit, standard,
  unavoidable, and clearly separated from derived results. Hidden assumptions
  are blockers.
* Proof files must be real, project-specific, and buildable. Template proof
  scaffolding does not count.

=== 3.2 Test Completeness

The following test layers MUST exist where applicable and MUST pass:

* Point-to-point tests
* End-to-end tests
* Build tests
* Execution tests
* Aspect tests
* Domain-specific tests for the risk surface of the project

"Passing" means:

* Zero known failing tests in the gated configuration
* Zero flaky or errant tests in the release path
* Zero placeholder or copied scaffold tests presented as coverage

=== 3.3 Benchmark Completeness

* If the project makes performance, efficiency, scalability, latency, or
  throughput claims, authentic benchmarks MUST exist and be runnable.
* Benchmarks must measure real logic, not constants, empty harnesses, copied
  templates, or smoke commands masquerading as evidence.
* Benchmark numbers used in README, paper, release notes, or talks MUST be
  reproducible from committed code and recorded outputs.

=== 3.4 Build and Execution Integrity

* Release builds MUST succeed from a clean checkout on the supported matrix.
* Executables, services, CLIs, libraries, or protocols MUST run correctly in
  representative execution scenarios.
* The release path MUST be non-errant: no known crashers, dead entry points,
  broken installers, or blocked startup paths in the supported configuration.

=== 3.5 Aspect Integrity

Aspect checks MUST be present and passing for the project's risk profile,
including where relevant:

* Security
* Concurrency
* Resource bounds
* Accessibility
* Interoperability
* Migration or compatibility
* Failure recovery

Generic unit coverage is not a substitute for aspect coverage.

=== 3.6 Static and Security Audit

* No unresolved critical or high severity audit findings in the stable path.
* No misleading template residue in proofs, tests, benchmarks, papers, or
  release notes.
* Dangerous patterns in trusted code paths MUST be eliminated or explicitly
  justified and quarantined.

=== 3.7 Claim and Artifact Parity

* The title, abstract, README, changelog, release notes, marketing copy, and
  repository metadata MUST not claim more than the artifact supports.
* If the title says "verified", "sound", "secure", "safe", "provable", or
  "reversible", the evidence must exist at that exact level.
* Trivial claims are also unacceptable. Stable release notes must state the
  strongest claim the evidence actually supports: no weaker, no stronger.

== 4. Cross-Repo Blitz Rule

If a system claim spans multiple repositories, audits must be blitzed across
all in-scope repositories before `v1.0.0`.

This means:

* Every participating repository gets the same proof, test, benchmark, build,
  execution, and aspect review at release time.
* A weak companion repository blocks a strong headline repository from making
  system-level stable claims.
* The weakest in-scope repository controls the system release stage.

No repo may hide multi-repo risk behind a single polished README.

== 5. Release Stage Interpretation

[cols="1,3"]
|===
| Stage | Meaning

| `draft`
| Design and implementation are still moving. Large correctness, testing, and release-surface gaps are expected.

| `alpha`
| Internal dogfooding stage. The project has been pushed into real use by you across your own working environment, repos, and workflows hard enough to absorb the first major wave of failures. Temporary breakage and delay are acceptable; shallow testing is not.

| `beta`
| External release stage. The software has escaped your own repo boundary and has been seen behaving as a release in other repos, installations, or real users. Internal dogfooding alone is not enough for `beta`. Stable evidence may still be incomplete, but the remaining gaps must be explicit and bounded.

| `rc`
| Release candidate. Full audit path is wired and nearly closed. Only bounded, non-foundational fixes may remain.

| `v1.0.0`
| Stable release. All hard gates pass. No foundational proof, testing, benchmark, build, execution, aspect, or audit blockers remain.

| `full release`
| Higher than stable. Reserved for projects that have not only passed the stable gate but also closed the best-practice operational gaps on the roadmap. Do not use this label casually or as a synonym for `v1.0.0`.
|===

== 6. Relation to Publication Gate

For papers, DOI deposits, and journal or conference submissions, this stable
release gate is necessary but not sufficient. Those artifacts must also pass
link:../publication-pre-flight/PREFLIGHT.adoc[Publication Pre-Flight].
