// SPDX-License-Identifier: CC-BY-SA-4.0
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>

= Toolchain Readiness Grades (TRG)
:toc:

*Status:* Active, v1.0, 2026-04-12 +
*License:* PMPL-1.0-or-later (MPL-2.0 automatic legal fallback) +
*Companion to:* Component Readiness Grades (CRG) v2.2 +
*Part of:* Rhodium Standard Repositories (RSR)

== What this is

A *strict superset* of CRG specifically for the *core toolchain components*
of a programming-language project: grammar, lexer, parser, AST, semantic
analyser, type checker, IR, codegen, linker, runtime, stdlib, REPL,
formatter, LSP, diagnostics, debugger, package manager, proof dispatcher,
ABI/FFI surface, backend registry.

TRG uses the same letter grades as CRG (`X | F | E | D | C | B | A`) but
the evidence required at each grade is significantly higher, because
toolchain components are *critical infrastructure* — every program
ever compiled by the toolchain inherits its bugs.

== Why it exists

Three reasons:

. CRG is a general-purpose component scheme. Toolchains need a tighter
  rubric.
. The 007 language project already runs MK2-style four-tier MoSCoW audits
  (`audits/audit-<component>.md`). TRG promotes that pattern to an
  estate-wide standard, with grade-thresholds attached to each tier.
. Hyperpolymath's standing priority order (dependability > security >
  interop > usability > performance > versatility > functional-extension)
  needs an enforcement vehicle for the parts of the estate that sit upstream
  of everything else.

== Files in this directory

[cols="2,5",options="header"]
|===
| File | Purpose
| `TOOLCHAIN-READINESS-GRADES.adoc` | The normative spec. Read this first.
| `README.adoc`                     | This file.
| `references/007/`                 | The 24 component audit documents
                                     copied verbatim from the 007 language
                                     project, plus the seed lexer-MK2 audit
                                     that originated the four-tier format.
                                     These are the canonical exemplars of
                                     the per-component audit format.
| `templates/`                      | The five canonical templates
                                     referenced from the spec, all
                                     v1.0 as of 2026-04-12:
                                     `templates/AUDIT-TEMPLATE.adoc`
                                     (the four-tier MoSCoW audit
                                     template),
                                     `templates/CANONICAL-PROOF-SUITE.adoc`
                                     (the M/S/E proof suite, 15
                                     entries — the gate to leave
                                     grade E),
                                     `templates/QUALIFYING-PROVERS.adoc`
                                     (the v1 qualifying-prover set:
                                     Idris2, Lean 4, Rocq, Agda),
                                     `templates/FUZZING-CORPUS-FLOOR.adoc`
                                     (the per-component fuzzing
                                     minimums),
                                     `templates/A-GRADE-LLM-PANEL.adoc`
                                     (the 6+6 panel composition rules).
| `SELF-ASSESSMENT.adoc`            | TRG applied to itself. Honest
                                     current grade: *X* (untested).
                                     The standard has been written
                                     but not yet applied to any
                                     toolchain component. Path to D
                                     and beyond is laid out.
| `TOOLCHAIN-READINESS-GRADES.a2ml` | Machine-readable counterpart of
                                     the spec, matching the CRG `.a2ml`
                                     pattern.
|===

== Quick mental model

[horizontal]
X:: absent / not working / any Must row failed
F:: tested + harmful / wasteful (delegate or remove)
E:: pre-alpha. All Must passed. Banned constructs ZERO. panic-attack
    zero Critical/High. Six A2ML files + 0-AI-MANIFEST present. Immaculate
    Guide passing.
D:: pre-alpha+. All Must + Should + the *Canonical Proof Suite* (this is
    the foundational gate). RSR-FULL. panic-attack zero across all
    severities. Fuzzing harness exists.
C:: *alpha*. All Must + Should + Could. Full Testing-Taxonomy 16×14
    coverage in Six Sigma range. Continuous fuzzing 14d. 5 fully-proven
    programs. 3-nines on top-4 priority axes.
B:: *beta*. All four tiers passed. Multi-prover cross-validation (≥2 of
    {Idris2, Lean 4, Rocq, Agda}). Single external audit. Continuous
    fuzzing 30d. 100 distinct external users. 5-nines top-4, 4-nines rest.
A:: *stable / release*. Six Sigma vs trailing-12-month IPO cohort (bottom
    decile). 5,000,000 external processor-hours. 21 fully-proven programs
    cross-validated by ≥3 independent provers. Type-theory upstream
    contribution in last 12 months. 1000 distinct external users.
    Unanimous 6+6 (humans + LLMs) signoff. *Plus* full hyperpolymath
    standards conformance (RSR, CI/CD 90d green, launch-scaffolder, PanLL,
    Hypatia zero, panic-attack zero, VeriSimDB, Stapeln, Groove, SLSA L3,
    reproducible builds, Coordination.k9, UX Manifesto).

== Demotion is immediate

Loss of any A-grade gate (canonical proof regresses, six-sigma slips,
processor-hours window drops, signoff rescinded, standards drift)
immediately demotes the component. There is no grace period. See §5.8.

== How strict is this really?

See §11 of the spec. Honest answer: TRG-A is, to the author's knowledge,
*not matched by any standard currently in use anywhere*. The author expects
approximately *zero* hyperpolymath toolchain components to hit A in the
first year, and is comfortable with the possibility that *no toolchain
component anywhere reaches A for many years*. That is the correct order of
magnitude. If A becomes easy to hit, the bar is wrong and the standard MUST
be raised.

== Per-language profiles

TRG is the *baseline*. Each hyperpolymath language is expected to publish
a `spec/TRG-PROFILE.adoc` in its own repo that *tightens* TRG with
language-specific obligations (e.g. Eclexia tropical-semiring soundness,
AffineScript region/affinity discipline, Idris2 totality discipline). A
profile may only tighten, never loosen. See §1.1.

== Interaction with CRG

A project that ships a language toolchain MUST publish *both*: a CRG grade
for the project as a whole, and a TRG grade for the toolchain. Where the
two rubrics overlap, the *stricter* grade governs. TRG is always at least
as strict as CRG.

== Open invitation

If you think TRG is still too lax (or too strict in a way that lets bad
work hide), file an issue with concrete evidence and a proposed
tightening. TRG earns trust by surviving critique.
