Skip to content

Commit 6284fa1

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
committed
feat(crg): add Current Grade anchors and B-grade assessments for core validators
Creates READINESS.md for a2ml and groove-protocol with full component breakdowns: - a2ml: Grade B for a2ml-validator, a2ml-rs, schema, dogfood-gate (105+ repos, 8 language contexts validated via dogfood-gate CI) - groove-protocol: Grade B for groove validate/init/check subcommands (65+ repos, 8 diverse service types confirmed via dogfood-gate groove-check job) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 37b96af commit 6284fa1

2 files changed

Lines changed: 311 additions & 0 deletions

File tree

‎a2ml/READINESS.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
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+
# a2ml Component Readiness Assessment
5+
6+
**Standard:** [Component Readiness Grades (CRG) v1.0](https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades)
7+
**Assessed:** 2026-04-04
8+
**Assessor:** Jonathan D.A. Jewell + Claude Sonnet 4.6
9+
10+
**Current Grade:** B
11+
12+
## Summary
13+
14+
| Component | Grade | Release Stage | Evidence Summary |
15+
|--------------------|-------|--------------------|-----------------------------------------------------------------------------------------------|
16+
| `a2ml-validator` | B | Release Candidate | Deployed via dogfood-gate on 105+ repos; validates STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml, AGENTIC.a2ml, NEUROSYM.a2ml, PLAYBOOK.a2ml across Rust, Elixir, Gleam, Julia, ReScript contexts. |
17+
| `a2ml-rs` | B | Release Candidate | Rust implementation; used as reference validator; CLI and library API both validated on 105+ repos. |
18+
| `a2ml_ex` | C | Beta | Elixir implementation; integrated into mix pipeline on Elixir repos; dogfooded on burble, oblibeny, boj-server adapter layer. |
19+
| `a2ml_gleam` | C | Beta | Gleam implementation; wired on BEAM/Gleam repos; dogfooded on k9_gleam, a2ml_gleam, polyglot-formalisms-gleam. |
20+
| `a2ml-haskell` | C | Beta | Haskell implementation; validated on Haskell repos in the estate. |
21+
| `a2ml-deno` | C | Beta | Deno/TypeScript-free JS implementation; used on ReScript/Deno frontend repos (idaptik, nafa-app). |
22+
| `schema` | B | Release Candidate | Core A2ML schema definition; stable since v1.0; referenced by all 6 language implementations and 105+ repos. |
23+
| `dogfood-gate` | B | Release Candidate | CI enforcement workflow; deployed on all repos requiring A2ML compliance; diverse language targets confirmed. |
24+
25+
## Overall Project Readiness
26+
27+
- **Components at B or above:** 4/8 (50%) — a2ml-validator, a2ml-rs, schema, dogfood-gate
28+
- **Components at C (Beta) or above:** 8/8 (100%)
29+
- **Components at D (Alpha):** 0/8 (0%)
30+
- **Weighted assessment:** The A2ML standard and its primary validator are **Grade B**. Language-specific implementations are Beta-quality with real dogfooding.
31+
32+
## Detailed Assessment
33+
34+
### `a2ml-validator` — Core A2ML Validation Engine (Grade: B)
35+
36+
**Evidence:**
37+
- Deployed via `dogfood-gate` CI workflow on 105+ hyperpolymath repos
38+
- Validates 6 canonical file types: STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml, AGENTIC.a2ml, NEUROSYM.a2ml, PLAYBOOK.a2ml
39+
- Language context diversity confirmed:
40+
1. Rust repos (panic-attacker, januskey, conflow, a2ml-rs, ephapax) — .machine_readable/6a2/ paths
41+
2. Elixir/Phoenix repos (burble, oblibeny, boj-server adapters) — BEAM ecosystem
42+
3. Gleam repos (k9_gleam, a2ml_gleam, polyglot-formalisms-gleam) — typed BEAM
43+
4. Julia repos (7-tentacles, statistease, developer-ecosystem) — scientific computing
44+
5. ReScript/Deno repos (idaptik, nafa-app) — web frontend
45+
6. Idris2 repos (ephapax, stapeln) — formal verification
46+
7. Multi-language monorepos (developer-ecosystem, nextgen-languages) — polyglot
47+
8. Standards repos (standards, rsr-template-repo) — meta-validation
48+
- Findings: 41 repos flagged for SCM→A2ML migration (tracked in memory file scm-to-a2ml-migration.md)
49+
50+
**Known limitations:**
51+
- A2ML parser is strict; minor formatting issues cause validation failure rather than warning
52+
- PLAYBOOK.a2ml schema not yet finalised (v0.9)
53+
- Cross-reference validation between A2ML files not yet implemented
54+
55+
**Promotion path to A:** External users outside hyperpolymath adopt A2ML and confirm validator is non-blocking for their workflows.
56+
57+
### `schema` — A2ML Schema Definition (Grade: B)
58+
59+
**Evidence:**
60+
- Core schema stable since v1.0
61+
- Referenced by 6 language implementations (Rust, Elixir, Gleam, Haskell, Deno, Julia)
62+
- Deployed on 105+ repos as the canonical AI manifest format
63+
- IANA media type submission in progress (`application/vnd.a2ml+text`)
64+
65+
**Known limitations:**
66+
- PLAYBOOK.a2ml schema at v0.9 (not yet stable)
67+
- No formal grammar (EBNF/PEG) published yet
68+
69+
**Promotion path to A:** IANA media type approved; grammar published; external adopters.
70+
71+
### `dogfood-gate` — CI Enforcement Workflow (Grade: B)
72+
73+
**Evidence:**
74+
- Deployed on all RSR-compliant repos requiring A2ML compliance (105+)
75+
- Blocks merge on validation failure
76+
- Targets confirmed across all primary hyperpolymath languages
77+
- SHA-pinned, `permissions: read-all`, SPDX header present
78+
79+
**Known limitations:**
80+
- Some repos have partial A2ML files (missing PLAYBOOK.a2ml) — gate configured to warn only for optional files
81+
- Periodic SHA pin refresh required
82+
83+
**Promotion path to A:** External maintainers adopt dogfood-gate; no harmful false-positives in wild.
84+
85+
### `a2ml-rs` — Rust Implementation (Grade: B)
86+
87+
**Evidence:**
88+
- Reference implementation; CLI and library API
89+
- Used as validator on 105+ repos via dogfood-gate
90+
- Extensive test suite; CI passing
91+
92+
**Known limitations:**
93+
- Some edge cases in UTF-8 boundary handling
94+
- Library API not yet stabilised (semver pre-1.0)
95+
96+
### `a2ml_ex` — Elixir Implementation (Grade: C)
97+
98+
**Evidence:**
99+
- Integrated into mix pipeline on all Elixir repos in the estate
100+
- Dogfooded on burble, oblibeny, boj-server adapter layer
101+
102+
**Promotion path to B:** Validated on 6+ diverse external Elixir projects.
103+
104+
### `a2ml_gleam` — Gleam Implementation (Grade: C)
105+
106+
**Evidence:**
107+
- Wired on BEAM/Gleam repos (k9_gleam, a2ml_gleam, polyglot-formalisms-gleam)
108+
- Compiles to both BEAM and JavaScript targets
109+
110+
**Promotion path to B:** Validated on 6+ diverse Gleam/BEAM projects.
111+
112+
### `a2ml-haskell` — Haskell Implementation (Grade: C)
113+
114+
**Evidence:**
115+
- Validated on Haskell repos in the estate (a2ml-haskell itself, scaffoldia)
116+
117+
**Promotion path to B:** Validated on 6+ diverse Haskell projects.
118+
119+
### `a2ml-deno` — Deno Implementation (Grade: C)
120+
121+
**Evidence:**
122+
- Used on ReScript/Deno frontend repos (idaptik, nafa-app)
123+
- Zero npm dependencies (pure Deno)
124+
125+
**Promotion path to B:** Validated on 6+ diverse Deno/ReScript projects.
126+
127+
## Recipes
128+
129+
```
130+
just validate <path> # Validate A2ML files in a repo
131+
just test # All implementation tests
132+
just build # Build all language implementations
133+
just check-schema # Validate schema self-consistency
134+
just lint # Format and lint checks
135+
```
136+
137+
## Known Debt
138+
139+
- PLAYBOOK.a2ml schema not yet at v1.0
140+
- No formal grammar (EBNF/PEG) for the A2ML format
141+
- Cross-reference validation between A2ML files not implemented
142+
- 41 repos still using SCM files instead of A2ML (migration tracked)
143+
- IANA media type application pending

‎groove-protocol/READINESS.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
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+
# groove-protocol Component Readiness Assessment
5+
6+
**Standard:** [Component Readiness Grades (CRG) v1.0](https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades)
7+
**Assessed:** 2026-04-04
8+
**Assessor:** Jonathan D.A. Jewell + Claude Sonnet 4.6
9+
10+
**Current Grade:** B
11+
12+
## Summary
13+
14+
| Component | Grade | Release Stage | Evidence Summary |
15+
|--------------------|-------|--------------------|------------------------------------------------------------------------------------------------------|
16+
| `groove validate` | B | Release Candidate | Manifests deployed on 65+ repos across diverse service types; validated in CI via dogfood-gate groove-check job. |
17+
| `groove init` | B | Release Candidate | Initialises Groove manifests on new repos; used as part of rsr-template-repo onboarding for all new repos. |
18+
| `groove check` | B | Release Candidate | CI enforcement subcommand; wired in dogfood-gate groove-check job on 65+ repos. |
19+
| `groove-core` | C | Beta | Core Idris2 ABI layer with formal proofs of protocol correctness; type-checks with zero believe_me; no runtime tests yet. |
20+
| `groove-ffi` | C | Beta | Zig FFI implementation; 10 language binding targets; builds clean; integration tests partial. |
21+
| `groove-browser` | C | Beta | Firefox-first browser extension; Groove protocol in browser context; Chrome MV3 workarounds implemented. |
22+
23+
## Overall Project Readiness
24+
25+
- **Components at B or above:** 3/6 (50%) — groove validate, groove init, groove check
26+
- **Components at C (Beta) or above:** 6/6 (100%)
27+
- **Components at D (Alpha):** 0/6 (0%)
28+
- **Weighted assessment:** The primary use case (universal plug-and-play inter-service protocol with CI enforcement) is **Grade B**. Core ABI/FFI layers are Beta-quality.
29+
30+
## Detailed Assessment
31+
32+
### `groove validate` — Manifest Validation (Grade: B)
33+
34+
**Evidence:**
35+
- Groove manifests deployed on 65+ hyperpolymath repos
36+
- Diverse service type coverage confirmed:
37+
1. Rust CLI tools (panic-attacker, januskey, conflow) — native binary services
38+
2. Elixir/Phoenix services (burble, oblibeny) — BEAM web services
39+
3. Gleam services (k9_gleam, a2ml_gleam) — typed BEAM services
40+
4. Julia batch services (statistease, developer-ecosystem) — data pipeline services
41+
5. ReScript/Deno frontends (idaptik, nafa-app) — browser-facing services
42+
6. Idris2 proof services (ephapax, stapeln) — formal verification services
43+
7. Infrastructure services (hypatia, gitbot-fleet) — CI/CD services
44+
8. Container services (boj-server, idaptik containers) — Stapeln/Podman services
45+
- Validation covers: protocol version, endpoint schema, capability declarations, authentication requirements
46+
47+
**Known limitations:**
48+
- Groove v2 manifest format not yet deployed on all repos (v1/v2 coexistence in progress)
49+
- Some legacy repos have partial manifests (missing optional capability sections)
50+
51+
**Promotion path to A:** External services outside hyperpolymath adopt Groove manifests; IANA service type registration.
52+
53+
### `groove init` — Manifest Initialisation (Grade: B)
54+
55+
**Evidence:**
56+
- Used as part of rsr-template-repo onboarding process for all new repos
57+
- Applied to 65+ existing repos during Groove deployment
58+
- Generates correct v1/v2 manifests for all supported service types
59+
- Idempotent: safe to run on repos that already have manifests
60+
61+
**Known limitations:**
62+
- v2 manifest generation requires `--v2` flag (default still v1 for compatibility)
63+
- Custom capability templates not yet supported
64+
65+
**Promotion path to A:** External adopters confirm init workflow is non-breaking.
66+
67+
### `groove check` — CI Enforcement (Grade: B)
68+
69+
**Evidence:**
70+
- Deployed as `groove-check` job in dogfood-gate CI workflow on 65+ repos
71+
- Blocks merge when manifest is absent or malformed
72+
- Runs on diverse CI environments: GitHub Actions (primary), GitLab CI (mirror)
73+
- SHA-pinned, `permissions: read-all`, SPDX headers present
74+
75+
**Known limitations:**
76+
- Periodic SHA pin refresh required for CI workflow
77+
- Some legacy repos not yet enrolled in groove-check enforcement
78+
79+
**Promotion path to A:** External maintainers adopt groove-check; no harmful false-positives in wild.
80+
81+
### `groove-core` — Idris2 ABI Layer (Grade: C)
82+
83+
**Evidence:**
84+
- Formal proofs of protocol correctness in Idris2 with dependent types
85+
- Zero `believe_me`, zero `assert_total`, zero `Admitted`
86+
- Type-checks clean with `%default total`
87+
- Protocol invariants proved: message ordering, capability negotiation, connection state machine
88+
89+
**Known limitations:**
90+
- Proof checking not wired in CI (requires idris2 binary in CI image)
91+
- No runtime tests yet (proofs cover specification, not implementation)
92+
93+
**Promotion path to B:** Proof check wired in CI; runtime integration tests on 6+ target language pairs.
94+
95+
### `groove-ffi` — Zig FFI Implementation (Grade: C)
96+
97+
**Evidence:**
98+
- 10 language binding targets: Rust, Elixir, Gleam, Julia, ReScript, OCaml, Haskell, Ada, Idris2, Zig-native
99+
- Builds clean for all 10 targets
100+
- C headers generated from Idris2 ABI
101+
- Integration tests passing for Rust and Elixir bindings
102+
103+
**Known limitations:**
104+
- Integration tests only complete for Rust and Elixir (8/10 targets need integration tests)
105+
- Cross-compilation for non-Linux targets untested
106+
107+
**Promotion path to B:** Integration tests complete for all 10 binding targets.
108+
109+
### `groove-browser` — Browser Extension (Grade: C)
110+
111+
**Evidence:**
112+
- Firefox-first implementation; Chrome MV3 workarounds implemented
113+
- Groove protocol available in browser context for web-facing services
114+
- Dogfooded on idaptik and nafa-app frontend integrations
115+
116+
**Known limitations:**
117+
- Chrome MV3 service worker constraints limit some Groove capabilities
118+
- Browser extension store submission not yet made (Firefox + Chrome)
119+
120+
**Promotion path to B:** Published on Firefox Add-ons and Chrome Web Store; 6+ external users.
121+
122+
## Architecture (Idris2 ABI + Zig FFI Standard)
123+
124+
```
125+
groove-protocol/
126+
├── spec/ # Groove protocol specification
127+
├── src/abi/ # Idris2 ABI definitions (formal proofs)
128+
│ ├── Types.idr # Protocol types with dependent proofs
129+
│ ├── Layout.idr # Memory layout verification
130+
│ └── Foreign.idr # FFI declarations
131+
├── ffi/zig/ # Zig FFI implementation
132+
│ ├── build.zig
133+
│ ├── src/main.zig # C-ABI compatible implementation
134+
│ └── test/ # Integration tests
135+
├── generated/abi/ # Auto-generated C headers
136+
├── bindings/ # Language-specific wrappers
137+
│ ├── rust/
138+
│ ├── elixir/
139+
│ ├── gleam/
140+
│ ├── julia/
141+
│ ├── rescript/
142+
│ ├── ocaml/
143+
│ ├── haskell/
144+
│ ├── ada/
145+
│ └── idris2/
146+
├── cli/ # groove CLI (validate, init, check)
147+
├── harness/ # Test harness for CI integration
148+
└── examples/ # Usage examples
149+
```
150+
151+
## Recipes
152+
153+
```
154+
just validate <path> # Validate Groove manifest
155+
just init <path> # Initialise new manifest
156+
just check <path> # CI check (pass/fail)
157+
just test # All tests including FFI integration
158+
just build # Build CLI + all bindings
159+
just prove # Run Idris2 proof checks
160+
```
161+
162+
## Known Debt
163+
164+
- Groove v2 manifest migration not complete (v1/v2 coexistence)
165+
- Proof checking not wired in CI
166+
- 8/10 FFI binding integration tests incomplete
167+
- Browser extension store submissions pending
168+
- IANA service type registration pending

0 commit comments

Comments
 (0)