Skip to content

Commit 2776eed

Browse files
claudeclaude
committed
Merge branch 'claude/analyze-repo-improvements-LkcDI' - AVOW tests, EXPLAINME expansion, CRG self-assessment
2 parents cf786d8 + b59b35e commit 2776eed

4 files changed

Lines changed: 266 additions & 6 deletions

File tree

‎CRG-SELF-ASSESSMENT.adoc‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
3+
= CRG Self-Assessment — standards
4+
:toc:
5+
:sectnums:
6+
7+
== Current Grade: C
8+
9+
Assessed: 2026-04-09
10+
11+
== Category Checklist
12+
13+
[cols="1,1,3", options="header"]
14+
|===
15+
| Category | Status | Evidence
16+
17+
| Unit tests
18+
| Present
19+
| a2ml/bindings/rust (47), k9-svc/bindings/rust (45), mcp-repo-guardian (36), axel-protocol (14), groove-protocol (10), avow-protocol/src (8)
20+
21+
| Smoke tests
22+
| Present
23+
| `just build` compiles all sub-projects; `just test` runs full suite
24+
25+
| Property-based (P2P)
26+
| Present
27+
| proptest in a2ml + k9-svc Rust crates (parse/render roundtrip)
28+
29+
| End-to-end reflexive
30+
| Present
31+
| Real manifest parsing + roundtrip stability in mcp-repo-guardian + a2ml
32+
33+
| Contract (pre/post)
34+
| Present
35+
| a2ml + k9-svc pre/post-condition validation; avow-lib Idris2 dependent-type proofs
36+
37+
| Aspect (security)
38+
| Present
39+
| TruffleHog secret scanning, Trivy vulnerability scanning, CodeQL, OpenSSF Scorecard
40+
41+
| Benchmarks (baselined)
42+
| Present
43+
| criterion for a2ml + k9-svc; zig bench for groove-protocol grv6
44+
|===
45+
46+
All 7 CRG categories are present. Grade C requirements satisfied.
47+
48+
== Gap Analysis: C -> B
49+
50+
Grade B requires all categories to be **robust** (not just present), with consistent pass rates and integration into CI.
51+
52+
[cols="1,1,3", options="header"]
53+
|===
54+
| Requirement | Status | Gap
55+
56+
| All tests run in CI
57+
| Partial
58+
| groove-protocol Zig tests and avow-lib Idris2 tests are not run in CI (toolchains missing from runners)
59+
60+
| Avow protocol tests
61+
| New
62+
| ReScript unit tests for ProvenResult added (8 tests). Idris2 tests exist but are compile-time only. Need CI integration.
63+
64+
| Test count > 200
65+
| Gap
66+
| Currently 160+. Need ~40 more tests across existing suites.
67+
68+
| No `continue-on-error` on quality gates
69+
| Partial
70+
| Several CI steps still use `continue-on-error: true` (YAML lint, markdown lint, secrets scan). These should be enforced.
71+
72+
| Benchmark regressions block CI
73+
| Gap
74+
| Benchmarks exist but are not gated — regressions do not fail the build.
75+
76+
| Fuse3 blocker resolved
77+
| Gap
78+
| repo-guardian-fs cannot compile on Rust stable >= 1.80 due to fuse3 v0.7.3 incompatibility. Offline tests exist as workaround.
79+
80+
| Self-referential dogfooding
81+
| Partial
82+
| hypatia-scan.yml workflow exists but is not regularly triggered. CRG self-assessment now exists (this file).
83+
|===
84+
85+
== Recommended Actions for Grade B
86+
87+
1. Add Zig and Idris2 to CI runners (or use Nix/Guix shells in workflows)
88+
2. Add AVOW protocol `deno task test` to Justfile test suite
89+
3. Write 40+ additional tests: expand axel-protocol coverage, add groove-protocol edge cases, add consent lifecycle tests for avow-lib
90+
4. Remove `continue-on-error` from YAML lint, markdown lint, and secrets scan CI steps
91+
5. Gate benchmark regressions in CI (fail on > 5% regression)
92+
6. Resolve fuse3 dependency (upgrade to v0.9.0 or replace with fuser crate)
93+
7. Schedule hypatia-scan to run weekly and enforce its output
94+
95+
== Recommended Actions for Grade A
96+
97+
Grade A requires **comprehensive** coverage, formal verification, and external audit readiness.
98+
99+
1. All lol/ postulates proven (currently 4 of 9 are provable but unproven)
100+
2. ECHIDNA proof verification running in CI
101+
3. VeriSimDB populated and queryable
102+
4. PanLL compliance dashboard operational
103+
5. External security audit completed
104+
6. All downstream repos at CRG Grade C or above

‎EXPLAINME.adoc‎

Lines changed: 82 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,30 +15,106 @@ See link:README.adoc[] for the full directory map and specification list.
1515

1616
**Caveat:** Standards are prescriptive -- not every downstream repo is fully compliant yet. Enforcement is via CI workflows and Hypatia scanning, not manual audit.
1717

18+
=== Architecture Decisions
19+
20+
[cols="1,3", options="header"]
21+
|===
22+
| Decision | Rationale
23+
24+
| AsciiDoc-first documentation
25+
| AsciiDoc supports semantic structure, cross-references, and conditional output better than Markdown. `.md` is only used for GitHub-required files (SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md).
26+
27+
| Justfile over Makefiles
28+
| `just` provides cross-platform recipes without implicit rules or tab sensitivity. Makefiles are banned org-wide.
29+
30+
| Language policy (CCCP)
31+
| Limits ecosystem fragmentation. Primary: ReScript, Rust, Gleam, Deno. Banned: TypeScript, Go, Python, Java/Kotlin/Swift. Exceptions documented per-repo.
32+
33+
| A2ML over YAML/JSON for metadata
34+
| Machine-readable, versionable, and carries semantic meaning. Each repo declares its state via `.machine_readable/STATE.a2ml`.
35+
36+
| SHA-pinned GitHub Actions
37+
| Prevents supply-chain attacks from mutable tags. All workflows pin actions by commit SHA.
38+
39+
| Guix-first package management
40+
| Reproducible builds. Nix flakes as fallback. No npm/node_modules in production.
41+
|===
42+
1843
=== Evidence
1944

2045
[cols="2,3", options="header"]
2146
|===
2247
| Path | Proves
2348

2449
| `a2ml/`
25-
| A2ML format specification -- the machine-readable metadata format used across all repos
50+
| A2ML format specification -- the machine-readable metadata format used across all repos (47 Rust tests)
2651

27-
| `meta-a2ml/`
28-
| META.a2ml, STATE.a2ml, ECOSYSTEM.a2ml specs and IANA registration drafts
52+
| `meta-a2ml/`, `state-a2ml/`, `ecosystem-a2ml/`
53+
| META, STATE, ECOSYSTEM A2ML specs and IANA registration drafts
2954

3055
| `agentic-a2ml/`
31-
| AGENTIC.a2ml spec -- AI agent interaction patterns
56+
| AGENTIC.a2ml spec -- AI agent interaction patterns with contractile enforcement
57+
58+
| `neurosym-a2ml/`
59+
| NEUROSYM.a2ml spec -- neurosymbolic integration configuration with Nickel schemas
60+
61+
| `playbook-a2ml/`, `anchor-a2ml/`
62+
| PLAYBOOK and ANCHOR A2ML specs -- operational runbooks and intervention protocols
3263

3364
| `contractiles/`
3465
| Contractile system (must/trust/dust/intend/k9) -- policy enforcement primitives
3566

67+
| `k9-svc/`
68+
| K9 self-validating component framework (45 Rust tests, CRG Grade B, deployed on 105+ repos)
69+
70+
| `k9-coordination-protocol/`
71+
| AI agent coordination protocol (79 tests, Phase 1 complete)
72+
3673
| `axel-protocol/`
37-
| Axel protocol specification -- cross-forge automation standard
74+
| Axel protocol specification -- age-gating and explicit enforcement (14 Deno tests, beta)
3875

3976
| `groove-protocol/`
40-
| Groove universal plug-and-play protocol -- inter-service communication
77+
| Groove universal plug-and-play protocol -- inter-service communication (10+ Zig tests, 80% complete)
78+
79+
| `avow-protocol/`
80+
| AVOW consent-attested messaging -- origin attribution and willingness verification (Idris2 + ReScript)
81+
82+
| `consent-aware-http/`
83+
| Multi-protocol AI usage boundaries -- consent headers for HTTP interactions
4184

4285
| `hooks/`
4386
| Pre-commit and CI hooks -- the enforcement layer that makes standards stick
87+
88+
| `.github/workflows/`
89+
| 23 CI/CD workflows -- policy enforcement, quality gates, security scanning, deployment
4490
|===
91+
92+
=== How to Use This Repo
93+
94+
1. **New project?** Copy `.machine_readable/` templates into your repo and fill in the A2ML files.
95+
2. **CI enforcement?** Reference the shared workflows or copy the relevant `.github/workflows/` files.
96+
3. **Language question?** Check the CCCP language policy in `CLAUDE.md` or the `language-policy.yml` workflow.
97+
4. **Building?** Run `just build` (requires Rust, Zig, and Deno). Run `just test` for the full 158+ test suite.
98+
5. **Self-check?** Run `just doctor` to verify your local toolchain, `just heal` to auto-fix common issues.
99+
100+
=== Test Coverage
101+
102+
[cols="2,1,1", options="header"]
103+
|===
104+
| Suite | Technology | Tests
105+
106+
| groove-protocol/reference/ipv6t | Zig | 10+
107+
| 0-ai-gatekeeper-protocol/mcp-repo-guardian | Deno | 36
108+
| axel-protocol | Deno | 14
109+
| a2ml/bindings/rust | Rust | 47
110+
| k9-svc/bindings/rust | Rust | 45
111+
| avow-protocol (ReScript) | Deno | 8
112+
| **Total** | | **160+**
113+
|===
114+
115+
=== Roadmap Phases
116+
117+
* **Phase A (Innervation):** Wire k9 coordination across all repos, replace static 6a2 files with derived STATE.
118+
* **Phase B (Evidence):** Formal proof verification via ECHIDNA, VeriSimDB population, lol/ postulate resolution.
119+
* **Phase C (Visibility):** PanLL dashboard panels, ecosystem health metrics, compliance heatmaps.
120+
* **Phase D (Maturity):** CRG Grade A self-assessment, full dogfooding, external audit readiness.

‎avow-protocol/deno.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
{
22
"tasks": {
3+
"test": "deno run -A npm:rescript && deno test --allow-read src/*_test.bs.js",
34
"build": "deno run -A npm:rescript",
45
"clean": "deno run -A npm:rescript clean",
56
"watch": "deno run -A npm:rescript -w",

‎avow-protocol/src/ProvenResult_test.res‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell
3+
4+
@module("@std/assert") external assertEquals: ('a, 'a) => unit = "assertEquals"
5+
@module("@std/assert") external assertNotEquals: ('a, 'a) => unit = "assertNotEquals"
6+
7+
@val @scope("Deno") external test: (string, unit => unit) => unit = "test"
8+
9+
// --- fromJs tests ---
10+
11+
let () = test("fromJs: ok result with value converts to Ok", () => {
12+
let jsResult: ProvenResult.jsResult<string> = {
13+
ok: true,
14+
value: Some("hello"),
15+
error: None,
16+
}
17+
let result = ProvenResult.fromJs(jsResult)
18+
assertEquals(result, Ok("hello"))
19+
})
20+
21+
let () = test("fromJs: ok result missing value converts to Error", () => {
22+
let jsResult: ProvenResult.jsResult<string> = {
23+
ok: true,
24+
value: None,
25+
error: None,
26+
}
27+
let result = ProvenResult.fromJs(jsResult)
28+
assertEquals(result, Error("Ok result missing value"))
29+
})
30+
31+
let () = test("fromJs: error result with message converts to Error", () => {
32+
let jsResult: ProvenResult.jsResult<string> = {
33+
ok: false,
34+
value: None,
35+
error: Some("parse failed"),
36+
}
37+
let result = ProvenResult.fromJs(jsResult)
38+
assertEquals(result, Error("parse failed"))
39+
})
40+
41+
let () = test("fromJs: error result without message converts to Unknown error", () => {
42+
let jsResult: ProvenResult.jsResult<string> = {
43+
ok: false,
44+
value: None,
45+
error: None,
46+
}
47+
let result = ProvenResult.fromJs(jsResult)
48+
assertEquals(result, Error("Unknown error"))
49+
})
50+
51+
// --- toJs tests ---
52+
53+
let () = test("toJs: Ok value converts to jsResult with ok=true", () => {
54+
let jsResult = ProvenResult.toJs(Ok("world"))
55+
assertEquals(jsResult.ok, true)
56+
assertEquals(jsResult.value, Some("world"))
57+
assertEquals(jsResult.error, None)
58+
})
59+
60+
let () = test("toJs: Error value converts to jsResult with ok=false", () => {
61+
let jsResult = ProvenResult.toJs(Error("bad input"))
62+
assertEquals(jsResult.ok, false)
63+
assertEquals(jsResult.value, None)
64+
assertEquals(jsResult.error, Some("bad input"))
65+
})
66+
67+
// --- round-trip tests ---
68+
69+
let () = test("round-trip: Ok -> toJs -> fromJs preserves value", () => {
70+
let original: result<int, string> = Ok(42)
71+
let roundTripped = original->ProvenResult.toJs->ProvenResult.fromJs
72+
assertEquals(roundTripped, original)
73+
})
74+
75+
let () = test("round-trip: Error -> toJs -> fromJs preserves error", () => {
76+
let original: result<int, string> = Error("not found")
77+
let roundTripped = original->ProvenResult.toJs->ProvenResult.fromJs
78+
assertEquals(roundTripped, original)
79+
})

0 commit comments

Comments
 (0)