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

= Component Readiness Grades (CRG)
Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
v2.0, 2026-03-30
:toc:
:toclevels: 2
:sectnums:

== Overview

Component Readiness Grades (CRG) is a general-purpose quality assessment scheme
for software components. It defines seven grades (X, F, E, D, C, B, A) that map
individual components to release thresholds based on the evidence of their readiness.
This v2 revision intentionally raises the bar: long alpha and beta phases are
expected, publication requires stronger evidence, and the standard is open to
challenge if readers think the bar is still too low.

This standard is part of the
https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium Standard Repositories (RSR)]
family of standards.

== Purpose

Most software projects assess quality at the project level ("version 2.0 is
stable"). CRG operates at the component level, recognising that a project is
a collection of parts with varying levels of maturity. A project may have
battle-hardened core modules alongside untested experimental features — CRG
gives you the vocabulary to say so precisely.

== Grade Summary

[cols="1,2,2,2,4"]
|===
| Grade | Name | Release Stage | Stability Posture | Meaning

| **X**
| Untested
| —
| —
| No testing performed. Status unknown.

| **F**
| Harmful / Wasteful
| —
| —
| Actively harmful, wasteful, or better handled by an external tool. Reject, deprecate, or delegate.

| **E**
| Minimal / Salvageable
| Pre-alpha
| Unstable
| Does something slight. Barely functional. Needs redesign or major work.

| **D**
| Partial / Inconsistent
| Alpha
| Unstable
| Works on some things but not systematically. Honest label: `alpha-unstable`. Requires RSR compliance or a documented equivalent repository discipline.

| **C**
| Self-Validated
| Alpha
| Stable in home context
| Dogfooded and reliable in the home context. Honest label: `alpha-stable`. Requires deep code and folder annotation.

| **B**
| Broadly Validated
| Beta
| Stable for broad trial
| Tested on 6+ diverse external targets and seen outside the home repo. Honest label: `beta-stable`. Minimum for non-abstract publication.

| **A**
| Field-Proven
| Stable
| Stable
| Real-world external feedback confirms value. Minimum for Stable.
|===

== Key Design Decisions

**Grades are per-component, not per-project.** A project with ten A-grade
components and one F-grade component is not an A-grade project.

**Grade A does not mean perfection.** It means the component has demonstrated
value in the field and has not regressed. There is always more to do.

**Grade F includes opportunity cost.** A technically functional component earns
F if maintaining it diverts effort from something more valuable, or if an
existing external tool does the job better.

**Grades are earned and can be lost.** Promotion requires evidence. Demotion
happens when evidence of quality disappears or evidence of harm appears.

**The gaps are intentionally large.** Moving from D to C means surviving hard
internal dogfooding. Moving from C to B means escaping the home repo and
earning external validation. Moving from B to A means enduring real-world use.
Long periods in alpha or beta are normal when the standard is honest.

**`Beta` should reassure, not merely flatter.** In CRG terminology, `beta`
implies `beta-stable`: externally exposed and safe enough for broad trial.
If something is still externally visible but too shaky for that description,
call it `public alpha`, not `beta`.

**Non-abstract publication starts at B.** Do not publish implementation-facing
work as if it were ready for community reliance until the relevant components
have reached `B` or above. Earlier publication is acceptable only for genuinely
abstract, theoretical, or clearly conjectural work that does not overclaim
implementation status.

**This standard invites challenge.** If you think these requirements are still
insufficient, say so and explain the missing evidence. The point of CRG v2 is
to make the bar explicit and revisable upward, not to pretend it is final.

**Grades can be skipped.** The scheme defines evidence thresholds, not mandatory
sequential steps. A component with strong evidence can skip intermediate grades.

== Full Specification

See link:COMPONENT-READINESS-GRADES.md[COMPONENT-READINESS-GRADES.md] for the
complete standard, including:

- Detailed grade definitions with examples
- Evidence requirements for each grade
- Assessment guidelines and checklists
- Promotion and demotion criteria
- Template assessment tables (Markdown and Guile Scheme formats)
- Conformance requirements

== Adoption

To adopt CRG in your project:

1. Create a `READINESS.md` file (or add a section to your `STATE.scm`).
2. List each assessable component with its current grade.
3. Provide evidence for each grade above X.
4. Ensure components at `D` or above satisfy RSR compliance or a documented equivalent.
5. Ensure components at `C` or above have deep code and folder annotation.
6. Review grades before each release and at least once per release cycle.
7. Respect the minimum grade thresholds when choosing release stages and publication claims.

== License

This standard is licensed under PMPL-1.0-or-later (Palimpsest License).
See link:../../LICENSE[LICENSE] for the full license text.
