Skip to content

Commit 68715a7

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
authored
feat(standards): add TRG + CRG per-language profile templates (#229)
## Summary Fills a gap in the existing TRG/CRG standards: both standards permit per-language profiles (TRG §1.1, CRG §4.6) that tighten the baseline, but neither shipped a profile template. - **`toolchain-readiness-grades/templates/TRG-PROFILE-TEMPLATE.adoc`** — mirrors the per-component breakdown from TRG §3 (F1-F7 front-end, M1-M5 middle-end, B1-B6 back-end, T1-T9 tool surface), each with its own grade column and evidence column - **`component-readiness-grades/templates/CRG-PROFILE-TEMPLATE.adoc`** — mirrors the released-component shape from CRG §3; one row per released artefact, plus a grade-clause rationale table per CRG §4 Both templates use the same outer structure as the ARG/FRG templates introduced in #226 (metadata header, axes recap, language-specific tightening, honest-gaps, path-to-next-grade, demotion risk, iteration history, review cycle, VeriSimDB attestation footer). ## Follow-ups (separate PRs) Per-language TRG + CRG profiles to land in: - `affinescript` - `ephapax` - `my-lang` - `typed-wasm` (compilation target treated as a language-shaped artefact — has grammar, AST, semantics, type system, runtime) ## Test plan - [ ] CI passes - [ ] `.adoc` renders cleanly - [ ] No SPDX-header lint complaints 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent f0c5ef1 commit 68715a7

2 files changed

Lines changed: 390 additions & 0 deletions

File tree

‎component-readiness-grades/templates/CRG-PROFILE-TEMPLATE.adoc‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
3+
4+
= CRG-PROFILE — {LANGUAGE_NAME}
5+
:toc: left
6+
:toclevels: 2
7+
8+
[cols="1,3"]
9+
|===
10+
| Field | Value
11+
12+
| Language | {LANGUAGE_NAME}
13+
| Repository | {REPO_URL}
14+
| Current CRG Grade | {GRADE} (X \| F \| E \| D \| C \| B \| A)
15+
| Assessed | {YYYY-MM-DD}
16+
| Assessor | {NAME <email>}
17+
| CRG Spec Version | 2.2
18+
| ARG Profile | spec/ARG-PROFILE.adoc
19+
| TRG Profile | spec/TRG-PROFILE.adoc
20+
| FRG Profile | spec/FRG-PROFILE.adoc
21+
|===
22+
23+
== About this profile
24+
25+
This profile applies the *CRG v2.2 (STRICT)* baseline to
26+
{LANGUAGE_NAME} and records the current honest grade per released
27+
component, the evidence supporting it, and the path to the next grade.
28+
29+
CRG grades *released components*: artefacts the project publishes for
30+
external consumers (libraries, binaries, services, plugins). Toolchain
31+
internals are graded separately under TRG; the user-facing language
32+
adoption surface is graded under ARG; the foundational research
33+
surface is graded under FRG.
34+
35+
CRG = {GRADE} (worst-of any released component). The full chain of
36+
axes for this language:
37+
38+
* ARG: {ARG_GRADE}
39+
* TRG: {TRG_GRADE}
40+
* FRG: {FRG_GRADE}
41+
* CRG: {GRADE}
42+
* RSR: {RSR_LEVEL}
43+
44+
== Released components
45+
46+
A *released component* is any unit of work this repository publishes
47+
under its own name + version: crate, library, binary, plugin, schema,
48+
or vendored artefact. Each is graded independently against CRG.
49+
50+
The list below is the complete published surface as of {YYYY-MM-DD}.
51+
52+
[cols="2,1,3,4", options="header"]
53+
|===
54+
| Component | Grade | Release stage | Evidence
55+
56+
| {component-1-name} | {grade} | {pre-alpha / alpha / alpha-stable / beta / stable / N/A} | {Path or registry URL; test coverage; CI status}
57+
| {component-2-name} | {grade} | {stage} | {Evidence}
58+
| {component-3-name} | {grade} | {stage} | {Evidence}
59+
| {...} | {grade} | {stage} | {Evidence}
60+
|===
61+
62+
If the project has no externally-released components, the
63+
language-level CRG is *X* by definition and this table will be empty
64+
with a single explanatory row.
65+
66+
== Per-component evidence (deep)
67+
68+
For each component above whose grade is *D or higher* (CRG §4.4+
69+
requires the deep per-file + per-directory annotation at grade C
70+
onward), include a per-file / per-directory annotation table here or
71+
link to one. The canonical example is
72+
`gossamer/docs/governance/CRG-AUDIT-2026-04-18.adoc`.
73+
74+
* {component-1-name}: {link to its audit file}
75+
* {component-2-name}: {link to its audit file}
76+
77+
== Grade rationale
78+
79+
[cols="2,1,4", options="header"]
80+
|===
81+
| Grade clause (CRG §4) | Met? | Evidence
82+
83+
| *E1 — At least one test exists*
84+
| {YES/NO}
85+
| {Path; brief description}
86+
87+
| *E2 — Failures documented*
88+
| {YES/NO}
89+
| {Path to failure ledger}
90+
91+
| *D1 — Test matrix documented*
92+
| {YES/NO}
93+
| {Path}
94+
95+
| *D2 — Scope documented*
96+
| {YES/NO}
97+
| {Path}
98+
99+
| *D3 — RSR compliance*
100+
| {YES/NO}
101+
| {RSR level + audit ref}
102+
103+
| *C1 — Dogfooded*
104+
| {YES/NO}
105+
| {Internal-use list}
106+
107+
| *C2 — CI green*
108+
| {YES/NO}
109+
| {Workflow run URL; cadence}
110+
111+
| *C3 — Deep annotation (per-file + per-dir)*
112+
| {YES/NO}
113+
| {Annotation doc path}
114+
115+
| *B1 — ≥6 diverse external targets*
116+
| {YES/NO/N/A}
117+
| {External-targets list with diversity argument}
118+
119+
| *B2 — Issues fed back from external use*
120+
| {YES/NO/N/A}
121+
| {Closed-issue trail; external-reporter labels}
122+
123+
| *A1 — Confirmed real-world value, no harm*
124+
| {YES/NO/N/A}
125+
| {External-feedback corpus}
126+
127+
| *VeriSimDB attestation (grade C+)*
128+
| {YES/NO}
129+
| {Attestation ID; last-ingested timestamp}
130+
|===
131+
132+
== Language-specific tightening (this profile only)
133+
134+
For {LANGUAGE_NAME}, the following additional obligations apply at the
135+
stated grades:
136+
137+
* *Grade C tightening:* {Language-specific obligation, e.g.
138+
"AffineScript stdlib: every released module MUST have a borrow-check
139+
fixture suite."}
140+
* *Grade B tightening:* {e.g. "Ephapax verifier crate: every released
141+
layer MUST have a published soundness theorem."}
142+
* *Grade A tightening:* {Aspirational, e.g. "Registered VeriSimDB
143+
instance, public health check."}
144+
145+
These tightenings are *additional* to the baseline — none of the
146+
baseline evidence is waived.
147+
148+
== What is NOT yet met (honest gaps)
149+
150+
* {Bullet list of specific CRG evidence the released components do not
151+
currently produce, grouped by component}
152+
* {Each gap should be specific enough that a reader can verify by
153+
inspection of the repo}
154+
155+
== Path to next grade ({NEXT_GRADE})
156+
157+
* {Specific next-step item 1, naming the gated component(s), with
158+
estimated work}
159+
* {Specific next-step item 2}
160+
* {...}
161+
162+
*Realistic timeline estimate:* {N weeks/months}
163+
164+
== Path to grade beyond that ({GRADE_AFTER_NEXT})
165+
166+
* {Larger items that follow the immediate next grade}
167+
168+
== Demotion risk
169+
170+
* *Lowest:* {What would have to break for the grade to drop by one,
171+
e.g. "single released component CI flips to red"}
172+
* *Medium:* {What would have to break for a multi-step demotion}
173+
* *Catastrophic:* {What would force demotion to F, e.g. "released
174+
component found to be harmful in production"}
175+
176+
== Iteration history
177+
178+
[cols="1,1,4", options="header"]
179+
|===
180+
| Date | Grade | Notes
181+
182+
| {YYYY-MM-DD} | {grade} | Initial assessment.
183+
| {YYYY-MM-DD} | {grade} | {Reason for change.}
184+
|===
185+
186+
== Review cycle
187+
188+
* *Routine:* Reassess on every release cycle (per CRG §6.3).
189+
* *Immediate:* Reassess within 7 days of any released-component
190+
regression.
191+
* *VeriSimDB drift alert:* Reassess within 24 hours of any drift alert
192+
from VeriSimDB on this language's released components.
193+
194+
== Footer
195+
196+
Run `just crg-badge` in this repo to generate the shields.io badge for
197+
the README.
198+
199+
This profile is itself a VCL-total proposition. Its content is
200+
`DECLARE`'d to VeriSimDB on each commit. Drift between the claimed
201+
grade above and the underlying evidence surfaces as a grade-stale alert.

‎toolchain-readiness-grades/templates/TRG-PROFILE-TEMPLATE.adoc‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
3+
4+
= TRG-PROFILE — {LANGUAGE_NAME}
5+
:toc: left
6+
:toclevels: 2
7+
8+
[cols="1,3"]
9+
|===
10+
| Field | Value
11+
12+
| Language | {LANGUAGE_NAME}
13+
| Repository | {REPO_URL}
14+
| Current TRG Grade | {GRADE} (X \| F \| E \| D \| C \| B \| A)
15+
| Assessed | {YYYY-MM-DD}
16+
| Assessor | {NAME <email>}
17+
| TRG Spec Version | 1.0
18+
| ARG Profile | spec/ARG-PROFILE.adoc
19+
| FRG Profile | spec/FRG-PROFILE.adoc
20+
| CRG Profile | spec/CRG-PROFILE.adoc
21+
|===
22+
23+
== About this profile
24+
25+
This profile applies the *TRG v1.0* baseline to {LANGUAGE_NAME} and
26+
records the current honest grade, the evidence supporting it per
27+
component, the language-specific tightening obligations, and the path
28+
to the next grade. Per TRG §1.1, profiles may *tighten* the baseline
29+
but never *loosen* it.
30+
31+
TRG = {GRADE} (worst-of any required component per TRG §7). The full
32+
chain of axes for this language:
33+
34+
* ARG: {ARG_GRADE}
35+
* TRG: {GRADE}
36+
* FRG: {FRG_GRADE}
37+
* CRG: {CRG_GRADE} (worst-of any released component)
38+
* RSR: {RSR_LEVEL}
39+
40+
Cross-axis rule: ARG ≤ TRG holds (currently TRG = {GRADE},
41+
ARG = {ARG_GRADE}).
42+
43+
== Component grades
44+
45+
The toolchain decomposes into components drawn from TRG §3. Each
46+
component is graded independently against the four-tier audit format
47+
of TRG §4 (Must / Should / Could / Aspirational → grades E / D / C / B).
48+
The overall TRG grade is the *worst* of any MUST component.
49+
50+
=== Front-end (TRG §3.1)
51+
52+
[cols="1,3,1,4", options="header"]
53+
|===
54+
| # | Component | Grade | Evidence
55+
56+
| F1 | Grammar / Syntax | {grade} | {Path to .ebnf / .pest / .peg; SoT status}
57+
| F2 | Lexer / Tokeniser | {grade} | {Path; test coverage; fuzz harness}
58+
| F3 | Parser | {grade} | {Path; test coverage}
59+
| F4 | AST | {grade} | {Path; invariant documentation}
60+
| F5 | Macro expander | {grade or N/A} | {Path; N/A if no macros}
61+
| F6 | Import resolver / Modules | {grade} | {Path; cycle-detection evidence}
62+
| F7 | Diagnostics / Errors | {grade} | {Path; error-code index}
63+
|===
64+
65+
=== Middle-end (TRG §3.2)
66+
67+
[cols="1,3,1,4", options="header"]
68+
|===
69+
| # | Component | Grade | Evidence
70+
71+
| M1 | Semantic analyser | {grade} | {Path; resolved-name property tests}
72+
| M2 | Type checker | {grade} | {Path; test corpus}
73+
| M3 | Type-checker oracle | {grade or N/A} | {Path; N/A if not a verified language}
74+
| M4 | Proof dispatcher | {grade or N/A} | {Path; N/A if not a verified language}
75+
| M5 | Semantics document | {grade} | {Path to .adoc / paper; operational + denotational coverage}
76+
|===
77+
78+
=== Back-end (TRG §3.3)
79+
80+
[cols="1,3,1,4", options="header"]
81+
|===
82+
| # | Component | Grade | Evidence
83+
84+
| B1 | Intermediate representation | {grade} | {Path; documented invariants}
85+
| B2 | Code generator (per backend) | {grade} | {Per-backend list; coverage}
86+
| B3 | Backend registry | {grade or N/A} | {Path; N/A if only one backend}
87+
| B4 | Linker / JIT / eval | {grade} | {Path; tests}
88+
| B5 | ABI / FFI surface | {grade} | {Idris2 ABI path; Zig FFI path}
89+
| B6 | Runtime | {grade} | {Path; test coverage}
90+
|===
91+
92+
=== Tool surface (TRG §3.4)
93+
94+
[cols="1,3,1,4", options="header"]
95+
|===
96+
| # | Component | Grade | Evidence
97+
98+
| T1 | Compiler driver | {grade} | {Path to binary; CLI surface tests}
99+
| T2 | Interpreter | {grade or N/A} | {Path; N/A if compiled-first}
100+
| T3 | REPL | {grade or N/A} | {Path; smoke-test coverage}
101+
| T4 | Formatter | {grade or N/A} | {Path; round-trip property test}
102+
| T5 | LSP server | {grade or N/A} | {Path; LSP protocol coverage}
103+
| T6 | Debugger | {grade or N/A} | {Path; integration list}
104+
| T7 | Package manager | {grade or N/A} | {Path; package-resolution tests}
105+
| T8 | Standard library | {grade} | {Path; symbol-coverage estimate; test-density}
106+
| T9 | Pipeline orchestrator | {grade} | {Path; CI integration}
107+
|===
108+
109+
== Language-specific tightening (this profile only)
110+
111+
TRG §1.1 permits per-language tightening. For {LANGUAGE_NAME}, the
112+
following additional obligations apply at the stated grades:
113+
114+
* *Grade D tightening:* {Language-specific obligation, e.g. "AffineScript:
115+
type checker MUST reject borrow-after-move on every sample in the
116+
borrow-check fixture suite."}
117+
* *Grade C tightening:* {e.g. "Ephapax: the proof dispatcher MUST emit
118+
a structured judgment trace for any preservation lemma in the
119+
active layer."}
120+
* *Grade B tightening:* {Language-specific aspirational obligation.}
121+
122+
These tightenings are *additional* to the baseline — none of the
123+
baseline evidence is waived.
124+
125+
== Canonical Proof Suite extension (if verified language)
126+
127+
Per TRG §6.6, verified languages MUST extend the Canonical Proof Suite
128+
(see `templates/CANONICAL-PROOF-SUITE.adoc`). For {LANGUAGE_NAME}:
129+
130+
* {Proof obligation 1, paradigm-specific, with file path}
131+
* {Proof obligation 2}
132+
* {...}
133+
134+
If the language is not verified, mark this section "N/A" and remove
135+
the M3/M4 rows above.
136+
137+
== What is NOT yet met (honest gaps)
138+
139+
* {Bullet list of specific MUST evidence the toolchain does not currently
140+
produce, grouped by component}
141+
* {Each gap should be specific enough that a reader can verify by
142+
inspection of the repo}
143+
144+
== Path to next grade ({NEXT_GRADE})
145+
146+
* {Specific next-step item 1, naming the gated component(s), with
147+
estimated work}
148+
* {Specific next-step item 2}
149+
* {...}
150+
151+
*Realistic timeline estimate:* {N weeks/months}
152+
153+
== Path to grade beyond that ({GRADE_AFTER_NEXT})
154+
155+
* {Larger items that follow the immediate next grade}
156+
157+
== Demotion risk
158+
159+
* *Lowest:* {What would have to break for the grade to drop by one,
160+
e.g. "parser corpus regression flag flips to red"}
161+
* *Medium:* {What would have to break for a multi-step demotion}
162+
* *Catastrophic:* {What would force demotion to F, e.g. "type-checker
163+
unsoundness witness found"}
164+
165+
== Iteration history
166+
167+
[cols="1,1,4", options="header"]
168+
|===
169+
| Date | Grade | Notes
170+
171+
| {YYYY-MM-DD} | {grade} | Initial assessment.
172+
| {YYYY-MM-DD} | {grade} | {Reason for change.}
173+
|===
174+
175+
== Review cycle
176+
177+
* *Routine:* Reassess on every release cycle (per TRG §8).
178+
* *Immediate:* Reassess within 7 days of any MUST-component regression.
179+
* *VeriSimDB drift alert:* Reassess within 24 hours of any drift alert
180+
from VeriSimDB on this toolchain's attestations.
181+
182+
== Footer
183+
184+
Run `just trg-badge` in this repo to generate the shields.io badge for
185+
the README.
186+
187+
This profile is itself a VCL-total proposition. Its content is
188+
`DECLARE`'d to VeriSimDB on each commit. Drift between the claimed
189+
grade above and the underlying evidence surfaces as a grade-stale alert.

0 commit comments

Comments
 (0)