From bd0caed0a397ef4a1996d084ddfcf2018b16c7b8 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 07:50:14 +0100 Subject: [PATCH] refactor: migrate repository documentation from Markdown to AsciiDoc --- ARCHITECTURE.adoc | 48 ++ ARCHITECTURE.md | 47 -- CLOSE-OUT.adoc | 50 ++ CLOSE-OUT.md | 43 -- CODE_OF_CONDUCT.adoc | 24 + CODE_OF_CONDUCT.md | 26 - CONTRIBUTING.adoc | 86 ++++ CONTRIBUTING.md | 68 --- GOVERNANCE.adoc | 60 +++ GOVERNANCE.md | 60 --- SECURITY.adoc | 16 + SECURITY.md | 20 - SETUP.adoc | 51 ++ SETUP.md | 47 -- deno/ARCHITECTURE.adoc | 48 ++ deno/ARCHITECTURE.md | 47 -- deno/CHANGELOG.adoc | 9 + deno/CHANGELOG.md | 11 - deno/CODE_OF_CONDUCT.adoc | 24 + deno/CODE_OF_CONDUCT.md | 27 -- deno/CONTRIBUTING.adoc | 71 +++ deno/CONTRIBUTING.md | 66 --- deno/GOVERNANCE.adoc | 60 +++ deno/GOVERNANCE.md | 60 --- deno/PROOF-NEEDS.adoc | 36 ++ deno/PROOF-NEEDS.md | 23 - deno/README.adoc | 115 +++++ deno/README.md | 119 ----- deno/SECURITY.adoc | 16 + deno/SECURITY.md | 20 - deno/TEST-NEEDS.adoc | 66 +++ deno/TEST-NEEDS.md | 52 -- deno/{TOPOLOGY.md => TOPOLOGY.adoc} | 24 +- .../reports/audit/audit-2026-04-15-post.adoc | 28 ++ .../reports/audit/audit-2026-04-15-post.md | 18 - deno/llm-warmup-dev.adoc | 19 + deno/llm-warmup-dev.md | 16 - deno/llm-warmup-user.adoc | 19 + deno/llm-warmup-user.md | 16 - ex/ARCHITECTURE.adoc | 48 ++ ex/ARCHITECTURE.md | 47 -- ex/CHANGELOG.adoc | 54 +++ ex/CHANGELOG.md | 52 -- ex/CODE_OF_CONDUCT.adoc | 24 + ex/CODE_OF_CONDUCT.md | 27 -- ex/CONTRIBUTING.adoc | 71 +++ ex/CONTRIBUTING.md | 66 --- ex/GOVERNANCE.adoc | 60 +++ ex/GOVERNANCE.md | 60 --- ex/README.adoc | 223 +++++++++ ex/README.md | 219 --------- ex/SECURITY.adoc | 67 +++ ex/SECURITY.md | 64 --- ex/TEST-NEEDS.adoc | 67 +++ ex/TEST-NEEDS.md | 49 -- ex/{TOPOLOGY.md => TOPOLOGY.adoc} | 23 +- ex/docs/tech-debt-2026-05-26.adoc | 71 +++ ex/docs/tech-debt-2026-05-26.md | 57 --- ex/llm-warmup-dev.adoc | 19 + ex/llm-warmup-dev.md | 16 - ex/llm-warmup-user.adoc | 19 + ex/llm-warmup-user.md | 16 - gleam/ARCHITECTURE.adoc | 48 ++ gleam/ARCHITECTURE.md | 47 -- gleam/CHANGELOG.adoc | 53 ++ gleam/CHANGELOG.md | 51 -- gleam/CODE_OF_CONDUCT.adoc | 24 + gleam/CODE_OF_CONDUCT.md | 27 -- gleam/CONTRIBUTING.adoc | 71 +++ gleam/CONTRIBUTING.md | 66 --- gleam/GOVERNANCE.adoc | 60 +++ gleam/GOVERNANCE.md | 60 --- gleam/README.adoc | 52 ++ gleam/README.md | 58 --- gleam/SECURITY.adoc | 16 + gleam/SECURITY.md | 17 - gleam/TEST-NEEDS.adoc | 69 +++ gleam/TEST-NEEDS.md | 49 -- gleam/{TOPOLOGY.md => TOPOLOGY.adoc} | 34 +- gleam/docs/tech-debt-2026-05-26.adoc | 71 +++ gleam/docs/tech-debt-2026-05-26.md | 57 --- gleam/llm-warmup-dev.adoc | 19 + gleam/llm-warmup-dev.md | 16 - gleam/llm-warmup-user.adoc | 19 + gleam/llm-warmup-user.md | 16 - haskell/ARCHITECTURE.adoc | 48 ++ haskell/ARCHITECTURE.md | 47 -- haskell/CHANGELOG.adoc | 18 + haskell/CHANGELOG.md | 15 - haskell/CODE_OF_CONDUCT.adoc | 24 + haskell/CODE_OF_CONDUCT.md | 27 -- haskell/CONTRIBUTING.adoc | 71 +++ haskell/CONTRIBUTING.md | 66 --- haskell/GOVERNANCE.adoc | 60 +++ haskell/GOVERNANCE.md | 60 --- haskell/PROOF-NEEDS.adoc | 13 + haskell/PROOF-NEEDS.md | 10 - haskell/README.adoc | 60 +++ haskell/README.md | 70 --- haskell/SECURITY.adoc | 16 + haskell/SECURITY.md | 20 - haskell/TEST-NEEDS.adoc | 64 +++ haskell/TEST-NEEDS.md | 51 -- haskell/{TOPOLOGY.md => TOPOLOGY.adoc} | 23 +- haskell/llm-warmup-dev.adoc | 19 + haskell/llm-warmup-dev.md | 16 - haskell/llm-warmup-user.adoc | 19 + haskell/llm-warmup-user.md | 16 - .../a2ml-estate-normaliser/ARCHITECTURE.adoc | 48 ++ .../a2ml-estate-normaliser/ARCHITECTURE.md | 47 -- .../a2ml-estate-normaliser/GOVERNANCE.adoc | 178 ++----- .../a2ml-estate-normaliser/GOVERNANCE.md | 60 --- .../SOLUTION_SUMMARY.adoc | 178 +++++++ .../SOLUTION_SUMMARY.md | 149 ------ .../tooling/scm2a2ml/A2ML_FIX_SUMMARY.adoc | 115 +++++ members/tooling/scm2a2ml/A2ML_FIX_SUMMARY.md | 100 ---- members/tooling/scm2a2ml/ARCHITECTURE.adoc | 48 ++ members/tooling/scm2a2ml/ARCHITECTURE.md | 47 -- members/tooling/scm2a2ml/CODE_OF_CONDUCT.adoc | 339 +++++++++++++ members/tooling/scm2a2ml/CODE_OF_CONDUCT.md | 327 ------------- members/tooling/scm2a2ml/CONTRIBUTING.adoc | 109 +++++ members/tooling/scm2a2ml/CONTRIBUTING.md | 116 ----- members/tooling/scm2a2ml/GOVERNANCE.adoc | 60 +++ members/tooling/scm2a2ml/GOVERNANCE.md | 60 --- members/tooling/scm2a2ml/SECURITY.adoc | 452 ++++++++++++++++++ members/tooling/scm2a2ml/SECURITY.md | 406 ---------------- members/tooling/vscode-a2ml/ARCHITECTURE.adoc | 48 ++ members/tooling/vscode-a2ml/ARCHITECTURE.md | 47 -- members/tooling/vscode-a2ml/CHANGELOG.adoc | 9 + members/tooling/vscode-a2ml/CHANGELOG.md | 11 - .../tooling/vscode-a2ml/CODE_OF_CONDUCT.adoc | 24 + .../tooling/vscode-a2ml/CODE_OF_CONDUCT.md | 27 -- members/tooling/vscode-a2ml/CONTRIBUTING.adoc | 71 +++ members/tooling/vscode-a2ml/CONTRIBUTING.md | 66 --- members/tooling/vscode-a2ml/GOVERNANCE.adoc | 60 +++ members/tooling/vscode-a2ml/GOVERNANCE.md | 60 --- members/tooling/vscode-a2ml/PROOF-NEEDS.adoc | 12 + members/tooling/vscode-a2ml/PROOF-NEEDS.md | 10 - members/tooling/vscode-a2ml/SECURITY.adoc | 16 + members/tooling/vscode-a2ml/SECURITY.md | 20 - members/tooling/vscode-a2ml/TEST-NEEDS.adoc | 35 ++ members/tooling/vscode-a2ml/TEST-NEEDS.md | 32 -- .../{TOPOLOGY.md => TOPOLOGY.adoc} | 24 +- .../reports/audit/audit-2026-04-15-post.adoc | 39 ++ .../reports/audit/audit-2026-04-15-post.md | 111 ----- .../reports/audit/audit-2026-04-15-pre.adoc | 4 + .../reports/audit/audit-2026-04-15-pre.md | 6 - .../tooling/vscode-a2ml/llm-warmup-dev.adoc | 19 + members/tooling/vscode-a2ml/llm-warmup-dev.md | 16 - .../tooling/vscode-a2ml/llm-warmup-user.adoc | 19 + .../tooling/vscode-a2ml/llm-warmup-user.md | 16 - rs/ARCHITECTURE.adoc | 48 ++ rs/ARCHITECTURE.md | 47 -- rs/CHANGELOG.adoc | 13 + rs/CHANGELOG.md | 14 - rs/CODE_OF_CONDUCT.adoc | 24 + rs/CODE_OF_CONDUCT.md | 27 -- rs/CONTRIBUTING.adoc | 71 +++ rs/CONTRIBUTING.md | 66 --- rs/GOVERNANCE.adoc | 60 +++ rs/GOVERNANCE.md | 60 --- rs/README.adoc | 67 +++ rs/README.md | 73 --- rs/SECURITY.adoc | 16 + rs/SECURITY.md | 20 - rs/TEST-NEEDS.adoc | 85 ++++ rs/TEST-NEEDS.md | 63 --- rs/{TOPOLOGY.md => TOPOLOGY.adoc} | 24 +- rs/llm-warmup-dev.adoc | 19 + rs/llm-warmup-dev.md | 16 - rs/llm-warmup-user.adoc | 19 + rs/llm-warmup-user.md | 16 - showcase/ARCHITECTURE.adoc | 48 ++ showcase/ARCHITECTURE.md | 47 -- showcase/CODE_OF_CONDUCT.adoc | 24 + showcase/CODE_OF_CONDUCT.md | 27 -- showcase/CONTRIBUTING.adoc | 71 +++ showcase/CONTRIBUTING.md | 66 --- showcase/GOVERNANCE.adoc | 60 +++ showcase/GOVERNANCE.md | 60 --- showcase/README.adoc | 21 + showcase/README.md | 27 -- showcase/SECURITY.adoc | 16 + showcase/SECURITY.md | 16 - showcase/TEST-NEEDS.adoc | 183 +++++++ showcase/TEST-NEEDS.md | 136 ------ showcase/TOPOLOGY.adoc | 24 + showcase/TOPOLOGY.md | 23 - .../content/{examples.md => examples.adoc} | 63 +-- showcase/content/getting-started.adoc | 213 +++++++++ showcase/content/getting-started.md | 226 --------- showcase/content/index.adoc | 88 ++++ showcase/content/index.md | 69 --- showcase/content/integrations.adoc | 131 +++++ showcase/content/integrations.md | 145 ------ .../{specification.md => specification.adoc} | 208 ++++---- showcase/llm-warmup-dev.adoc | 19 + showcase/llm-warmup-dev.md | 16 - showcase/llm-warmup-user.adoc | 19 + showcase/llm-warmup-user.md | 16 - showcase/tests/README.adoc | 7 + showcase/tests/README.md | 8 - validate-action/ARCHITECTURE.adoc | 48 ++ validate-action/ARCHITECTURE.md | 47 -- validate-action/CHANGELOG.adoc | 24 + validate-action/CHANGELOG.md | 23 - validate-action/CODE_OF_CONDUCT.adoc | 24 + validate-action/CODE_OF_CONDUCT.md | 27 -- validate-action/CONTRIBUTING.adoc | 71 +++ validate-action/CONTRIBUTING.md | 66 --- validate-action/GOVERNANCE.adoc | 110 ++--- validate-action/GOVERNANCE.md | 60 --- validate-action/PROOF-NEEDS.adoc | 12 + validate-action/PROOF-NEEDS.md | 10 - validate-action/README.adoc | 102 ++++ validate-action/README.md | 93 ---- validate-action/SECURITY.adoc | 16 + validate-action/SECURITY.md | 20 - validate-action/TEST-NEEDS.adoc | 32 ++ validate-action/TEST-NEEDS.md | 33 -- .../{TOPOLOGY.md => TOPOLOGY.adoc} | 23 +- validate-action/llm-warmup-dev.adoc | 19 + validate-action/llm-warmup-dev.md | 16 - validate-action/llm-warmup-user.adoc | 19 + validate-action/llm-warmup-user.md | 16 - 225 files changed, 6222 insertions(+), 6163 deletions(-) create mode 100644 ARCHITECTURE.adoc delete mode 100644 ARCHITECTURE.md create mode 100644 CLOSE-OUT.adoc delete mode 100644 CLOSE-OUT.md create mode 100644 CODE_OF_CONDUCT.adoc delete mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.adoc delete mode 100644 CONTRIBUTING.md create mode 100644 GOVERNANCE.adoc delete mode 100644 GOVERNANCE.md create mode 100644 SECURITY.adoc delete mode 100644 SECURITY.md create mode 100644 SETUP.adoc delete mode 100644 SETUP.md create mode 100644 deno/ARCHITECTURE.adoc delete mode 100644 deno/ARCHITECTURE.md create mode 100644 deno/CHANGELOG.adoc delete mode 100644 deno/CHANGELOG.md create mode 100644 deno/CODE_OF_CONDUCT.adoc delete mode 100644 deno/CODE_OF_CONDUCT.md create mode 100644 deno/CONTRIBUTING.adoc delete mode 100644 deno/CONTRIBUTING.md create mode 100644 deno/GOVERNANCE.adoc delete mode 100644 deno/GOVERNANCE.md create mode 100644 deno/PROOF-NEEDS.adoc delete mode 100644 deno/PROOF-NEEDS.md create mode 100644 deno/README.adoc delete mode 100644 deno/README.md create mode 100644 deno/SECURITY.adoc delete mode 100644 deno/SECURITY.md create mode 100644 deno/TEST-NEEDS.adoc delete mode 100644 deno/TEST-NEEDS.md rename deno/{TOPOLOGY.md => TOPOLOGY.adoc} (64%) create mode 100644 deno/docs/reports/audit/audit-2026-04-15-post.adoc delete mode 100644 deno/docs/reports/audit/audit-2026-04-15-post.md create mode 100644 deno/llm-warmup-dev.adoc delete mode 100644 deno/llm-warmup-dev.md create mode 100644 deno/llm-warmup-user.adoc delete mode 100644 deno/llm-warmup-user.md create mode 100644 ex/ARCHITECTURE.adoc delete mode 100644 ex/ARCHITECTURE.md create mode 100644 ex/CHANGELOG.adoc delete mode 100644 ex/CHANGELOG.md create mode 100644 ex/CODE_OF_CONDUCT.adoc delete mode 100644 ex/CODE_OF_CONDUCT.md create mode 100644 ex/CONTRIBUTING.adoc delete mode 100644 ex/CONTRIBUTING.md create mode 100644 ex/GOVERNANCE.adoc delete mode 100644 ex/GOVERNANCE.md create mode 100644 ex/README.adoc delete mode 100644 ex/README.md create mode 100644 ex/SECURITY.adoc delete mode 100644 ex/SECURITY.md create mode 100644 ex/TEST-NEEDS.adoc delete mode 100644 ex/TEST-NEEDS.md rename ex/{TOPOLOGY.md => TOPOLOGY.adoc} (60%) create mode 100644 ex/docs/tech-debt-2026-05-26.adoc delete mode 100644 ex/docs/tech-debt-2026-05-26.md create mode 100644 ex/llm-warmup-dev.adoc delete mode 100644 ex/llm-warmup-dev.md create mode 100644 ex/llm-warmup-user.adoc delete mode 100644 ex/llm-warmup-user.md create mode 100644 gleam/ARCHITECTURE.adoc delete mode 100644 gleam/ARCHITECTURE.md create mode 100644 gleam/CHANGELOG.adoc delete mode 100644 gleam/CHANGELOG.md create mode 100644 gleam/CODE_OF_CONDUCT.adoc delete mode 100644 gleam/CODE_OF_CONDUCT.md create mode 100644 gleam/CONTRIBUTING.adoc delete mode 100644 gleam/CONTRIBUTING.md create mode 100644 gleam/GOVERNANCE.adoc delete mode 100644 gleam/GOVERNANCE.md create mode 100644 gleam/README.adoc delete mode 100644 gleam/README.md create mode 100644 gleam/SECURITY.adoc delete mode 100644 gleam/SECURITY.md create mode 100644 gleam/TEST-NEEDS.adoc delete mode 100644 gleam/TEST-NEEDS.md rename gleam/{TOPOLOGY.md => TOPOLOGY.adoc} (51%) create mode 100644 gleam/docs/tech-debt-2026-05-26.adoc delete mode 100644 gleam/docs/tech-debt-2026-05-26.md create mode 100644 gleam/llm-warmup-dev.adoc delete mode 100644 gleam/llm-warmup-dev.md create mode 100644 gleam/llm-warmup-user.adoc delete mode 100644 gleam/llm-warmup-user.md create mode 100644 haskell/ARCHITECTURE.adoc delete mode 100644 haskell/ARCHITECTURE.md create mode 100644 haskell/CHANGELOG.adoc delete mode 100644 haskell/CHANGELOG.md create mode 100644 haskell/CODE_OF_CONDUCT.adoc delete mode 100644 haskell/CODE_OF_CONDUCT.md create mode 100644 haskell/CONTRIBUTING.adoc delete mode 100644 haskell/CONTRIBUTING.md create mode 100644 haskell/GOVERNANCE.adoc delete mode 100644 haskell/GOVERNANCE.md create mode 100644 haskell/PROOF-NEEDS.adoc delete mode 100644 haskell/PROOF-NEEDS.md create mode 100644 haskell/README.adoc delete mode 100644 haskell/README.md create mode 100644 haskell/SECURITY.adoc delete mode 100644 haskell/SECURITY.md create mode 100644 haskell/TEST-NEEDS.adoc delete mode 100644 haskell/TEST-NEEDS.md rename haskell/{TOPOLOGY.md => TOPOLOGY.adoc} (56%) create mode 100644 haskell/llm-warmup-dev.adoc delete mode 100644 haskell/llm-warmup-dev.md create mode 100644 haskell/llm-warmup-user.adoc delete mode 100644 haskell/llm-warmup-user.md create mode 100644 members/tooling/a2ml-estate-normaliser/ARCHITECTURE.adoc delete mode 100644 members/tooling/a2ml-estate-normaliser/ARCHITECTURE.md delete mode 100644 members/tooling/a2ml-estate-normaliser/GOVERNANCE.md create mode 100644 members/tooling/a2ml-estate-normaliser/SOLUTION_SUMMARY.adoc delete mode 100644 members/tooling/a2ml-estate-normaliser/SOLUTION_SUMMARY.md create mode 100644 members/tooling/scm2a2ml/A2ML_FIX_SUMMARY.adoc delete mode 100644 members/tooling/scm2a2ml/A2ML_FIX_SUMMARY.md create mode 100644 members/tooling/scm2a2ml/ARCHITECTURE.adoc delete mode 100644 members/tooling/scm2a2ml/ARCHITECTURE.md create mode 100644 members/tooling/scm2a2ml/CODE_OF_CONDUCT.adoc delete mode 100644 members/tooling/scm2a2ml/CODE_OF_CONDUCT.md create mode 100644 members/tooling/scm2a2ml/CONTRIBUTING.adoc delete mode 100644 members/tooling/scm2a2ml/CONTRIBUTING.md create mode 100644 members/tooling/scm2a2ml/GOVERNANCE.adoc delete mode 100644 members/tooling/scm2a2ml/GOVERNANCE.md create mode 100644 members/tooling/scm2a2ml/SECURITY.adoc delete mode 100644 members/tooling/scm2a2ml/SECURITY.md create mode 100644 members/tooling/vscode-a2ml/ARCHITECTURE.adoc delete mode 100644 members/tooling/vscode-a2ml/ARCHITECTURE.md create mode 100644 members/tooling/vscode-a2ml/CHANGELOG.adoc delete mode 100644 members/tooling/vscode-a2ml/CHANGELOG.md create mode 100644 members/tooling/vscode-a2ml/CODE_OF_CONDUCT.adoc delete mode 100644 members/tooling/vscode-a2ml/CODE_OF_CONDUCT.md create mode 100644 members/tooling/vscode-a2ml/CONTRIBUTING.adoc delete mode 100644 members/tooling/vscode-a2ml/CONTRIBUTING.md create mode 100644 members/tooling/vscode-a2ml/GOVERNANCE.adoc delete mode 100644 members/tooling/vscode-a2ml/GOVERNANCE.md create mode 100644 members/tooling/vscode-a2ml/PROOF-NEEDS.adoc delete mode 100644 members/tooling/vscode-a2ml/PROOF-NEEDS.md create mode 100644 members/tooling/vscode-a2ml/SECURITY.adoc delete mode 100644 members/tooling/vscode-a2ml/SECURITY.md create mode 100644 members/tooling/vscode-a2ml/TEST-NEEDS.adoc delete mode 100644 members/tooling/vscode-a2ml/TEST-NEEDS.md rename members/tooling/vscode-a2ml/{TOPOLOGY.md => TOPOLOGY.adoc} (63%) create mode 100644 members/tooling/vscode-a2ml/docs/reports/audit/audit-2026-04-15-post.adoc delete mode 100644 members/tooling/vscode-a2ml/docs/reports/audit/audit-2026-04-15-post.md create mode 100644 members/tooling/vscode-a2ml/docs/reports/audit/audit-2026-04-15-pre.adoc delete mode 100644 members/tooling/vscode-a2ml/docs/reports/audit/audit-2026-04-15-pre.md create mode 100644 members/tooling/vscode-a2ml/llm-warmup-dev.adoc delete mode 100644 members/tooling/vscode-a2ml/llm-warmup-dev.md create mode 100644 members/tooling/vscode-a2ml/llm-warmup-user.adoc delete mode 100644 members/tooling/vscode-a2ml/llm-warmup-user.md create mode 100644 rs/ARCHITECTURE.adoc delete mode 100644 rs/ARCHITECTURE.md create mode 100644 rs/CHANGELOG.adoc delete mode 100644 rs/CHANGELOG.md create mode 100644 rs/CODE_OF_CONDUCT.adoc delete mode 100644 rs/CODE_OF_CONDUCT.md create mode 100644 rs/CONTRIBUTING.adoc delete mode 100644 rs/CONTRIBUTING.md create mode 100644 rs/GOVERNANCE.adoc delete mode 100644 rs/GOVERNANCE.md create mode 100644 rs/README.adoc delete mode 100644 rs/README.md create mode 100644 rs/SECURITY.adoc delete mode 100644 rs/SECURITY.md create mode 100644 rs/TEST-NEEDS.adoc delete mode 100644 rs/TEST-NEEDS.md rename rs/{TOPOLOGY.md => TOPOLOGY.adoc} (62%) create mode 100644 rs/llm-warmup-dev.adoc delete mode 100644 rs/llm-warmup-dev.md create mode 100644 rs/llm-warmup-user.adoc delete mode 100644 rs/llm-warmup-user.md create mode 100644 showcase/ARCHITECTURE.adoc delete mode 100644 showcase/ARCHITECTURE.md create mode 100644 showcase/CODE_OF_CONDUCT.adoc delete mode 100644 showcase/CODE_OF_CONDUCT.md create mode 100644 showcase/CONTRIBUTING.adoc delete mode 100644 showcase/CONTRIBUTING.md create mode 100644 showcase/GOVERNANCE.adoc delete mode 100644 showcase/GOVERNANCE.md create mode 100644 showcase/README.adoc delete mode 100644 showcase/README.md create mode 100644 showcase/SECURITY.adoc delete mode 100644 showcase/SECURITY.md create mode 100644 showcase/TEST-NEEDS.adoc delete mode 100644 showcase/TEST-NEEDS.md create mode 100644 showcase/TOPOLOGY.adoc delete mode 100644 showcase/TOPOLOGY.md rename showcase/content/{examples.md => examples.adoc} (86%) create mode 100644 showcase/content/getting-started.adoc delete mode 100644 showcase/content/getting-started.md create mode 100644 showcase/content/index.adoc delete mode 100644 showcase/content/index.md create mode 100644 showcase/content/integrations.adoc delete mode 100644 showcase/content/integrations.md rename showcase/content/{specification.md => specification.adoc} (52%) create mode 100644 showcase/llm-warmup-dev.adoc delete mode 100644 showcase/llm-warmup-dev.md create mode 100644 showcase/llm-warmup-user.adoc delete mode 100644 showcase/llm-warmup-user.md create mode 100644 showcase/tests/README.adoc delete mode 100644 showcase/tests/README.md create mode 100644 validate-action/ARCHITECTURE.adoc delete mode 100644 validate-action/ARCHITECTURE.md create mode 100644 validate-action/CHANGELOG.adoc delete mode 100644 validate-action/CHANGELOG.md create mode 100644 validate-action/CODE_OF_CONDUCT.adoc delete mode 100644 validate-action/CODE_OF_CONDUCT.md create mode 100644 validate-action/CONTRIBUTING.adoc delete mode 100644 validate-action/CONTRIBUTING.md delete mode 100644 validate-action/GOVERNANCE.md create mode 100644 validate-action/PROOF-NEEDS.adoc delete mode 100644 validate-action/PROOF-NEEDS.md create mode 100644 validate-action/README.adoc delete mode 100644 validate-action/README.md create mode 100644 validate-action/SECURITY.adoc delete mode 100644 validate-action/SECURITY.md create mode 100644 validate-action/TEST-NEEDS.adoc delete mode 100644 validate-action/TEST-NEEDS.md rename validate-action/{TOPOLOGY.md => TOPOLOGY.adoc} (60%) create mode 100644 validate-action/llm-warmup-dev.adoc delete mode 100644 validate-action/llm-warmup-dev.md create mode 100644 validate-action/llm-warmup-user.adoc delete mode 100644 validate-action/llm-warmup-user.md diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CLOSE-OUT.adoc b/CLOSE-OUT.adoc new file mode 100644 index 0000000..218a501 --- /dev/null +++ b/CLOSE-OUT.adoc @@ -0,0 +1,50 @@ +== A2ML Ecosystem — Close-Out + +Decision ledger for the coordination-hub rebuild. + +=== Decided + +* *Shape.* The hub is a coordination hub plus pinned submodules — a +sibling of `+developer-ecosystem+` and a satellite of +`+hyperpolymath/standards+`. +* *Spec home.* The A2ML specification lives in +`+hyperpolymath/standards+` (`+docs/A2ML-SPEC.adoc+`). This hub pins it +by tag; it does not own it. +* *Drift model.* Pin + verify: upstream spec and governance are +referenced by pinned tag and checked in CI, never hard-linked or copied. +* *Members.* 12 members across implementations / tooling / ci / +examples, pinned as submodule gitlinks on `+main+`. +`+contractiles-a2-lab+` is excluded (private) and only cross-referenced. +* *Governance layout.* Machine-readable metadata lives under +`+.machine_readable/+` only; `+0-AI-MANIFEST.a2ml+` is the root entry +point. +* *Conformance verified.* 4 valid + 5 invalid `+.a2ml+` fixtures, +indexed by `+conformance/manifest.a2ml+`: valid validates with 0 errors; +invalid (strict) errors on every case. + +=== Issues (filed) + +* Pin canonical spec in standards + replace TODO-tag — +`+decision, governance+` +* Member rollout: ANCHOR satellite+pin+conformance CI; enable +upstream-pins — `+rollout+` +* Canonical parse-AST (expected.json) + expand conformance corpus — +`+conformance+` +* Governance parity: stamp standard `+.machine_readable+` + +CONTRIBUTING/SECURITY/COC from standards — `+governance+` +* Author tiered dev/maintainer/user docs + concept guides — `+docs+` +* Reference this hub from developer-ecosystem / standards — `+meta+` +* Ratify a2mliser (in) + contractiles-a2-lab (cross-ref) — `+decision+` + +=== Discarded + +* Bundling member sources into the hub (rejected: members stay +independent). +* WSL-specific tooling assumptions (rejected: not portable). +* base64-embedded payloads for fixtures or metadata (rejected: opaque +and unverifiable). + +=== Cleanup + +* After the PR merges, delete the development branch +`+claude/gracious-goodall-4vnq77+`. diff --git a/CLOSE-OUT.md b/CLOSE-OUT.md deleted file mode 100644 index 815091b..0000000 --- a/CLOSE-OUT.md +++ /dev/null @@ -1,43 +0,0 @@ - -# A2ML Ecosystem — Close-Out - -Decision ledger for the coordination-hub rebuild. - -## Decided - -- **Shape.** The hub is a coordination hub plus pinned submodules — a sibling of - `developer-ecosystem` and a satellite of `hyperpolymath/standards`. -- **Spec home.** The A2ML specification lives in `hyperpolymath/standards` - (`docs/A2ML-SPEC.adoc`). This hub pins it by tag; it does not own it. -- **Drift model.** Pin + verify: upstream spec and governance are referenced by - pinned tag and checked in CI, never hard-linked or copied. -- **Members.** 12 members across implementations / tooling / ci / examples, - pinned as submodule gitlinks on `main`. `contractiles-a2-lab` is excluded - (private) and only cross-referenced. -- **Governance layout.** Machine-readable metadata lives under - `.machine_readable/` only; `0-AI-MANIFEST.a2ml` is the root entry point. -- **Conformance verified.** 4 valid + 5 invalid `.a2ml` fixtures, indexed by - `conformance/manifest.a2ml`: valid validates with 0 errors; invalid (strict) - errors on every case. - -## Issues (filed) - -- Pin canonical spec in standards + replace TODO-tag — `decision, governance` -- Member rollout: ANCHOR satellite+pin+conformance CI; enable upstream-pins — `rollout` -- Canonical parse-AST (expected.json) + expand conformance corpus — `conformance` -- Governance parity: stamp standard `.machine_readable` + CONTRIBUTING/SECURITY/COC from standards — `governance` -- Author tiered dev/maintainer/user docs + concept guides — `docs` -- Reference this hub from developer-ecosystem / standards — `meta` -- Ratify a2mliser (in) + contractiles-a2-lab (cross-ref) — `decision` - -## Discarded - -- Bundling member sources into the hub (rejected: members stay independent). -- WSL-specific tooling assumptions (rejected: not portable). -- base64-embedded payloads for fixtures or metadata (rejected: opaque and - unverifiable). - -## Cleanup - -- After the PR merges, delete the development branch - `claude/gracious-goodall-4vnq77`. diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index fb43d83..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,26 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..9097ac5 --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,86 @@ +== Contributing + +Thank you for your interest in contributing! This repository is a +*coordination hub* and a satellite of `+hyperpolymath/standards+`: it +does not own the A2ML specification or governance — those are pinned +from `+standards+` — but it owns the conformance fixtures, the +membership manifest, and the cross-repo drift CI. Human-readable +documentation lives in the root; machine-readable metadata lives under +`+.machine_readable/+`. + +=== How to Contribute + +We welcome contributions in many forms: + +* *Conformance fixtures:* Add or refine cases under +`+conformance/valid/+` and `+conformance/invalid/+` (keep +`+conformance/manifest.a2ml+` in sync). +* *Membership:* Propose member additions/removals via +`+.machine_readable/6a2/ECOSYSTEM.a2ml+`, kept in lockstep with +`+.gitmodules+` and `+scripts/check-membership.sh+`. +* *Drift CI & tooling:* Improve `+.github/workflows/anchor-drift.yml+` +or the helper `+scripts/+`. +* *Documentation:* Enhance the docs or the AI manifest. +* *Bug reports:* File clear, reproducible issues. + +=== Getting Started + +[arabic] +. *Read the AI Manifest:* Start with `+0-AI-MANIFEST.a2ml+` to +understand the repository structure. +. *Initialise members:* Run `+scripts/init-submodules.sh+` to populate +`+members/+` (each member is pinned by commit). +. *Check membership:* Run `+scripts/check-membership.sh+` to verify the +manifest, `+.gitmodules+`, and submodule declarations agree. +. *Validate conformance:* Run the A2ML validator +(`+hyperpolymath/a2ml-validate-action+`) over `+conformance/valid+` +(expect 0 errors) and over `+conformance/invalid+` with strict mode +(every case must error). + +=== Development Workflow + +==== Branch Naming + +.... +docs/short-description # Documentation +test/what-added # Test additions +feat/short-description # New features +fix/issue-number-description # Bug fixes +refactor/what-changed # Code improvements +security/what-fixed # Security fixes +.... + +==== Commit Messages + +We follow https://www.conventionalcommits.org/[Conventional Commits]: + +.... +(): + +[optional body] + +[optional footer] +.... + +Types: `+feat+`, `+fix+`, `+docs+`, `+test+`, `+refactor+`, `+ci+`, +`+chore+`, `+security+` + +=== Reporting Bugs + +Before reporting: 1. Search existing issues 2. Check if it’s already +fixed in `+main+` + +When reporting, include: - Clear, descriptive title - Environment +details (OS, versions, toolchain) - Steps to reproduce - Expected vs +actual behaviour + +=== Code of Conduct + +All contributors are expected to adhere to our +link:CODE_OF_CONDUCT.md[Code of Conduct]. + +=== License + +By contributing, you agree that your contributions will be licensed +under the same licenses as the project: code under MPL-2.0 and +documentation under CC-BY-SA-4.0 (see LICENSE and LICENSES/). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index e9ca169..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,68 +0,0 @@ - -# Contributing - -Thank you for your interest in contributing! This repository is a **coordination hub** and a satellite of `hyperpolymath/standards`: it does not own the A2ML specification or governance — those are pinned from `standards` — but it owns the conformance fixtures, the membership manifest, and the cross-repo drift CI. Human-readable documentation lives in the root; machine-readable metadata lives under `.machine_readable/`. - -## How to Contribute - -We welcome contributions in many forms: - -- **Conformance fixtures:** Add or refine cases under `conformance/valid/` and `conformance/invalid/` (keep `conformance/manifest.a2ml` in sync). -- **Membership:** Propose member additions/removals via `.machine_readable/6a2/ECOSYSTEM.a2ml`, kept in lockstep with `.gitmodules` and `scripts/check-membership.sh`. -- **Drift CI & tooling:** Improve `.github/workflows/anchor-drift.yml` or the helper `scripts/`. -- **Documentation:** Enhance the docs or the AI manifest. -- **Bug reports:** File clear, reproducible issues. - -## Getting Started - -1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` to understand the repository structure. -2. **Initialise members:** Run `scripts/init-submodules.sh` to populate `members/` (each member is pinned by commit). -3. **Check membership:** Run `scripts/check-membership.sh` to verify the manifest, `.gitmodules`, and submodule declarations agree. -4. **Validate conformance:** Run the A2ML validator (`hyperpolymath/a2ml-validate-action`) over `conformance/valid` (expect 0 errors) and over `conformance/invalid` with strict mode (every case must error). - -## Development Workflow - -### Branch Naming - -``` -docs/short-description # Documentation -test/what-added # Test additions -feat/short-description # New features -fix/issue-number-description # Bug fixes -refactor/what-changed # Code improvements -security/what-fixed # Security fixes -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): - -``` -(): - -[optional body] - -[optional footer] -``` - -Types: `feat`, `fix`, `docs`, `test`, `refactor`, `ci`, `chore`, `security` - -## Reporting Bugs - -Before reporting: -1. Search existing issues -2. Check if it's already fixed in `main` - -When reporting, include: -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour - -## Code of Conduct - -All contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). - -## License - -By contributing, you agree that your contributions will be licensed under the same licenses as the project: code under MPL-2.0 and documentation under CC-BY-SA-4.0 (see [LICENSE](LICENSE) and [LICENSES/](LICENSES/)). diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..e47fdd9 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,16 @@ +== Security Policy + +=== Reporting a Vulnerability + +If you discover a security vulnerability, please report it responsibly. + +*Email:* j.d.a.jewell@open.ac.uk + +*Please include:* - Description of the vulnerability - Steps to +reproduce - Potential impact + +*Response timeline:* - Acknowledgement within 48 hours - Initial +assessment within 7 days - Fix or mitigation within 90 days + +*Safe harbour:* We will not pursue legal action against security +researchers who follow responsible disclosure. diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 5c4d5e9..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,20 +0,0 @@ - -# Security Policy - -## Reporting a Vulnerability - -If you discover a security vulnerability, please report it responsibly. - -**Email:** j.d.a.jewell@open.ac.uk - -**Please include:** -- Description of the vulnerability -- Steps to reproduce -- Potential impact - -**Response timeline:** -- Acknowledgement within 48 hours -- Initial assessment within 7 days -- Fix or mitigation within 90 days - -**Safe harbour:** We will not pursue legal action against security researchers who follow responsible disclosure. diff --git a/SETUP.adoc b/SETUP.adoc new file mode 100644 index 0000000..de8f37e --- /dev/null +++ b/SETUP.adoc @@ -0,0 +1,51 @@ +== Setup + +This repository is a coordination hub and satellite of +`+hyperpolymath/standards+`. + +=== Fresh Checkout + +[source,sh] +---- +git clone https://github.com/hyperpolymath/a2ml-ecosystem.git +cd a2ml-ecosystem +git submodule update --init --recursive +---- + +For local estate work, prefer: + +[source,sh] +---- +scripts/init-submodules.sh +scripts/check-membership.sh +---- + +`+scripts/init-submodules.sh+` initializes from sibling local checkouts +when they are present and skips members that are not available in the +local scope. `+scripts/check-membership.sh+` reads +`+.machine_readable/6a2/ECOSYSTEM.a2ml+`. + +=== Machine-Readable Layout + +Coordination metadata lives under `+.machine_readable/+` only: + +* `+.machine_readable/anchors/ANCHOR.a2ml+` — authority anchor and +upstream pins. +* `+.machine_readable/6a2/ECOSYSTEM.a2ml+` — membership manifest. +* `+.machine_readable/6a2/{STATE,META,PLAYBOOK,AGENTIC,NEUROSYM}.a2ml+` +— hub state, ADRs, playbook, and agentic / neuro-symbolic notes. + +`+0-AI-MANIFEST.a2ml+` at the repository root indexes this surface. + +=== Validation + +[source,sh] +---- +# governance: whole repo, strict, ignoring fixtures and members +INPUT_PATH=. INPUT_STRICT=true INPUT_PATHS_IGNORE=$'conformance/\nmembers/' ../a2ml/a2ml-validate-action/validate-a2ml.sh +# conformance positive (zero errors) and negative (every case errors) +INPUT_PATH=conformance/valid INPUT_STRICT=true ../a2ml/a2ml-validate-action/validate-a2ml.sh +INPUT_PATH=conformance/invalid INPUT_STRICT=true ../a2ml/a2ml-validate-action/validate-a2ml.sh +---- + +The invalid conformance command is expected to fail. diff --git a/SETUP.md b/SETUP.md deleted file mode 100644 index 015cc71..0000000 --- a/SETUP.md +++ /dev/null @@ -1,47 +0,0 @@ - -# Setup - -This repository is a coordination hub and satellite of -`hyperpolymath/standards`. - -## Fresh Checkout - -```sh -git clone https://github.com/hyperpolymath/a2ml-ecosystem.git -cd a2ml-ecosystem -git submodule update --init --recursive -``` - -For local estate work, prefer: - -```sh -scripts/init-submodules.sh -scripts/check-membership.sh -``` - -`scripts/init-submodules.sh` initializes from sibling local checkouts when they -are present and skips members that are not available in the local scope. -`scripts/check-membership.sh` reads `.machine_readable/6a2/ECOSYSTEM.a2ml`. - -## Machine-Readable Layout - -Coordination metadata lives under `.machine_readable/` only: - -- `.machine_readable/anchors/ANCHOR.a2ml` — authority anchor and upstream pins. -- `.machine_readable/6a2/ECOSYSTEM.a2ml` — membership manifest. -- `.machine_readable/6a2/{STATE,META,PLAYBOOK,AGENTIC,NEUROSYM}.a2ml` — hub - state, ADRs, playbook, and agentic / neuro-symbolic notes. - -`0-AI-MANIFEST.a2ml` at the repository root indexes this surface. - -## Validation - -```sh -# governance: whole repo, strict, ignoring fixtures and members -INPUT_PATH=. INPUT_STRICT=true INPUT_PATHS_IGNORE=$'conformance/\nmembers/' ../a2ml/a2ml-validate-action/validate-a2ml.sh -# conformance positive (zero errors) and negative (every case errors) -INPUT_PATH=conformance/valid INPUT_STRICT=true ../a2ml/a2ml-validate-action/validate-a2ml.sh -INPUT_PATH=conformance/invalid INPUT_STRICT=true ../a2ml/a2ml-validate-action/validate-a2ml.sh -``` - -The invalid conformance command is expected to fail. diff --git a/deno/ARCHITECTURE.adoc b/deno/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/deno/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/deno/ARCHITECTURE.md b/deno/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/deno/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/deno/CHANGELOG.adoc b/deno/CHANGELOG.adoc new file mode 100644 index 0000000..ca1c652 --- /dev/null +++ b/deno/CHANGELOG.adoc @@ -0,0 +1,9 @@ +== Changelog + +All notable changes to this project will be documented in this file. + +The format is based on https://keepachangelog.com/en/1.1.0/[Keep a +Changelog], and this project adheres to +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] diff --git a/deno/CHANGELOG.md b/deno/CHANGELOG.md deleted file mode 100644 index 8109476..0000000 --- a/deno/CHANGELOG.md +++ /dev/null @@ -1,11 +0,0 @@ -# Changelog - -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - - - - -## [Unreleased] diff --git a/deno/CODE_OF_CONDUCT.adoc b/deno/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/deno/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/deno/CODE_OF_CONDUCT.md b/deno/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/deno/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/deno/CONTRIBUTING.adoc b/deno/CONTRIBUTING.adoc new file mode 100644 index 0000000..dd089ae --- /dev/null +++ b/deno/CONTRIBUTING.adoc @@ -0,0 +1,71 @@ +== Contributing + +Thank you for your interest in contributing! We follow a "`Dual-Track`" +architecture where human-readable documentation lives in the root and +machine-readable policies live in `+.machine_readable/+`. + +=== How to Contribute + +We welcome contributions in many forms: + +* *Code:* Improving the core stack or extensions +* *Documentation:* Enhancing docs or AI manifests +* *Testing:* Adding property-based tests or formal proofs +* *Bug reports:* Filing clear, reproducible issues + +=== Getting Started + +[arabic] +. *Read the AI Manifest:* Start with `+0-AI-MANIFEST.a2ml+` (if present) +to understand the repository structure. +. *Environment:* Use `+guix develop+` or `+direnv allow+` to set up your +tools. +. *Task Runner:* Use `+just+` to see available commands +(`+just --list+`). + +=== Development Workflow + +==== Branch Naming + +.... +docs/short-description # Documentation +test/what-added # Test additions +feat/short-description # New features +fix/issue-number-description # Bug fixes +refactor/what-changed # Code improvements +security/what-fixed # Security fixes +.... + +==== Commit Messages + +We follow https://www.conventionalcommits.org/[Conventional Commits]: + +.... +(): + +[optional body] + +[optional footer] +.... + +Types: `+feat+`, `+fix+`, `+docs+`, `+test+`, `+refactor+`, `+ci+`, +`+chore+`, `+security+` + +=== Reporting Bugs + +Before reporting: 1. Search existing issues 2. Check if it’s already +fixed in `+main+` + +When reporting, include: - Clear, descriptive title - Environment +details (OS, versions, toolchain) - Steps to reproduce - Expected vs +actual behaviour + +=== Code of Conduct + +All contributors are expected to adhere to our +link:CODE_OF_CONDUCT.md[Code of Conduct]. + +=== License + +By contributing, you agree that your contributions will be licensed +under the same license as the project (see LICENSE). diff --git a/deno/CONTRIBUTING.md b/deno/CONTRIBUTING.md deleted file mode 100644 index 90e87dc..0000000 --- a/deno/CONTRIBUTING.md +++ /dev/null @@ -1,66 +0,0 @@ - -# Contributing - -Thank you for your interest in contributing! We follow a "Dual-Track" architecture where human-readable documentation lives in the root and machine-readable policies live in `.machine_readable/`. - -## How to Contribute - -We welcome contributions in many forms: - -- **Code:** Improving the core stack or extensions -- **Documentation:** Enhancing docs or AI manifests -- **Testing:** Adding property-based tests or formal proofs -- **Bug reports:** Filing clear, reproducible issues - -## Getting Started - -1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` (if present) to understand the repository structure. -2. **Environment:** Use `guix develop` or `direnv allow` to set up your tools. -3. **Task Runner:** Use `just` to see available commands (`just --list`). - -## Development Workflow - -### Branch Naming - -``` -docs/short-description # Documentation -test/what-added # Test additions -feat/short-description # New features -fix/issue-number-description # Bug fixes -refactor/what-changed # Code improvements -security/what-fixed # Security fixes -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): - -``` -(): - -[optional body] - -[optional footer] -``` - -Types: `feat`, `fix`, `docs`, `test`, `refactor`, `ci`, `chore`, `security` - -## Reporting Bugs - -Before reporting: -1. Search existing issues -2. Check if it's already fixed in `main` - -When reporting, include: -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour - -## Code of Conduct - -All contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). - -## License - -By contributing, you agree that your contributions will be licensed under the same license as the project (see [LICENSE](LICENSE)). diff --git a/deno/GOVERNANCE.adoc b/deno/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/deno/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/deno/GOVERNANCE.md b/deno/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/deno/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/deno/PROOF-NEEDS.adoc b/deno/PROOF-NEEDS.adoc new file mode 100644 index 0000000..6e59b91 --- /dev/null +++ b/deno/PROOF-NEEDS.adoc @@ -0,0 +1,36 @@ +== Proof Requirements + +=== Current state + +* ABI directory exists (template-level) +* No dangerous patterns found +* 2.2K lines; AffineScript-based A2ML parser with trust-level hierarchy + +=== What needs proving + +* *Trust-level ordering*: Prove the trust hierarchy (Unverified < +Automated < Reviewed < Verified) forms a total order and that +attestation operations never silently upgrade trust level +* *Parser round-trip*: Prove parse-then-render produces semantically +equivalent A2ML (no silent attribute loss) +* *Attestation chain validity*: Prove attestation chains cannot be +forged or reordered without detection + +=== Recommended prover + +* *Idris2* — Trust-level lattice is a natural fit for dependent types +with `+DecEq+` and `+Ord+` proofs + +=== Priority + +* *LOW* — A2ML is a markup format, not safety-critical infrastructure. +However, if attestation trust levels are relied upon by downstream +security decisions (e.g., Hypatia), the trust-level ordering proof +becomes MEDIUM priority. + +=== Template ABI Cleanup (2026-03-29) + +Template ABI removed – was creating false impression of formal +verification. The removed files (Types.idr, Layout.idr, Foreign.idr) +contained only RSR template scaffolding with unresolved +\{\{PROJECT}}/\{\{AUTHOR}} placeholders and no domain-specific proofs. diff --git a/deno/PROOF-NEEDS.md b/deno/PROOF-NEEDS.md deleted file mode 100644 index a4f2ef8..0000000 --- a/deno/PROOF-NEEDS.md +++ /dev/null @@ -1,23 +0,0 @@ -# Proof Requirements - -## Current state -- ABI directory exists (template-level) -- No dangerous patterns found -- 2.2K lines; AffineScript-based A2ML parser with trust-level hierarchy - -## What needs proving -- **Trust-level ordering**: Prove the trust hierarchy (Unverified < Automated < Reviewed < Verified) forms a total order and that attestation operations never silently upgrade trust level -- **Parser round-trip**: Prove parse-then-render produces semantically equivalent A2ML (no silent attribute loss) -- **Attestation chain validity**: Prove attestation chains cannot be forged or reordered without detection - -## Recommended prover -- **Idris2** — Trust-level lattice is a natural fit for dependent types with `DecEq` and `Ord` proofs - -## Priority -- **LOW** — A2ML is a markup format, not safety-critical infrastructure. However, if attestation trust levels are relied upon by downstream security decisions (e.g., Hypatia), the trust-level ordering proof becomes MEDIUM priority. - -## Template ABI Cleanup (2026-03-29) - -Template ABI removed -- was creating false impression of formal verification. -The removed files (Types.idr, Layout.idr, Foreign.idr) contained only RSR template -scaffolding with unresolved {{PROJECT}}/{{AUTHOR}} placeholders and no domain-specific proofs. diff --git a/deno/README.adoc b/deno/README.adoc new file mode 100644 index 0000000..2bc89ea --- /dev/null +++ b/deno/README.adoc @@ -0,0 +1,115 @@ +== Overview + +*Deno-native parser library for A2ML (Attested Markup Language), written +in AffineScript.* + +A2ML is a structured markup language with built-in attestation +provenance, directive metadata, and trust-level tracking. This library +provides a complete parser and renderer for A2ML documents, compiled +from AffineScript to JavaScript ES modules for use with Deno. + +== Features + +* Parse A2ML documents from strings or files +* Render AST back to A2ML surface syntax (round-trip support) +* Typed AST with variant types for blocks, inlines, directives, and +attestations +* Trust-level hierarchy: Unverified, Automated, Reviewed, Verified +* Directive blocks with key-value attributes +* Attestation provenance chain +* Zero dependencies beyond AffineScript standard library + +== Quick Start + +[source,bash] +---- +# Build AffineScript to JS +deno task build + +# Use in your Deno project +deno add jsr:@hyperpolymath/a2ml +---- + +[source,javascript] +---- +import { parse, render, parseErrorToString } from "@hyperpolymath/a2ml"; + +const result = parse("# Hello World\n\nSome **bold** text.\n"); +// result is Ok(document) or Error(parseError) +---- + +== Module Structure + +[width="100%",cols="50%,50%",options="header",] +|=== +|Module |Purpose +|`+A2ML.res+` |Main module — re-exports all public API + +|`+A2ML_Types.res+` |Core data types: document, block, inline, +directive, attestation, trustLevel + +|`+A2ML_Parser.res+` |Line-oriented parser: A2ML text to typed AST + +|`+A2ML_Renderer.res+` |Renderer: typed AST back to A2ML text +|=== + +== A2ML Syntax Reference + +.... +# Heading + +Paragraph with **bold**, *italic*, `code`, [link](url), and @ref(id). + +@directive-name(key=val): single line value + +@multi-line: +Content spanning +multiple lines +@end + +!attest +identity: Jonathan D.A. Jewell +role: author +trust-level: verified +timestamp: 2026-03-16T00:00:00Z +!end + +- Bullet list item +- Another item + +> Block quote text + +```affinescript +let x = 42 +``` +.... + +== Development + +[source,bash] +---- +deno task build # Compile AffineScript +deno task clean # Clean build artifacts +deno task test # Run tests +---- + +== Related Libraries + +* https://github.com/hyperpolymath/a2ml-rs[a2ml-rs] — Rust +implementation +* https://github.com/hyperpolymath/a2ml-haskell[a2ml-haskell] — Haskell +implementation +* https://github.com/hyperpolymath/a2ml_gleam[a2ml_gleam] — Gleam +implementation +* https://github.com/hyperpolymath/tree-sitter-a2ml[tree-sitter-a2ml] — +Tree-sitter grammar +* https://github.com/hyperpolymath/vscode-a2ml[vscode-a2ml] — VS Code +extension + +== License + +SPDX-License-Identifier: CC-BY-SA-4.0 + +Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) + +See LICENSE for details. diff --git a/deno/README.md b/deno/README.md deleted file mode 100644 index 592c830..0000000 --- a/deno/README.md +++ /dev/null @@ -1,119 +0,0 @@ - - -# Overview - -**Deno-native parser library for A2ML (Attested Markup Language), -written in AffineScript.** - -A2ML is a structured markup language with built-in attestation -provenance, directive metadata, and trust-level tracking. This library -provides a complete parser and renderer for A2ML documents, compiled -from AffineScript to JavaScript ES modules for use with Deno. - -# Features - -- Parse A2ML documents from strings or files - -- Render AST back to A2ML surface syntax (round-trip support) - -- Typed AST with variant types for blocks, inlines, directives, and - attestations - -- Trust-level hierarchy: Unverified, Automated, Reviewed, Verified - -- Directive blocks with key-value attributes - -- Attestation provenance chain - -- Zero dependencies beyond AffineScript standard library - -# Quick Start - -```bash -# Build AffineScript to JS -deno task build - -# Use in your Deno project -deno add jsr:@hyperpolymath/a2ml -``` - -```javascript -import { parse, render, parseErrorToString } from "@hyperpolymath/a2ml"; - -const result = parse("# Hello World\n\nSome **bold** text.\n"); -// result is Ok(document) or Error(parseError) -``` - -# Module Structure - -| Module | Purpose | -|----|----| -| `A2ML.res` | Main module — re-exports all public API | -| `A2ML_Types.res` | Core data types: document, block, inline, directive, attestation, trustLevel | -| `A2ML_Parser.res` | Line-oriented parser: A2ML text to typed AST | -| `A2ML_Renderer.res` | Renderer: typed AST back to A2ML text | - -# A2ML Syntax Reference - - # Heading - - Paragraph with **bold**, *italic*, `code`, [link](url), and @ref(id). - - @directive-name(key=val): single line value - - @multi-line: - Content spanning - multiple lines - @end - - !attest - identity: Jonathan D.A. Jewell - role: author - trust-level: verified - timestamp: 2026-03-16T00:00:00Z - !end - - - Bullet list item - - Another item - - > Block quote text - - ```affinescript - let x = 42 - ``` - -# Development - -```bash -deno task build # Compile AffineScript -deno task clean # Clean build artifacts -deno task test # Run tests -``` - -# Related Libraries - -- [a2ml-rs](https://github.com/hyperpolymath/a2ml-rs) — Rust - implementation - -- [a2ml-haskell](https://github.com/hyperpolymath/a2ml-haskell) — - Haskell implementation - -- [a2ml_gleam](https://github.com/hyperpolymath/a2ml_gleam) — Gleam - implementation - -- [tree-sitter-a2ml](https://github.com/hyperpolymath/tree-sitter-a2ml) - — Tree-sitter grammar - -- [vscode-a2ml](https://github.com/hyperpolymath/vscode-a2ml) — VS Code - extension - -# License - -SPDX-License-Identifier: CC-BY-SA-4.0 - -Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) - -See [LICENSE](LICENSE) for details. diff --git a/deno/SECURITY.adoc b/deno/SECURITY.adoc new file mode 100644 index 0000000..e47fdd9 --- /dev/null +++ b/deno/SECURITY.adoc @@ -0,0 +1,16 @@ +== Security Policy + +=== Reporting a Vulnerability + +If you discover a security vulnerability, please report it responsibly. + +*Email:* j.d.a.jewell@open.ac.uk + +*Please include:* - Description of the vulnerability - Steps to +reproduce - Potential impact + +*Response timeline:* - Acknowledgement within 48 hours - Initial +assessment within 7 days - Fix or mitigation within 90 days + +*Safe harbour:* We will not pursue legal action against security +researchers who follow responsible disclosure. diff --git a/deno/SECURITY.md b/deno/SECURITY.md deleted file mode 100644 index 5c4d5e9..0000000 --- a/deno/SECURITY.md +++ /dev/null @@ -1,20 +0,0 @@ - -# Security Policy - -## Reporting a Vulnerability - -If you discover a security vulnerability, please report it responsibly. - -**Email:** j.d.a.jewell@open.ac.uk - -**Please include:** -- Description of the vulnerability -- Steps to reproduce -- Potential impact - -**Response timeline:** -- Acknowledgement within 48 hours -- Initial assessment within 7 days -- Fix or mitigation within 90 days - -**Safe harbour:** We will not pursue legal action against security researchers who follow responsible disclosure. diff --git a/deno/TEST-NEEDS.adoc b/deno/TEST-NEEDS.adoc new file mode 100644 index 0000000..12f7d02 --- /dev/null +++ b/deno/TEST-NEEDS.adoc @@ -0,0 +1,66 @@ +== Test & Benchmark Requirements + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current State + +* Unit tests: NONE (no Deno/AffineScript test files found) +* Integration tests: 1 Zig integration test (ABI/FFI template) +* E2E tests: NONE +* Benchmarks: NONE (benchmark dir has only README placeholder) +* panic-attack scan: NEVER RUN (feature dir exists but no report) + +=== What’s Missing + +==== Point-to-Point (P2P) + +* A2ML.res — no tests +* A2ML_Types.res — no tests +* A2ML_Parser.res — no tests +* A2ML_Renderer.res — no tests +* Zig FFI main.zig — only template integration test +* Idris2 ABI definitions (Types.idr, Layout.idr, Foreign.idr) — no +verification tests + +==== End-to-End (E2E) + +* Parse A2ML document and verify output — not tested +* Render A2ML to output format — not tested +* Round-trip (parse then render) fidelity — not tested +* Error handling for malformed A2ML — not tested +* Deno runtime integration — not tested + +==== Aspect Tests + +* [ ] Security (input sanitisation for untrusted A2ML documents) +* [ ] Performance (parsing large A2ML documents) +* [ ] Concurrency (N/A for parser library) +* [ ] Error handling (malformed input, missing fields, invalid trust +levels) +* [ ] Accessibility (N/A) + +==== Build & Execution + +* [ ] deno check — not verified +* [ ] deno test — not verified +* [ ] AffineScript build — not verified +* [ ] Zig build — not verified +* [ ] Self-diagnostic — none + +==== Benchmarks Needed + +* Parse throughput vs a2ml-rs and a2ml_ex implementations +* Memory usage on large documents +* Zig FFI call overhead measurement + +==== Self-Tests + +* [ ] panic-attack assail on own repo +* [ ] Built-in doctor/check command (if applicable) + +=== Priority + +* *HIGH* — A2ML is a critical format in the ecosystem. 4 AffineScript +source files + 3 Idris2 ABI + 2 Zig FFI files with ZERO functional +tests. The fuzz directory contains only a placeholder.txt. As a library +consumed by other projects, this needs comprehensive tests. diff --git a/deno/TEST-NEEDS.md b/deno/TEST-NEEDS.md deleted file mode 100644 index 7154b2f..0000000 --- a/deno/TEST-NEEDS.md +++ /dev/null @@ -1,52 +0,0 @@ -# Test & Benchmark Requirements - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current State -- Unit tests: NONE (no Deno/AffineScript test files found) -- Integration tests: 1 Zig integration test (ABI/FFI template) -- E2E tests: NONE -- Benchmarks: NONE (benchmark dir has only README placeholder) -- panic-attack scan: NEVER RUN (feature dir exists but no report) - -## What's Missing -### Point-to-Point (P2P) -- A2ML.res — no tests -- A2ML_Types.res — no tests -- A2ML_Parser.res — no tests -- A2ML_Renderer.res — no tests -- Zig FFI main.zig — only template integration test -- Idris2 ABI definitions (Types.idr, Layout.idr, Foreign.idr) — no verification tests - -### End-to-End (E2E) -- Parse A2ML document and verify output — not tested -- Render A2ML to output format — not tested -- Round-trip (parse then render) fidelity — not tested -- Error handling for malformed A2ML — not tested -- Deno runtime integration — not tested - -### Aspect Tests -- [ ] Security (input sanitisation for untrusted A2ML documents) -- [ ] Performance (parsing large A2ML documents) -- [ ] Concurrency (N/A for parser library) -- [ ] Error handling (malformed input, missing fields, invalid trust levels) -- [ ] Accessibility (N/A) - -### Build & Execution -- [ ] deno check — not verified -- [ ] deno test — not verified -- [ ] AffineScript build — not verified -- [ ] Zig build — not verified -- [ ] Self-diagnostic — none - -### Benchmarks Needed -- Parse throughput vs a2ml-rs and a2ml_ex implementations -- Memory usage on large documents -- Zig FFI call overhead measurement - -### Self-Tests -- [ ] panic-attack assail on own repo -- [ ] Built-in doctor/check command (if applicable) - -## Priority -- **HIGH** — A2ML is a critical format in the ecosystem. 4 AffineScript source files + 3 Idris2 ABI + 2 Zig FFI files with ZERO functional tests. The fuzz directory contains only a placeholder.txt. As a library consumed by other projects, this needs comprehensive tests. diff --git a/deno/TOPOLOGY.md b/deno/TOPOLOGY.adoc similarity index 64% rename from deno/TOPOLOGY.md rename to deno/TOPOLOGY.adoc index edd533e..eab6d21 100644 --- a/deno/TOPOLOGY.md +++ b/deno/TOPOLOGY.adoc @@ -1,14 +1,16 @@ - - -# TOPOLOGY.md — a2ml-deno +== TOPOLOGY.md — a2ml-deno -## Purpose +=== Purpose -Deno-native parser and renderer for A2ML (Attested Markup Language), written in AffineScript and compiled to JavaScript ES modules. Provides parse-render round-trip support for A2ML documents with trust-level hierarchy and directive blocks. Consumed by Deno runtimes and published to JSR. +Deno-native parser and renderer for A2ML (Attested Markup Language), +written in AffineScript and compiled to JavaScript ES modules. Provides +parse-render round-trip support for A2ML documents with trust-level +hierarchy and directive blocks. Consumed by Deno runtimes and published +to JSR. -## Module Map +=== Module Map -``` +.... a2ml-deno/ ├── src/ │ ├── A2ML.res # Main public API @@ -20,12 +22,12 @@ a2ml-deno/ ├── deno.json # Deno module config ├── jsr.json # JSR publication config └── container/ # Containerfile for CI -``` +.... -## Data Flow +=== Data Flow -``` +.... [A2ML text] ──► [A2ML_Parser] ──► [Typed AST] ──► [A2ML_Renderer] ──► [A2ML text] │ [A2ML_Types] -``` +.... diff --git a/deno/docs/reports/audit/audit-2026-04-15-post.adoc b/deno/docs/reports/audit/audit-2026-04-15-post.adoc new file mode 100644 index 0000000..8fe48c8 --- /dev/null +++ b/deno/docs/reports/audit/audit-2026-04-15-post.adoc @@ -0,0 +1,28 @@ +== Post-audit Status Report: a2ml-deno + +* *Date:* 2026-04-15 +* *Status:* Complete (M5 Sweep) +* *Repo:* /var/mnt/eclipse/repos/a2ml-deno + +=== Actions Taken + +[arabic] +. Standard CI/Workflow Sweep: Added blocker workflows +(`+ts-blocker.yml+`, `+npm-bun-blocker.yml+`) and updated `+Justfile+`. +. SCM-to-A2ML Migration: Staged and committed deletions of legacy +`+.scm+` files. +. Lockfile Sweep: Generated and tracked missing lockfiles where +manifests were present. +. Static Analysis: Verified with `+panic-attack assail+`. + +=== Findings Summary + +* 14 TODO/FIXME/HACK markers in +.machine_readable/contractiles/k9/template-hunt.k9.ncl +* flake.guix declares inputs without narHash, rev pinning, or sibling +flake.lock — dependency revision is unpinned in flake.guix +* 8 unsafe get calls in src/A2ML_Parser.res + +=== Final Grade + +* *CRG Grade:* D (Promoted from E/X) - CI and lockfiles are in place. diff --git a/deno/docs/reports/audit/audit-2026-04-15-post.md b/deno/docs/reports/audit/audit-2026-04-15-post.md deleted file mode 100644 index 4a41bb5..0000000 --- a/deno/docs/reports/audit/audit-2026-04-15-post.md +++ /dev/null @@ -1,18 +0,0 @@ -# Post-audit Status Report: a2ml-deno -- **Date:** 2026-04-15 -- **Status:** Complete (M5 Sweep) -- **Repo:** /var/mnt/eclipse/repos/a2ml-deno - -## Actions Taken -1. Standard CI/Workflow Sweep: Added blocker workflows (`ts-blocker.yml`, `npm-bun-blocker.yml`) and updated `Justfile`. -2. SCM-to-A2ML Migration: Staged and committed deletions of legacy `.scm` files. -3. Lockfile Sweep: Generated and tracked missing lockfiles where manifests were present. -4. Static Analysis: Verified with `panic-attack assail`. - -## Findings Summary -- 14 TODO/FIXME/HACK markers in .machine_readable/contractiles/k9/template-hunt.k9.ncl -- flake.guix declares inputs without narHash, rev pinning, or sibling flake.lock — dependency revision is unpinned in flake.guix -- 8 unsafe get calls in src/A2ML_Parser.res - -## Final Grade -- **CRG Grade:** D (Promoted from E/X) - CI and lockfiles are in place. diff --git a/deno/llm-warmup-dev.adoc b/deno/llm-warmup-dev.adoc new file mode 100644 index 0000000..68c0efd --- /dev/null +++ b/deno/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — a2ml-deno (Developer) + +=== What is a2ml-deno? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/deno/llm-warmup-dev.md b/deno/llm-warmup-dev.md deleted file mode 100644 index 0c32ade..0000000 --- a/deno/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — a2ml-deno (Developer) - -## What is a2ml-deno? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/deno/llm-warmup-user.adoc b/deno/llm-warmup-user.adoc new file mode 100644 index 0000000..fb24c3d --- /dev/null +++ b/deno/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — a2ml-deno (User) + +=== What is a2ml-deno? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/deno/llm-warmup-user.md b/deno/llm-warmup-user.md deleted file mode 100644 index 1ce93a5..0000000 --- a/deno/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — a2ml-deno (User) - -## What is a2ml-deno? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/ex/ARCHITECTURE.adoc b/ex/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ex/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ex/ARCHITECTURE.md b/ex/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ex/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/ex/CHANGELOG.adoc b/ex/CHANGELOG.adoc new file mode 100644 index 0000000..eb2787c --- /dev/null +++ b/ex/CHANGELOG.adoc @@ -0,0 +1,54 @@ +== Changelog + +All notable changes to `+a2ml_ex+` will be documented in this file. + +This file is generated from conventional commits by the +https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`] +workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this +repo’s CI to keep this file in sync automatically — see +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`] +for the canonical config. + +The format follows https://keepachangelog.com/en/1.1.0/[Keep a +Changelog]; this project aims to follow +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Added + +* feat(crg): add crg-grade and crg-badge justfile recipes +* feat: add stapeln.toml container definition +* feat: add UX Justfile with doctor, tour, help-me, assail recipes +* feat: deploy UX Manifesto infrastructure + +==== Fixed + +* fix(ci): sync hypatia-scan.yml to canonical (kill cd-scanner build +drift) (#9) +* fix(ci): adopt canonical hypatia-scan.yml (env.HOME/scanner-layout + +Comment-step gate) (#8) +* fix(scorecard): enforce granular permissions and add fuzzing +placeholder + +==== Documentation + +* docs: add TOPOLOGY.md +* docs: substantive CRG C annotation (EXPLAINME.adoc) +* docs: add TEST-NEEDS.md and/or PROOF-NEEDS.md from audit +* docs: add SECURITY.md and OpenSSF badge for compliance +* docs: add EXPLAINME.adoc — prove-it file backing README claims + +==== CI + +* ci: deploy dogfood-gate, add Groove manifest and CRG tests + +=== Pre-history + +Prior commits to this file’s introduction are recorded in git history +but not formally classified into Keep-a-Changelog sections. To backfill, +run `+git cliff -o CHANGELOG.md+` locally using the canonical +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`] +— this is one-shot mechanical work. + +''''' diff --git a/ex/CHANGELOG.md b/ex/CHANGELOG.md deleted file mode 100644 index 7fd7ea5..0000000 --- a/ex/CHANGELOG.md +++ /dev/null @@ -1,52 +0,0 @@ - - -# Changelog - -All notable changes to `a2ml_ex` will be documented in this file. - -This file is generated from conventional commits by the -[`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml) -workflow (`hyperpolymath/standards#206`). Adopt the workflow in this repo's CI to keep this file in sync automatically — see -[`templates/cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) -for the canonical config. - -The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); -this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added - -- feat(crg): add crg-grade and crg-badge justfile recipes -- feat: add stapeln.toml container definition -- feat: add UX Justfile with doctor, tour, help-me, assail recipes -- feat: deploy UX Manifesto infrastructure - -### Fixed - -- fix(ci): sync hypatia-scan.yml to canonical (kill cd-scanner build drift) (#9) -- fix(ci): adopt canonical hypatia-scan.yml (env.HOME/scanner-layout + Comment-step gate) (#8) -- fix(scorecard): enforce granular permissions and add fuzzing placeholder - -### Documentation - -- docs: add TOPOLOGY.md -- docs: substantive CRG C annotation (EXPLAINME.adoc) -- docs: add TEST-NEEDS.md and/or PROOF-NEEDS.md from audit -- docs: add SECURITY.md and OpenSSF badge for compliance -- docs: add EXPLAINME.adoc — prove-it file backing README claims - -### CI - -- ci: deploy dogfood-gate, add Groove manifest and CRG tests - -## Pre-history - -Prior commits to this file's introduction are recorded in git history but not formally classified into Keep-a-Changelog sections. To backfill, run `git cliff -o CHANGELOG.md` locally using the canonical [`cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) — this is one-shot mechanical work. - ---- - - diff --git a/ex/CODE_OF_CONDUCT.adoc b/ex/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/ex/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/ex/CODE_OF_CONDUCT.md b/ex/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/ex/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/ex/CONTRIBUTING.adoc b/ex/CONTRIBUTING.adoc new file mode 100644 index 0000000..dd089ae --- /dev/null +++ b/ex/CONTRIBUTING.adoc @@ -0,0 +1,71 @@ +== Contributing + +Thank you for your interest in contributing! We follow a "`Dual-Track`" +architecture where human-readable documentation lives in the root and +machine-readable policies live in `+.machine_readable/+`. + +=== How to Contribute + +We welcome contributions in many forms: + +* *Code:* Improving the core stack or extensions +* *Documentation:* Enhancing docs or AI manifests +* *Testing:* Adding property-based tests or formal proofs +* *Bug reports:* Filing clear, reproducible issues + +=== Getting Started + +[arabic] +. *Read the AI Manifest:* Start with `+0-AI-MANIFEST.a2ml+` (if present) +to understand the repository structure. +. *Environment:* Use `+guix develop+` or `+direnv allow+` to set up your +tools. +. *Task Runner:* Use `+just+` to see available commands +(`+just --list+`). + +=== Development Workflow + +==== Branch Naming + +.... +docs/short-description # Documentation +test/what-added # Test additions +feat/short-description # New features +fix/issue-number-description # Bug fixes +refactor/what-changed # Code improvements +security/what-fixed # Security fixes +.... + +==== Commit Messages + +We follow https://www.conventionalcommits.org/[Conventional Commits]: + +.... +(): + +[optional body] + +[optional footer] +.... + +Types: `+feat+`, `+fix+`, `+docs+`, `+test+`, `+refactor+`, `+ci+`, +`+chore+`, `+security+` + +=== Reporting Bugs + +Before reporting: 1. Search existing issues 2. Check if it’s already +fixed in `+main+` + +When reporting, include: - Clear, descriptive title - Environment +details (OS, versions, toolchain) - Steps to reproduce - Expected vs +actual behaviour + +=== Code of Conduct + +All contributors are expected to adhere to our +link:CODE_OF_CONDUCT.md[Code of Conduct]. + +=== License + +By contributing, you agree that your contributions will be licensed +under the same license as the project (see LICENSE). diff --git a/ex/CONTRIBUTING.md b/ex/CONTRIBUTING.md deleted file mode 100644 index 90e87dc..0000000 --- a/ex/CONTRIBUTING.md +++ /dev/null @@ -1,66 +0,0 @@ - -# Contributing - -Thank you for your interest in contributing! We follow a "Dual-Track" architecture where human-readable documentation lives in the root and machine-readable policies live in `.machine_readable/`. - -## How to Contribute - -We welcome contributions in many forms: - -- **Code:** Improving the core stack or extensions -- **Documentation:** Enhancing docs or AI manifests -- **Testing:** Adding property-based tests or formal proofs -- **Bug reports:** Filing clear, reproducible issues - -## Getting Started - -1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` (if present) to understand the repository structure. -2. **Environment:** Use `guix develop` or `direnv allow` to set up your tools. -3. **Task Runner:** Use `just` to see available commands (`just --list`). - -## Development Workflow - -### Branch Naming - -``` -docs/short-description # Documentation -test/what-added # Test additions -feat/short-description # New features -fix/issue-number-description # Bug fixes -refactor/what-changed # Code improvements -security/what-fixed # Security fixes -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): - -``` -(): - -[optional body] - -[optional footer] -``` - -Types: `feat`, `fix`, `docs`, `test`, `refactor`, `ci`, `chore`, `security` - -## Reporting Bugs - -Before reporting: -1. Search existing issues -2. Check if it's already fixed in `main` - -When reporting, include: -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour - -## Code of Conduct - -All contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). - -## License - -By contributing, you agree that your contributions will be licensed under the same license as the project (see [LICENSE](LICENSE)). diff --git a/ex/GOVERNANCE.adoc b/ex/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/ex/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/ex/GOVERNANCE.md b/ex/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/ex/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/ex/README.adoc b/ex/README.adoc new file mode 100644 index 0000000..4a47018 --- /dev/null +++ b/ex/README.adoc @@ -0,0 +1,223 @@ +https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/a2ml_ex[image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity[OpenSSF +Best Practices]] + +== Overview + +*Elixir implementation of A2ML (Attested Markup Language) parser and +renderer.* + +A2ML is a structured markup language with built-in attestation +provenance, directive metadata, and trust-level tracking. This library +provides a complete parser and renderer for A2ML documents in pure +Elixir. + +== Features + +* Parse A2ML documents from strings or files +* Render AST back to A2ML surface syntax (round-trip support) +* Typed AST with structs for blocks, inlines, directives, and +attestations +* Trust-level hierarchy: `+:unverified+`, `+:automated+`, `+:reviewed+`, +`+:verified+` +* Directive blocks with key-value attributes +* Attestation provenance chain +* Zero dependencies beyond Elixir standard library + +== Quick Start + +Add to your `+mix.exs+`: + +[source,elixir] +---- +defp deps do + [{:a2ml_ex, git: "https://github.com/hyperpolymath/a2ml_ex.git"}] +end +---- + +Then run: + +[source,bash] +---- +mix deps.get +mix compile +---- + +== Usage + +[source,elixir] +---- +# Parse A2ML document +{:ok, document} = A2ML.parse("# Hello World\n\nSome **bold** text.") + +# Render back to A2ML +{:ok, rendered} = A2ML.render(document) + +# Handle parse errors +{:error, %A2ML.ParseError{}} = A2ML.parse("invalid syntax") +---- + +== Module Structure + +[width="100%",cols="50%,50%",options="header",] +|=== +|Module |Purpose +|`+A2ML+` |Main module - re-exports public API + +|`+A2ML.Document+` |Document struct and functions + +|`+A2ML.Block+` |Block-level elements (headings, paragraphs, lists, +etc.) + +|`+A2ML.Inline+` |Inline elements (bold, italic, code, links, etc.) + +|`+A2ML.Directive+` |Directive blocks with attributes + +|`+A2ML.Attestation+` |Attestation provenance and trust levels + +|`+A2ML.Parser+` |Parser implementation (string to AST) + +|`+A2ML.Renderer+` |Renderer implementation (AST to string) + +|`+A2ML.Error+` |Error types and handling +|=== + +== A2ML Syntax Reference + +.... +# Heading + +Paragraph with **bold**, *italic*, `code`, [link](url), and @ref(id). + +@directive-name(key=val): single line value + +@multi-line: +Content spanning +multiple lines +@end + +!attest +identity: Jonathan D.A. Jewell +role: author +trust-level: verified +timestamp: 2026-03-16T00:00:00Z +!end + +- Bullet list item +- Another item + +> Block quote text + +```elixir +defmodule Example do + def hello, do: "world" +end +``` +.... + +== Development + +[source,bash] +---- +mix deps.get # Install dependencies +mix compile # Compile project +mix test # Run tests +mix format # Format code +mix creds check # Check credentials +---- + +== Configuration + +Add to `+config/config.exs+`: + +[source,elixir] +---- +config :a2ml_ex, + default_trust_level: :reviewed, + strict_mode: true +---- + +== Related Libraries + +* https://github.com/hyperpolymath/a2ml-deno[a2ml-deno] — +Deno/AffineScript implementation +* https://github.com/hyperpolymath/a2ml-rs[a2ml-rs] — Rust +implementation +* https://github.com/hyperpolymath/a2ml-haskell[a2ml-haskell] — Haskell +implementation +* https://github.com/hyperpolymath/a2ml_gleam[a2ml_gleam] — Gleam +implementation +* https://github.com/hyperpolymath/tree-sitter-a2ml[tree-sitter-a2ml] — +Tree-sitter grammar +* https://github.com/hyperpolymath/vscode-a2ml[vscode-a2ml] — VS Code +extension + +== Trust Levels + +A2ML supports four trust levels in a hierarchy: + +[width="100%",cols="21%,79%",options="header",] +|=== +|Level |Meaning +|`+:unverified+` |Content has not been reviewed or attested +|`+:automated+` |Content generated or verified by automated systems +|`+:reviewed+` |Content reviewed by human but not formally verified +|`+:verified+` |Content formally verified with cryptographic attestation +|=== + +== Directives + +Directives provide metadata and processing instructions: + +.... +@page-break + +@toc(depth=3): Table of Contents + +@include(file="chapter1.a2ml"): + +@template(name="article"): +# {title} +By {author} + +{content} +@end +.... + +== Attestations + +Attestations provide cryptographic provenance: + +.... +!attest +identity: Alice Smith +role: Editor +trust-level: verified +timestamp: 2026-03-16T12:00:00Z +signature: 0xabc123... +!end +.... + +== Performance + +The Elixir implementation is optimized for: + +* Fast parsing of large documents +* Memory-efficient AST representation +* Concurrent rendering capabilities +* Stream processing support + +== License + +SPDX-License-Identifier: CC-BY-SA-4.0 + +Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) + +See LICENSE for full license text. + +== Contributing + +See CONTRIBUTING for contribution guidelines. + +== Roadmap + +See ROADMAP for planned features and enhancements. diff --git a/ex/README.md b/ex/README.md deleted file mode 100644 index e8d34c3..0000000 --- a/ex/README.md +++ /dev/null @@ -1,219 +0,0 @@ - - -[![OpenSSF Best Practices](https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity)](https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/a2ml_ex) - -# Overview - -**Elixir implementation of A2ML (Attested Markup Language) parser and -renderer.** - -A2ML is a structured markup language with built-in attestation -provenance, directive metadata, and trust-level tracking. This library -provides a complete parser and renderer for A2ML documents in pure -Elixir. - -# Features - -- Parse A2ML documents from strings or files - -- Render AST back to A2ML surface syntax (round-trip support) - -- Typed AST with structs for blocks, inlines, directives, and - attestations - -- Trust-level hierarchy: `:unverified`, `:automated`, `:reviewed`, - `:verified` - -- Directive blocks with key-value attributes - -- Attestation provenance chain - -- Zero dependencies beyond Elixir standard library - -# Quick Start - -Add to your `mix.exs`: - -```elixir -defp deps do - [{:a2ml_ex, git: "https://github.com/hyperpolymath/a2ml_ex.git"}] -end -``` - -Then run: - -```bash -mix deps.get -mix compile -``` - -# Usage - -```elixir -# Parse A2ML document -{:ok, document} = A2ML.parse("# Hello World\n\nSome **bold** text.") - -# Render back to A2ML -{:ok, rendered} = A2ML.render(document) - -# Handle parse errors -{:error, %A2ML.ParseError{}} = A2ML.parse("invalid syntax") -``` - -# Module Structure - -| Module | Purpose | -|----|----| -| `A2ML` | Main module - re-exports public API | -| `A2ML.Document` | Document struct and functions | -| `A2ML.Block` | Block-level elements (headings, paragraphs, lists, etc.) | -| `A2ML.Inline` | Inline elements (bold, italic, code, links, etc.) | -| `A2ML.Directive` | Directive blocks with attributes | -| `A2ML.Attestation` | Attestation provenance and trust levels | -| `A2ML.Parser` | Parser implementation (string to AST) | -| `A2ML.Renderer` | Renderer implementation (AST to string) | -| `A2ML.Error` | Error types and handling | - -# A2ML Syntax Reference - - # Heading - - Paragraph with **bold**, *italic*, `code`, [link](url), and @ref(id). - - @directive-name(key=val): single line value - - @multi-line: - Content spanning - multiple lines - @end - - !attest - identity: Jonathan D.A. Jewell - role: author - trust-level: verified - timestamp: 2026-03-16T00:00:00Z - !end - - - Bullet list item - - Another item - - > Block quote text - - ```elixir - defmodule Example do - def hello, do: "world" - end - ``` - -# Development - -```bash -mix deps.get # Install dependencies -mix compile # Compile project -mix test # Run tests -mix format # Format code -mix creds check # Check credentials -``` - -# Configuration - -Add to `config/config.exs`: - -```elixir -config :a2ml_ex, - default_trust_level: :reviewed, - strict_mode: true -``` - -# Related Libraries - -- [a2ml-deno](https://github.com/hyperpolymath/a2ml-deno) — - Deno/AffineScript implementation - -- [a2ml-rs](https://github.com/hyperpolymath/a2ml-rs) — Rust - implementation - -- [a2ml-haskell](https://github.com/hyperpolymath/a2ml-haskell) — - Haskell implementation - -- [a2ml_gleam](https://github.com/hyperpolymath/a2ml_gleam) — Gleam - implementation - -- [tree-sitter-a2ml](https://github.com/hyperpolymath/tree-sitter-a2ml) - — Tree-sitter grammar - -- [vscode-a2ml](https://github.com/hyperpolymath/vscode-a2ml) — VS Code - extension - -# Trust Levels - -A2ML supports four trust levels in a hierarchy: - -| Level | Meaning | -|---------------|----------------------------------------------------------| -| `:unverified` | Content has not been reviewed or attested | -| `:automated` | Content generated or verified by automated systems | -| `:reviewed` | Content reviewed by human but not formally verified | -| `:verified` | Content formally verified with cryptographic attestation | - -# Directives - -Directives provide metadata and processing instructions: - - @page-break - - @toc(depth=3): Table of Contents - - @include(file="chapter1.a2ml"): - - @template(name="article"): - # {title} - By {author} - - {content} - @end - -# Attestations - -Attestations provide cryptographic provenance: - - !attest - identity: Alice Smith - role: Editor - trust-level: verified - timestamp: 2026-03-16T12:00:00Z - signature: 0xabc123... - !end - -# Performance - -The Elixir implementation is optimized for: - -- Fast parsing of large documents - -- Memory-efficient AST representation - -- Concurrent rendering capabilities - -- Stream processing support - -# License - -SPDX-License-Identifier: CC-BY-SA-4.0 - -Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) - -See [LICENSE](LICENSE) for full license text. - -# Contributing - -See CONTRIBUTING for -contribution guidelines. - -# Roadmap - -See ROADMAP for planned features -and enhancements. diff --git a/ex/SECURITY.adoc b/ex/SECURITY.adoc new file mode 100644 index 0000000..6cc90ba --- /dev/null +++ b/ex/SECURITY.adoc @@ -0,0 +1,67 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|0.x.x |:white_check_mark: +|=== + +=== Reporting a Vulnerability + +*Do not report security vulnerabilities through public GitHub issues.* + +Instead, please report them via: + +[arabic] +. *Email*: security@hyperpolymath.org (preferred) +. *GitHub Security Advisories*: +https://github.com/hyperpolymath/a2ml_ex/security/advisories/new[Create +a private advisory] + +==== What to include + +* Type of vulnerability (injection, deserialization, etc.) +* Full path to affected source file(s) +* Step-by-step instructions to reproduce +* Proof-of-concept or exploit code (if available) +* Impact assessment + +==== Response Timeline + +* *Acknowledgment*: Within 48 hours +* *Initial assessment*: Within 7 days +* *Resolution target*: Within 90 days (may vary based on severity) + +==== Safe Harbor + +We consider security research conducted in accordance with this policy +to be: - Authorized - Lawful - Helpful + +We will not pursue legal action against researchers who follow this +policy. + +=== Security Measures + +This project implements: + +* [x] Dependabot alerts enabled +* [x] CodeQL static analysis +* [x] OpenSSF Scorecard compliance +* [x] Signed commits required +* [x] Branch protection enabled +* [x] Zero runtime dependencies beyond Elixir standard library + +=== Known Limitations + +The A2ML parser processes untrusted input. While the Elixir +implementation benefits from BEAM VM memory safety: + +[arabic] +. *Parser input* may contain maliciously crafted documents +. *Directive evaluation* does not execute arbitrary code +. *Trust level assertions* are metadata only — they do not provide +cryptographic guarantees without external verification + +Report issues in any layer — we take all security concerns seriously. diff --git a/ex/SECURITY.md b/ex/SECURITY.md deleted file mode 100644 index 25dd53b..0000000 --- a/ex/SECURITY.md +++ /dev/null @@ -1,64 +0,0 @@ -# Security Policy - - - - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| 0.x.x | :white_check_mark: | - -## Reporting a Vulnerability - -**Do not report security vulnerabilities through public GitHub issues.** - -Instead, please report them via: - -1. **Email**: security@hyperpolymath.org (preferred) -2. **GitHub Security Advisories**: [Create a private advisory](https://github.com/hyperpolymath/a2ml_ex/security/advisories/new) - -### What to include - -- Type of vulnerability (injection, deserialization, etc.) -- Full path to affected source file(s) -- Step-by-step instructions to reproduce -- Proof-of-concept or exploit code (if available) -- Impact assessment - -### Response Timeline - -- **Acknowledgment**: Within 48 hours -- **Initial assessment**: Within 7 days -- **Resolution target**: Within 90 days (may vary based on severity) - -### Safe Harbor - -We consider security research conducted in accordance with this policy to be: -- Authorized -- Lawful -- Helpful - -We will not pursue legal action against researchers who follow this policy. - -## Security Measures - -This project implements: - -- [x] Dependabot alerts enabled -- [x] CodeQL static analysis -- [x] OpenSSF Scorecard compliance -- [x] Signed commits required -- [x] Branch protection enabled -- [x] Zero runtime dependencies beyond Elixir standard library - -## Known Limitations - -The A2ML parser processes untrusted input. While the Elixir implementation -benefits from BEAM VM memory safety: - -1. **Parser input** may contain maliciously crafted documents -2. **Directive evaluation** does not execute arbitrary code -3. **Trust level assertions** are metadata only — they do not provide cryptographic guarantees without external verification - -Report issues in any layer — we take all security concerns seriously. diff --git a/ex/TEST-NEEDS.adoc b/ex/TEST-NEEDS.adoc new file mode 100644 index 0000000..ea9b75e --- /dev/null +++ b/ex/TEST-NEEDS.adoc @@ -0,0 +1,67 @@ +== TEST-NEEDS — a2ml_ex + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== CRG C — Test Coverage Achieved + +CRG C gate requires: unit, smoke, build, P2P (property-based), E2E, +reflexive, contract, aspect, and benchmark tests. + +[width="100%",cols="17%,31%,7%,45%",options="header",] +|=== +|Category |File |Count |Notes +|Unit |`+test/a2_ml_test.exs+` |13 |Parser, renderer, trust levels, +attestation + +|Smoke |`+test/a2_ml_test.exs+` |— |Covered by minimal parse/render +tests + +|Build |`+mix compile+` |— |CI gate + +|Property/P2P |`+test/a2ml_property_test.exs+` |6 |Determinism, +anti-symmetry, round-trips + +|E2E |`+test/a2_ml_test.exs+` |1 |Full parse/render/re-parse roundtrip + +|Reflexive |`+test/a2ml_property_test.exs+` |1 |`+compare(x,x) == :eq+` +for all levels + +|Contract |`+test/a2ml_contract_test.exs+` |11 |Named invariants +(error/ok guarantees) + +|Aspect |`+test/a2ml_aspect_test.exs+` |11 |Security, correctness, +performance, resilience + +|Benchmark |`+test/a2ml_bench_test.exs+` |4 |Timing guards +(parse/render/roundtrip) +|=== + +*Total: 48 tests, 0 failures* + +=== Running Tests + +[source,bash] +---- +mix test +---- + +=== Test Taxonomy (Testing Taxonomy v1.0) + +* *Unit*: individual function correctness +* *Smoke*: essential path does not crash +* *Build*: compilation gate (mix compile) +* *Property/P2P*: determinism, algebraic laws, invariants over many +inputs +* *E2E*: full parse → render → re-parse pipeline +* *Reflexive*: `+compare(x,x) == :eq+` identity laws +* *Contract*: named behavioural invariants (error-tuple guarantee, etc.) +* *Aspect*: cross-cutting concerns (security input safety, performance +bounds, resilience) +* *Benchmark*: wall-clock regression guards + +=== Remaining Gaps (Future Work) + +* Real fuzz harness (the `+tests/fuzz/placeholder.txt+` is a scorecard +placeholder only) +* Cross-implementation comparison benchmarks vs a2ml-rs and a2ml-deno +* Concurrency stress tests (if GenServer is added) diff --git a/ex/TEST-NEEDS.md b/ex/TEST-NEEDS.md deleted file mode 100644 index a58a7f8..0000000 --- a/ex/TEST-NEEDS.md +++ /dev/null @@ -1,49 +0,0 @@ -# TEST-NEEDS — a2ml_ex - - - - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## CRG C — Test Coverage Achieved - -CRG C gate requires: unit, smoke, build, P2P (property-based), E2E, -reflexive, contract, aspect, and benchmark tests. - -| Category | File | Count | Notes | -|---------------|-------------------------------|-------|---------------------------------------------| -| Unit | `test/a2_ml_test.exs` | 13 | Parser, renderer, trust levels, attestation | -| Smoke | `test/a2_ml_test.exs` | — | Covered by minimal parse/render tests | -| Build | `mix compile` | — | CI gate | -| Property/P2P | `test/a2ml_property_test.exs` | 6 | Determinism, anti-symmetry, round-trips | -| E2E | `test/a2_ml_test.exs` | 1 | Full parse/render/re-parse roundtrip | -| Reflexive | `test/a2ml_property_test.exs` | 1 | `compare(x,x) == :eq` for all levels | -| Contract | `test/a2ml_contract_test.exs` | 11 | Named invariants (error/ok guarantees) | -| Aspect | `test/a2ml_aspect_test.exs` | 11 | Security, correctness, performance, resilience | -| Benchmark | `test/a2ml_bench_test.exs` | 4 | Timing guards (parse/render/roundtrip) | - -**Total: 48 tests, 0 failures** - -## Running Tests - -```bash -mix test -``` - -## Test Taxonomy (Testing Taxonomy v1.0) - -- **Unit**: individual function correctness -- **Smoke**: essential path does not crash -- **Build**: compilation gate (mix compile) -- **Property/P2P**: determinism, algebraic laws, invariants over many inputs -- **E2E**: full parse → render → re-parse pipeline -- **Reflexive**: `compare(x,x) == :eq` identity laws -- **Contract**: named behavioural invariants (error-tuple guarantee, etc.) -- **Aspect**: cross-cutting concerns (security input safety, performance bounds, resilience) -- **Benchmark**: wall-clock regression guards - -## Remaining Gaps (Future Work) - -- Real fuzz harness (the `tests/fuzz/placeholder.txt` is a scorecard placeholder only) -- Cross-implementation comparison benchmarks vs a2ml-rs and a2ml-deno -- Concurrency stress tests (if GenServer is added) diff --git a/ex/TOPOLOGY.md b/ex/TOPOLOGY.adoc similarity index 60% rename from ex/TOPOLOGY.md rename to ex/TOPOLOGY.adoc index ade4a16..8389dc6 100644 --- a/ex/TOPOLOGY.md +++ b/ex/TOPOLOGY.adoc @@ -1,14 +1,15 @@ - - -# TOPOLOGY.md — a2ml_ex +== TOPOLOGY.md — a2ml_ex -## Purpose +=== Purpose -Elixir implementation of the A2ML (Attested Markup Language) parser and renderer. Provides a complete parse-render round-trip for A2ML documents using native Elixir structs. Intended for integration with Phoenix/BEAM applications and Elixir toolchains. +Elixir implementation of the A2ML (Attested Markup Language) parser and +renderer. Provides a complete parse-render round-trip for A2ML documents +using native Elixir structs. Intended for integration with Phoenix/BEAM +applications and Elixir toolchains. -## Module Map +=== Module Map -``` +.... a2ml_ex/ ├── lib/ │ ├── a2ml/ @@ -19,10 +20,10 @@ a2ml_ex/ │ └── a2_ml.ex # Top-level module entry point ├── mix.exs # Mix project config └── deps/ # Dependencies -``` +.... -## Data Flow +=== Data Flow -``` +.... [A2ML text] ──► [A2ML.Parser] ──► [Typed structs] ──► [A2ML.Renderer] ──► [A2ML text] -``` +.... diff --git a/ex/docs/tech-debt-2026-05-26.adoc b/ex/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..0ad9448 --- /dev/null +++ b/ex/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,71 @@ +== Tech-Debt Audit — a2ml_ex — 2026-05-26 + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+MEDIUM+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +No proof-bearing files (`+*.v+`, `+*.lean+`, `+*.agda+`, `+*.idr+`, +`+*.idr2+`, `+*.fst+`, `+*.dfy+`, `+*.tla+`, `+*.ads+`, `+*.adb+`) found +in this repo. + +*Recommended next move:* none. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+MPL-2.0+` +|Body classifier |`+Palimp-MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |233 +|`+docs/+` files |0 +|`+docs/+` LoC |0 +|CHANGELOG.md |N +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+MEDIUM+` +|=== + +*Recommended next move:* introduce a `+docs/+` directory. The README at +233 lines has likely grown to do the work of `+docs/+` — split it into a +thin README + `+docs/architecture.md+`, `+docs/usage.md+`, etc. +Heavy-wiki exemplars to copy from: `+affinescript+`, `+boj-server+`, +`+echidna+`, `+hypatia+`. + +Additionally: *CHANGELOG.md is missing.* 65% of estate repos lack one — +adopting a CHANGELOG (or auto-generating via `+git-cliff+`) is a +recommended estate-wide follow-up. + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/ex/docs/tech-debt-2026-05-26.md b/ex/docs/tech-debt-2026-05-26.md deleted file mode 100644 index 693c648..0000000 --- a/ex/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Tech-Debt Audit — a2ml_ex — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `MEDIUM`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -No proof-bearing files (`*.v`, `*.lean`, `*.agda`, `*.idr`, `*.idr2`, `*.fst`, `*.dfy`, `*.tla`, `*.ads`, `*.adb`) found in this repo. - -**Recommended next move:** none. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `MPL-2.0` | -| Body classifier | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 233 | -| `docs/` files | 0 | -| `docs/` LoC | 0 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `MEDIUM` | - -**Recommended next move:** introduce a `docs/` directory. The README at 233 lines has likely grown to do the work of `docs/` — split it into a thin README + `docs/architecture.md`, `docs/usage.md`, etc. Heavy-wiki exemplars to copy from: `affinescript`, `boj-server`, `echidna`, `hypatia`. - -Additionally: **CHANGELOG.md is missing.** 65% of estate repos lack one — adopting a CHANGELOG (or auto-generating via `git-cliff`) is a recommended estate-wide follow-up. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer. diff --git a/ex/llm-warmup-dev.adoc b/ex/llm-warmup-dev.adoc new file mode 100644 index 0000000..30eadd0 --- /dev/null +++ b/ex/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — a2ml_ex (Developer) + +=== What is a2ml_ex? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/ex/llm-warmup-dev.md b/ex/llm-warmup-dev.md deleted file mode 100644 index 106aa4a..0000000 --- a/ex/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — a2ml_ex (Developer) - -## What is a2ml_ex? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/ex/llm-warmup-user.adoc b/ex/llm-warmup-user.adoc new file mode 100644 index 0000000..a69f4f4 --- /dev/null +++ b/ex/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — a2ml_ex (User) + +=== What is a2ml_ex? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/ex/llm-warmup-user.md b/ex/llm-warmup-user.md deleted file mode 100644 index 0ae6b1c..0000000 --- a/ex/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — a2ml_ex (User) - -## What is a2ml_ex? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/gleam/ARCHITECTURE.adoc b/gleam/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/gleam/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/gleam/ARCHITECTURE.md b/gleam/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/gleam/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/gleam/CHANGELOG.adoc b/gleam/CHANGELOG.adoc new file mode 100644 index 0000000..17600aa --- /dev/null +++ b/gleam/CHANGELOG.adoc @@ -0,0 +1,53 @@ +== Changelog + +All notable changes to `+a2ml_gleam+` will be documented in this file. + +This file is generated from conventional commits by the +https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`] +workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this +repo’s CI to keep this file in sync automatically — see +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`] +for the canonical config. + +The format follows https://keepachangelog.com/en/1.1.0/[Keep a +Changelog]; this project aims to follow +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Added + +* feat(crg): add crg-grade and crg-badge justfile recipes +* feat: add stapeln.toml container definition +* feat: add UX Justfile with doctor, tour, help-me, assail recipes +* feat: deploy UX Manifesto infrastructure + +==== Fixed + +* fix(ci): sync hypatia-scan.yml to canonical (kill cd-scanner build +drift) (#19) +* fix(ci): adopt canonical hypatia-scan.yml (env.HOME/scanner-layout + +Comment-step gate) (#18) +* fix(scorecard): enforce granular permissions and add fuzzing +placeholder + +==== Documentation + +* docs: add TOPOLOGY.md +* docs: substantive CRG C annotation (EXPLAINME.adoc) +* docs: add TEST-NEEDS.md and/or PROOF-NEEDS.md from audit +* docs: add EXPLAINME.adoc — prove-it file backing README claims + +==== CI + +* ci: deploy dogfood-gate, add Groove manifest and CRG tests + +=== Pre-history + +Prior commits to this file’s introduction are recorded in git history +but not formally classified into Keep-a-Changelog sections. To backfill, +run `+git cliff -o CHANGELOG.md+` locally using the canonical +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`] +— this is one-shot mechanical work. + +''''' diff --git a/gleam/CHANGELOG.md b/gleam/CHANGELOG.md deleted file mode 100644 index 9c190cb..0000000 --- a/gleam/CHANGELOG.md +++ /dev/null @@ -1,51 +0,0 @@ - - -# Changelog - -All notable changes to `a2ml_gleam` will be documented in this file. - -This file is generated from conventional commits by the -[`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml) -workflow (`hyperpolymath/standards#206`). Adopt the workflow in this repo's CI to keep this file in sync automatically — see -[`templates/cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) -for the canonical config. - -The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); -this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added - -- feat(crg): add crg-grade and crg-badge justfile recipes -- feat: add stapeln.toml container definition -- feat: add UX Justfile with doctor, tour, help-me, assail recipes -- feat: deploy UX Manifesto infrastructure - -### Fixed - -- fix(ci): sync hypatia-scan.yml to canonical (kill cd-scanner build drift) (#19) -- fix(ci): adopt canonical hypatia-scan.yml (env.HOME/scanner-layout + Comment-step gate) (#18) -- fix(scorecard): enforce granular permissions and add fuzzing placeholder - -### Documentation - -- docs: add TOPOLOGY.md -- docs: substantive CRG C annotation (EXPLAINME.adoc) -- docs: add TEST-NEEDS.md and/or PROOF-NEEDS.md from audit -- docs: add EXPLAINME.adoc — prove-it file backing README claims - -### CI - -- ci: deploy dogfood-gate, add Groove manifest and CRG tests - -## Pre-history - -Prior commits to this file's introduction are recorded in git history but not formally classified into Keep-a-Changelog sections. To backfill, run `git cliff -o CHANGELOG.md` locally using the canonical [`cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) — this is one-shot mechanical work. - ---- - - diff --git a/gleam/CODE_OF_CONDUCT.adoc b/gleam/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/gleam/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/gleam/CODE_OF_CONDUCT.md b/gleam/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/gleam/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/gleam/CONTRIBUTING.adoc b/gleam/CONTRIBUTING.adoc new file mode 100644 index 0000000..dd089ae --- /dev/null +++ b/gleam/CONTRIBUTING.adoc @@ -0,0 +1,71 @@ +== Contributing + +Thank you for your interest in contributing! We follow a "`Dual-Track`" +architecture where human-readable documentation lives in the root and +machine-readable policies live in `+.machine_readable/+`. + +=== How to Contribute + +We welcome contributions in many forms: + +* *Code:* Improving the core stack or extensions +* *Documentation:* Enhancing docs or AI manifests +* *Testing:* Adding property-based tests or formal proofs +* *Bug reports:* Filing clear, reproducible issues + +=== Getting Started + +[arabic] +. *Read the AI Manifest:* Start with `+0-AI-MANIFEST.a2ml+` (if present) +to understand the repository structure. +. *Environment:* Use `+guix develop+` or `+direnv allow+` to set up your +tools. +. *Task Runner:* Use `+just+` to see available commands +(`+just --list+`). + +=== Development Workflow + +==== Branch Naming + +.... +docs/short-description # Documentation +test/what-added # Test additions +feat/short-description # New features +fix/issue-number-description # Bug fixes +refactor/what-changed # Code improvements +security/what-fixed # Security fixes +.... + +==== Commit Messages + +We follow https://www.conventionalcommits.org/[Conventional Commits]: + +.... +(): + +[optional body] + +[optional footer] +.... + +Types: `+feat+`, `+fix+`, `+docs+`, `+test+`, `+refactor+`, `+ci+`, +`+chore+`, `+security+` + +=== Reporting Bugs + +Before reporting: 1. Search existing issues 2. Check if it’s already +fixed in `+main+` + +When reporting, include: - Clear, descriptive title - Environment +details (OS, versions, toolchain) - Steps to reproduce - Expected vs +actual behaviour + +=== Code of Conduct + +All contributors are expected to adhere to our +link:CODE_OF_CONDUCT.md[Code of Conduct]. + +=== License + +By contributing, you agree that your contributions will be licensed +under the same license as the project (see LICENSE). diff --git a/gleam/CONTRIBUTING.md b/gleam/CONTRIBUTING.md deleted file mode 100644 index 90e87dc..0000000 --- a/gleam/CONTRIBUTING.md +++ /dev/null @@ -1,66 +0,0 @@ - -# Contributing - -Thank you for your interest in contributing! We follow a "Dual-Track" architecture where human-readable documentation lives in the root and machine-readable policies live in `.machine_readable/`. - -## How to Contribute - -We welcome contributions in many forms: - -- **Code:** Improving the core stack or extensions -- **Documentation:** Enhancing docs or AI manifests -- **Testing:** Adding property-based tests or formal proofs -- **Bug reports:** Filing clear, reproducible issues - -## Getting Started - -1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` (if present) to understand the repository structure. -2. **Environment:** Use `guix develop` or `direnv allow` to set up your tools. -3. **Task Runner:** Use `just` to see available commands (`just --list`). - -## Development Workflow - -### Branch Naming - -``` -docs/short-description # Documentation -test/what-added # Test additions -feat/short-description # New features -fix/issue-number-description # Bug fixes -refactor/what-changed # Code improvements -security/what-fixed # Security fixes -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): - -``` -(): - -[optional body] - -[optional footer] -``` - -Types: `feat`, `fix`, `docs`, `test`, `refactor`, `ci`, `chore`, `security` - -## Reporting Bugs - -Before reporting: -1. Search existing issues -2. Check if it's already fixed in `main` - -When reporting, include: -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour - -## Code of Conduct - -All contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). - -## License - -By contributing, you agree that your contributions will be licensed under the same license as the project (see [LICENSE](LICENSE)). diff --git a/gleam/GOVERNANCE.adoc b/gleam/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/gleam/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/gleam/GOVERNANCE.md b/gleam/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/gleam/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/gleam/README.adoc b/gleam/README.adoc new file mode 100644 index 0000000..9e1330a --- /dev/null +++ b/gleam/README.adoc @@ -0,0 +1,52 @@ +https://securityscorecards.dev/viewer/?uri=github.com/hyperpolymath/a2ml_gleam[image:https://api.securityscorecards.dev/projects/github.com/hyperpolymath/a2ml_gleam/badge[OpenSSF +Scorecard]] + +A2ML (AI Attestation Markup Language) parser and renderer for Gleam. + +== Overview + +A pure Gleam library for parsing, manipulating, and rendering A2ML +documents. A2ML is a lightweight markup language for expressing AI +attestations, trust levels, and verification metadata. + +== Features + +* Full A2ML parser with error reporting +* Renderer for A2ML document output +* Trust level handling (Unverified, Automated, Reviewed, Verified) +* Attestation and directive support +* Manifest extraction +* Roundtrip fidelity (parse then render preserves structure) + +== Installation + +[source,sh] +---- +gleam add a2ml_gleam +---- + +== Usage + +[source,gleam] +---- +import a2ml_gleam/parser +import a2ml_gleam/renderer + +let assert Ok(doc) = parser.parse("# My Document\n\n@version 1.0") +let output = renderer.render(doc) +---- + +== Testing + +[source,sh] +---- +gleam test +---- + +Wondering how this works? See EXPLAINME.adoc. + +== License + +SPDX-License-Identifier: CC-BY-SA-4.0 + +(MPL-2.0 preferred; MPL-2.0 required for Hex.pm ecosystem) + +See LICENSE. diff --git a/gleam/README.md b/gleam/README.md deleted file mode 100644 index 6bf7108..0000000 --- a/gleam/README.md +++ /dev/null @@ -1,58 +0,0 @@ - - -[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/hyperpolymath/a2ml_gleam/badge)](https://securityscorecards.dev/viewer/?uri=github.com/hyperpolymath/a2ml_gleam) - -A2ML (AI Attestation Markup Language) parser and renderer for Gleam. - -# Overview - -A pure Gleam library for parsing, manipulating, and rendering A2ML -documents. A2ML is a lightweight markup language for expressing AI -attestations, trust levels, and verification metadata. - -# Features - -- Full A2ML parser with error reporting - -- Renderer for A2ML document output - -- Trust level handling (Unverified, Automated, Reviewed, Verified) - -- Attestation and directive support - -- Manifest extraction - -- Roundtrip fidelity (parse then render preserves structure) - -# Installation - -```sh -gleam add a2ml_gleam -``` - -# Usage - -```gleam -import a2ml_gleam/parser -import a2ml_gleam/renderer - -let assert Ok(doc) = parser.parse("# My Document\n\n@version 1.0") -let output = renderer.render(doc) -``` - -# Testing - -```sh -gleam test -``` - -Wondering how this works? See [EXPLAINME.adoc](EXPLAINME.adoc). - -# License - -SPDX-License-Identifier: CC-BY-SA-4.0\ -(MPL-2.0 preferred; MPL-2.0 required for Hex.pm ecosystem)\ -See [LICENSE](LICENSE). diff --git a/gleam/SECURITY.adoc b/gleam/SECURITY.adoc new file mode 100644 index 0000000..cac7186 --- /dev/null +++ b/gleam/SECURITY.adoc @@ -0,0 +1,16 @@ +== Security Policy + +=== Reporting a Vulnerability + +Please report security vulnerabilities to j.d.a.jewell@open.ac.uk. + +We will acknowledge receipt within 48 hours and provide a detailed +response within 7 days. + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|Latest |Yes +|=== diff --git a/gleam/SECURITY.md b/gleam/SECURITY.md deleted file mode 100644 index d6043a9..0000000 --- a/gleam/SECURITY.md +++ /dev/null @@ -1,17 +0,0 @@ - - - - -# Security Policy - -## Reporting a Vulnerability - -Please report security vulnerabilities to j.d.a.jewell@open.ac.uk. - -We will acknowledge receipt within 48 hours and provide a detailed response within 7 days. - -## Supported Versions - -| Version | Supported | -|---------|-----------| -| Latest | Yes | diff --git a/gleam/TEST-NEEDS.adoc b/gleam/TEST-NEEDS.adoc new file mode 100644 index 0000000..1a4e06e --- /dev/null +++ b/gleam/TEST-NEEDS.adoc @@ -0,0 +1,69 @@ +== TEST-NEEDS — a2ml_gleam + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== CRG C — Test Coverage Achieved + +CRG C gate requires: unit, smoke, build, P2P (property-based), E2E, +reflexive, contract, aspect, and benchmark tests. + +[width="100%",cols="16%,37%,6%,41%",options="header",] +|=== +|Category |File |Count |Notes +|Unit |`+test/a2ml_gleam_test.gleam+` |12 |Parser, renderer, trust +levels, attestation + +|Smoke |`+test/a2ml_gleam_test.gleam+` |— |Covered by minimal +parse/render tests + +|Build |`+gleam build+` |— |CI gate + +|Property/P2P |`+test/a2ml_gleam_property_test.gleam+` |6 |Determinism, +roundtrip, invalid input loops + +|E2E |`+test/a2ml_gleam_test.gleam+` |1 |Full parse/render/re-parse +roundtrip + +|Reflexive |`+test/a2ml_gleam_property_test.gleam+` |1 |Trust level +string roundtrip identity + +|Contract |`+test/a2ml_gleam_contract_test.gleam+` |12 |Named invariants +(error/ok guarantees) + +|Aspect |`+test/a2ml_gleam_aspect_test.gleam+` |13 |Security, +correctness, performance, resilience + +|Benchmark |`+test/a2ml_gleam_bench_test.gleam+` |5 |Bulk operation +correctness guards +|=== + +*Total: 50 tests, 0 failures* + +=== Running Tests + +[source,bash] +---- +gleam test +---- + +=== Test Taxonomy (Testing Taxonomy v1.0) + +* *Unit*: individual function correctness +* *Smoke*: essential path does not crash +* *Build*: compilation gate (gleam build) +* *Property/P2P*: determinism, algebraic laws, invariants over many +inputs +* *E2E*: full parse → render → re-parse pipeline +* *Reflexive*: trust level string roundtrip identity laws +* *Contract*: named behavioural invariants (error-shape guarantee, etc.) +* *Aspect*: cross-cutting concerns (security input safety, performance +bounds, resilience) +* *Benchmark*: bulk operation correctness guards (Gleam has no +wall-clock assert harness) + +=== Remaining Gaps (Future Work) + +* Real fuzz harness (the `+tests/fuzz/placeholder.txt+` is a scorecard +placeholder only) +* Cross-implementation compatibility tests vs a2ml_ex and a2ml-rs +* BEAM vs JS target performance comparison diff --git a/gleam/TEST-NEEDS.md b/gleam/TEST-NEEDS.md deleted file mode 100644 index fc48c2c..0000000 --- a/gleam/TEST-NEEDS.md +++ /dev/null @@ -1,49 +0,0 @@ -# TEST-NEEDS — a2ml_gleam - - - - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## CRG C — Test Coverage Achieved - -CRG C gate requires: unit, smoke, build, P2P (property-based), E2E, -reflexive, contract, aspect, and benchmark tests. - -| Category | File | Count | Notes | -|---------------|-----------------------------------------|-------|---------------------------------------------| -| Unit | `test/a2ml_gleam_test.gleam` | 12 | Parser, renderer, trust levels, attestation | -| Smoke | `test/a2ml_gleam_test.gleam` | — | Covered by minimal parse/render tests | -| Build | `gleam build` | — | CI gate | -| Property/P2P | `test/a2ml_gleam_property_test.gleam` | 6 | Determinism, roundtrip, invalid input loops | -| E2E | `test/a2ml_gleam_test.gleam` | 1 | Full parse/render/re-parse roundtrip | -| Reflexive | `test/a2ml_gleam_property_test.gleam` | 1 | Trust level string roundtrip identity | -| Contract | `test/a2ml_gleam_contract_test.gleam` | 12 | Named invariants (error/ok guarantees) | -| Aspect | `test/a2ml_gleam_aspect_test.gleam` | 13 | Security, correctness, performance, resilience | -| Benchmark | `test/a2ml_gleam_bench_test.gleam` | 5 | Bulk operation correctness guards | - -**Total: 50 tests, 0 failures** - -## Running Tests - -```bash -gleam test -``` - -## Test Taxonomy (Testing Taxonomy v1.0) - -- **Unit**: individual function correctness -- **Smoke**: essential path does not crash -- **Build**: compilation gate (gleam build) -- **Property/P2P**: determinism, algebraic laws, invariants over many inputs -- **E2E**: full parse → render → re-parse pipeline -- **Reflexive**: trust level string roundtrip identity laws -- **Contract**: named behavioural invariants (error-shape guarantee, etc.) -- **Aspect**: cross-cutting concerns (security input safety, performance bounds, resilience) -- **Benchmark**: bulk operation correctness guards (Gleam has no wall-clock assert harness) - -## Remaining Gaps (Future Work) - -- Real fuzz harness (the `tests/fuzz/placeholder.txt` is a scorecard placeholder only) -- Cross-implementation compatibility tests vs a2ml_ex and a2ml-rs -- BEAM vs JS target performance comparison diff --git a/gleam/TOPOLOGY.md b/gleam/TOPOLOGY.adoc similarity index 51% rename from gleam/TOPOLOGY.md rename to gleam/TOPOLOGY.adoc index 505d4d6..adc6e1c 100644 --- a/gleam/TOPOLOGY.md +++ b/gleam/TOPOLOGY.adoc @@ -1,16 +1,15 @@ - - - +== TOPOLOGY.md — a2ml_gleam -# TOPOLOGY.md — a2ml_gleam +=== Purpose -## Purpose +A pure Gleam library for parsing, manipulating, and rendering A2ML (AI +Attestation Markup Language) documents. Provides full A2ML parser with +error reporting, manifest extraction, and roundtrip fidelity for +trust-level handling. -A pure Gleam library for parsing, manipulating, and rendering A2ML (AI Attestation Markup Language) documents. Provides full A2ML parser with error reporting, manifest extraction, and roundtrip fidelity for trust-level handling. +=== Module Map -## Module Map - -``` +.... a2ml_gleam/ ├── src/ │ ├── a2ml/ @@ -21,18 +20,19 @@ a2ml_gleam/ ├── test/ │ └── a2ml_gleam_test.gleam # Parser/renderer roundtrip tests └── gleam.toml # Hex package metadata -``` +.... -## Data Flow +=== Data Flow -``` +.... [A2ML Text] ──► [Parser] ──► [AST] ──► [Renderer] ──► [A2ML Text] ↓ [Manifest Extract] -``` +.... -## Key Invariants +=== Key Invariants -- Roundtrip fidelity: parse + render preserves document structure -- Error recovery: malformed directives return errors, don't crash -- Trust-level validation: structural only (enum values), cryptographic verification external +* Roundtrip fidelity: parse + render preserves document structure +* Error recovery: malformed directives return errors, don’t crash +* Trust-level validation: structural only (enum values), cryptographic +verification external diff --git a/gleam/docs/tech-debt-2026-05-26.adoc b/gleam/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..1ba6fef --- /dev/null +++ b/gleam/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,71 @@ +== Tech-Debt Audit — a2ml_gleam — 2026-05-26 + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+MEDIUM+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +No proof-bearing files (`+*.v+`, `+*.lean+`, `+*.agda+`, `+*.idr+`, +`+*.idr2+`, `+*.fst+`, `+*.dfy+`, `+*.tla+`, `+*.ads+`, `+*.adb+`) found +in this repo. + +*Recommended next move:* none. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+NONE+` +|Body classifier |`+Palimp-MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |58 +|`+docs/+` files |0 +|`+docs/+` LoC |0 +|CHANGELOG.md |N +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+MEDIUM+` +|=== + +*Recommended next move:* introduce a `+docs/+` directory. The README at +58 lines has likely grown to do the work of `+docs/+` — split it into a +thin README + `+docs/architecture.md+`, `+docs/usage.md+`, etc. +Heavy-wiki exemplars to copy from: `+affinescript+`, `+boj-server+`, +`+echidna+`, `+hypatia+`. + +Additionally: *CHANGELOG.md is missing.* 65% of estate repos lack one — +adopting a CHANGELOG (or auto-generating via `+git-cliff+`) is a +recommended estate-wide follow-up. + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/gleam/docs/tech-debt-2026-05-26.md b/gleam/docs/tech-debt-2026-05-26.md deleted file mode 100644 index be976eb..0000000 --- a/gleam/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Tech-Debt Audit — a2ml_gleam — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `MEDIUM`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -No proof-bearing files (`*.v`, `*.lean`, `*.agda`, `*.idr`, `*.idr2`, `*.fst`, `*.dfy`, `*.tla`, `*.ads`, `*.adb`) found in this repo. - -**Recommended next move:** none. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `NONE` | -| Body classifier | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 58 | -| `docs/` files | 0 | -| `docs/` LoC | 0 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `MEDIUM` | - -**Recommended next move:** introduce a `docs/` directory. The README at 58 lines has likely grown to do the work of `docs/` — split it into a thin README + `docs/architecture.md`, `docs/usage.md`, etc. Heavy-wiki exemplars to copy from: `affinescript`, `boj-server`, `echidna`, `hypatia`. - -Additionally: **CHANGELOG.md is missing.** 65% of estate repos lack one — adopting a CHANGELOG (or auto-generating via `git-cliff`) is a recommended estate-wide follow-up. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer. diff --git a/gleam/llm-warmup-dev.adoc b/gleam/llm-warmup-dev.adoc new file mode 100644 index 0000000..44b8e05 --- /dev/null +++ b/gleam/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — a2ml_gleam (Developer) + +=== What is a2ml_gleam? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/gleam/llm-warmup-dev.md b/gleam/llm-warmup-dev.md deleted file mode 100644 index 126ff8a..0000000 --- a/gleam/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — a2ml_gleam (Developer) - -## What is a2ml_gleam? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/gleam/llm-warmup-user.adoc b/gleam/llm-warmup-user.adoc new file mode 100644 index 0000000..4d17bfe --- /dev/null +++ b/gleam/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — a2ml_gleam (User) + +=== What is a2ml_gleam? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/gleam/llm-warmup-user.md b/gleam/llm-warmup-user.md deleted file mode 100644 index 41a9387..0000000 --- a/gleam/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — a2ml_gleam (User) - -## What is a2ml_gleam? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/haskell/ARCHITECTURE.adoc b/haskell/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/haskell/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/haskell/ARCHITECTURE.md b/haskell/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/haskell/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/haskell/CHANGELOG.adoc b/haskell/CHANGELOG.adoc new file mode 100644 index 0000000..5d88956 --- /dev/null +++ b/haskell/CHANGELOG.adoc @@ -0,0 +1,18 @@ +== Changelog + +All notable changes to this project will be documented in this file. + +The format is based on https://keepachangelog.com/en/1.1.0/[Keep a +Changelog], and this project adheres to +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [0.1.0.0] - 2026-03-16 + +==== Added + +* Initial release. +* `+Data.A2ML.Types+` — Core AST types (Document, Block, Inline, +Directive, Attestation, TrustLevel, Manifest). +* `+Data.A2ML.Parser+` — Parse `+.a2ml+` files into the typed AST. +* `+Data.A2ML.Renderer+` — Render the AST back to A2ML surface syntax. +* `+Data.A2ML+` — Convenience re-export module. diff --git a/haskell/CHANGELOG.md b/haskell/CHANGELOG.md deleted file mode 100644 index 7845f99..0000000 --- a/haskell/CHANGELOG.md +++ /dev/null @@ -1,15 +0,0 @@ -# Changelog - -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [0.1.0.0] - 2026-03-16 - -### Added -- Initial release. -- `Data.A2ML.Types` — Core AST types (Document, Block, Inline, Directive, Attestation, TrustLevel, Manifest). -- `Data.A2ML.Parser` — Parse `.a2ml` files into the typed AST. -- `Data.A2ML.Renderer` — Render the AST back to A2ML surface syntax. -- `Data.A2ML` — Convenience re-export module. diff --git a/haskell/CODE_OF_CONDUCT.adoc b/haskell/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/haskell/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/haskell/CODE_OF_CONDUCT.md b/haskell/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/haskell/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/haskell/CONTRIBUTING.adoc b/haskell/CONTRIBUTING.adoc new file mode 100644 index 0000000..dd089ae --- /dev/null +++ b/haskell/CONTRIBUTING.adoc @@ -0,0 +1,71 @@ +== Contributing + +Thank you for your interest in contributing! We follow a "`Dual-Track`" +architecture where human-readable documentation lives in the root and +machine-readable policies live in `+.machine_readable/+`. + +=== How to Contribute + +We welcome contributions in many forms: + +* *Code:* Improving the core stack or extensions +* *Documentation:* Enhancing docs or AI manifests +* *Testing:* Adding property-based tests or formal proofs +* *Bug reports:* Filing clear, reproducible issues + +=== Getting Started + +[arabic] +. *Read the AI Manifest:* Start with `+0-AI-MANIFEST.a2ml+` (if present) +to understand the repository structure. +. *Environment:* Use `+guix develop+` or `+direnv allow+` to set up your +tools. +. *Task Runner:* Use `+just+` to see available commands +(`+just --list+`). + +=== Development Workflow + +==== Branch Naming + +.... +docs/short-description # Documentation +test/what-added # Test additions +feat/short-description # New features +fix/issue-number-description # Bug fixes +refactor/what-changed # Code improvements +security/what-fixed # Security fixes +.... + +==== Commit Messages + +We follow https://www.conventionalcommits.org/[Conventional Commits]: + +.... +(): + +[optional body] + +[optional footer] +.... + +Types: `+feat+`, `+fix+`, `+docs+`, `+test+`, `+refactor+`, `+ci+`, +`+chore+`, `+security+` + +=== Reporting Bugs + +Before reporting: 1. Search existing issues 2. Check if it’s already +fixed in `+main+` + +When reporting, include: - Clear, descriptive title - Environment +details (OS, versions, toolchain) - Steps to reproduce - Expected vs +actual behaviour + +=== Code of Conduct + +All contributors are expected to adhere to our +link:CODE_OF_CONDUCT.md[Code of Conduct]. + +=== License + +By contributing, you agree that your contributions will be licensed +under the same license as the project (see LICENSE). diff --git a/haskell/CONTRIBUTING.md b/haskell/CONTRIBUTING.md deleted file mode 100644 index 90e87dc..0000000 --- a/haskell/CONTRIBUTING.md +++ /dev/null @@ -1,66 +0,0 @@ - -# Contributing - -Thank you for your interest in contributing! We follow a "Dual-Track" architecture where human-readable documentation lives in the root and machine-readable policies live in `.machine_readable/`. - -## How to Contribute - -We welcome contributions in many forms: - -- **Code:** Improving the core stack or extensions -- **Documentation:** Enhancing docs or AI manifests -- **Testing:** Adding property-based tests or formal proofs -- **Bug reports:** Filing clear, reproducible issues - -## Getting Started - -1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` (if present) to understand the repository structure. -2. **Environment:** Use `guix develop` or `direnv allow` to set up your tools. -3. **Task Runner:** Use `just` to see available commands (`just --list`). - -## Development Workflow - -### Branch Naming - -``` -docs/short-description # Documentation -test/what-added # Test additions -feat/short-description # New features -fix/issue-number-description # Bug fixes -refactor/what-changed # Code improvements -security/what-fixed # Security fixes -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): - -``` -(): - -[optional body] - -[optional footer] -``` - -Types: `feat`, `fix`, `docs`, `test`, `refactor`, `ci`, `chore`, `security` - -## Reporting Bugs - -Before reporting: -1. Search existing issues -2. Check if it's already fixed in `main` - -When reporting, include: -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour - -## Code of Conduct - -All contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). - -## License - -By contributing, you agree that your contributions will be licensed under the same license as the project (see [LICENSE](LICENSE)). diff --git a/haskell/GOVERNANCE.adoc b/haskell/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/haskell/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/haskell/GOVERNANCE.md b/haskell/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/haskell/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/haskell/PROOF-NEEDS.adoc b/haskell/PROOF-NEEDS.adoc new file mode 100644 index 0000000..9d30fc8 --- /dev/null +++ b/haskell/PROOF-NEEDS.adoc @@ -0,0 +1,13 @@ +== PROOF-NEEDS.md + +=== Template ABI Cleanup (2026-03-29) + +Template ABI removed – was creating false impression of formal +verification. The removed files (Types.idr, Layout.idr, Foreign.idr) +contained only RSR template scaffolding with unresolved +a2ml-haskell/Jonathan D.A. Jewell placeholders and no domain-specific +proofs. + +When this project needs formal ABI verification, create domain-specific +Idris2 proofs following the pattern in repos like `+typed-wasm+`, +`+proven+`, `+echidna+`, or `+boj-server+`. diff --git a/haskell/PROOF-NEEDS.md b/haskell/PROOF-NEEDS.md deleted file mode 100644 index b138a08..0000000 --- a/haskell/PROOF-NEEDS.md +++ /dev/null @@ -1,10 +0,0 @@ -# PROOF-NEEDS.md - -## Template ABI Cleanup (2026-03-29) - -Template ABI removed -- was creating false impression of formal verification. -The removed files (Types.idr, Layout.idr, Foreign.idr) contained only RSR template -scaffolding with unresolved a2ml-haskell/Jonathan D.A. Jewell placeholders and no domain-specific proofs. - -When this project needs formal ABI verification, create domain-specific Idris2 proofs -following the pattern in repos like `typed-wasm`, `proven`, `echidna`, or `boj-server`. diff --git a/haskell/README.adoc b/haskell/README.adoc new file mode 100644 index 0000000..2436c7a --- /dev/null +++ b/haskell/README.adoc @@ -0,0 +1,60 @@ +Haskell library for parsing and rendering A2ML (Attested Markup +Language) — attestation-native markup carrying trust metadata, +cryptographic attestation fields, and provenance information. + +== Overview + +`+a2ml-haskell+` provides a purely functional parser and renderer over +`+Text+`: + +* `+Data.A2ML.Parser+` — `parseA2ML + +Text → Either ParseError Document`. Line-oriented, no regex, no mutable +state. Recognises headings, multi-line directive blocks (`+@name:+` +`+…+` `+@end+`), bullet lists, and inline formatting. +* `+Data.A2ML.Renderer+` — serialises a `+Document+` back to canonical +A2ML. + +* `+Data.A2ML.Types+` — `+Document+`, `+Block+`, `+Inline+`, +`+DirectiveName+` (typed sum: `+DirAbstract+`, `+DirRefs+`, +`+DirAttestation+`, `+DirMeta+`, `+DirCustom+` `+Text+`), +`+Attestation+`, `+TrustLevel+`, `+Manifest+`, `+Reference+`. + +The Haskell variant uses richer directive syntax than `+a2ml-rs+`: +directives are multi-line `+@name:+` `+…+` `+@end+` blocks (not +single-line `+@name+` `+value+` pairs). + +== Attestation Model + +The `+Attestation+` type carries: + +* `+attestationSigner+` — identity of the signing agent or person +* `+attestationAlgorithm+` — e.g. `+"ed25519"+` or `+"sha256"+` +* `+attestationSignature+` — hex or base64 signature (opaque, not +verified here) +* `+attestationTimestamp+` — optional ISO-8601 timestamp + +`+TrustLevel+` encodes attestor count and independence: `+Unsigned+` → +`+SelfAttested+` → `+ThirdPartyAttested+` → `+MultiAttested+`. + +`+Manifest+` aggregates title, author, version, SPDX license, overall +trust level, and the full attestation list — the entry point for +provenance inspection. + +== Building + +[source,sh] +---- +cabal build +cabal test +---- + +== Related + +* https://github.com/hyperpolymath/a2ml-rs[a2ml-rs] — Rust +implementation +* https://github.com/hyperpolymath/pandoc-a2ml[pandoc-a2ml] — Pandoc Lua +reader/writer + +== License + +MPL-2.0. See LICENSE. diff --git a/haskell/README.md b/haskell/README.md deleted file mode 100644 index c870812..0000000 --- a/haskell/README.md +++ /dev/null @@ -1,70 +0,0 @@ - - -Haskell library for parsing and rendering A2ML (Attested Markup -Language) — attestation-native markup carrying trust metadata, -cryptographic attestation fields, and provenance information. - -# Overview - -`a2ml-haskell` provides a purely functional parser and renderer over -`Text`: - -- `Data.A2ML.Parser` — \`parseA2ML - Text → Either ParseError Document\`. Line-oriented, no regex, no - mutable state. Recognises headings, multi-line directive blocks - (`@name:` `…` `@end`), bullet lists, and inline formatting. - -- `Data.A2ML.Renderer` — serialises a `Document` back to canonical A2ML. - - - -- `Data.A2ML.Types` — `Document`, `Block`, `Inline`, `DirectiveName` - (typed sum: `DirAbstract`, `DirRefs`, `DirAttestation`, `DirMeta`, - `DirCustom` `Text`), `Attestation`, `TrustLevel`, `Manifest`, - `Reference`. - -The Haskell variant uses richer directive syntax than `a2ml-rs`: -directives are multi-line `@name:` `…` `@end` blocks (not single-line -`@name` `value` pairs). - -# Attestation Model - -The `Attestation` type carries: - -- `attestationSigner` — identity of the signing agent or person - -- `attestationAlgorithm` — e.g. `"ed25519"` or `"sha256"` - -- `attestationSignature` — hex or base64 signature (opaque, not verified - here) - -- `attestationTimestamp` — optional ISO-8601 timestamp - -`TrustLevel` encodes attestor count and independence: `Unsigned` → -`SelfAttested` → `ThirdPartyAttested` → `MultiAttested`. - -`Manifest` aggregates title, author, version, SPDX license, overall -trust level, and the full attestation list — the entry point for -provenance inspection. - -# Building - -```sh -cabal build -cabal test -``` - -# Related - -- [a2ml-rs](https://github.com/hyperpolymath/a2ml-rs) — Rust - implementation - -- [pandoc-a2ml](https://github.com/hyperpolymath/pandoc-a2ml) — Pandoc - Lua reader/writer - -# License - -MPL-2.0. See [LICENSE](LICENSE). diff --git a/haskell/SECURITY.adoc b/haskell/SECURITY.adoc new file mode 100644 index 0000000..e47fdd9 --- /dev/null +++ b/haskell/SECURITY.adoc @@ -0,0 +1,16 @@ +== Security Policy + +=== Reporting a Vulnerability + +If you discover a security vulnerability, please report it responsibly. + +*Email:* j.d.a.jewell@open.ac.uk + +*Please include:* - Description of the vulnerability - Steps to +reproduce - Potential impact + +*Response timeline:* - Acknowledgement within 48 hours - Initial +assessment within 7 days - Fix or mitigation within 90 days + +*Safe harbour:* We will not pursue legal action against security +researchers who follow responsible disclosure. diff --git a/haskell/SECURITY.md b/haskell/SECURITY.md deleted file mode 100644 index 5c4d5e9..0000000 --- a/haskell/SECURITY.md +++ /dev/null @@ -1,20 +0,0 @@ - -# Security Policy - -## Reporting a Vulnerability - -If you discover a security vulnerability, please report it responsibly. - -**Email:** j.d.a.jewell@open.ac.uk - -**Please include:** -- Description of the vulnerability -- Steps to reproduce -- Potential impact - -**Response timeline:** -- Acknowledgement within 48 hours -- Initial assessment within 7 days -- Fix or mitigation within 90 days - -**Safe harbour:** We will not pursue legal action against security researchers who follow responsible disclosure. diff --git a/haskell/TEST-NEEDS.adoc b/haskell/TEST-NEEDS.adoc new file mode 100644 index 0000000..04e87c9 --- /dev/null +++ b/haskell/TEST-NEEDS.adoc @@ -0,0 +1,64 @@ +== Test & Benchmark Requirements + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current State + +* Unit tests: NONE (no Haskell test files found, no test-suite in .cabal +verified) +* Integration tests: 1 Zig integration test (ABI/FFI template) +* E2E tests: NONE +* Benchmarks: NONE (benchmark dir has only README placeholder) +* panic-attack scan: NEVER RUN + +=== What’s Missing + +==== Point-to-Point (P2P) + +* Data/A2ML.hs (main module) — no tests +* Data/A2ML/Types.hs — no tests +* Data/A2ML/Parser.hs — no tests (parser is most critical) +* Data/A2ML/Renderer.hs — no tests +* Idris2 ABI definitions — no verification tests +* Zig FFI — only template integration test +* tests/fuzz/ contains only placeholder.txt + +==== End-to-End (E2E) + +* Parse A2ML document and verify output +* Render A2ML and verify format +* Round-trip fidelity +* QuickCheck / Hedgehog property-based tests for parser correctness +* Error handling for malformed input + +==== Aspect Tests + +* [ ] Security (untrusted A2ML input) +* [ ] Performance (parsing large documents, lazy evaluation pitfalls) +* [ ] Concurrency (N/A for library) +* [ ] Error handling (partial parse, encoding issues) +* [ ] Accessibility (N/A) + +==== Build & Execution + +* [ ] cabal build — not verified +* [ ] cabal test — not verified (no test-suite section found) +* [ ] Self-diagnostic — none + +==== Benchmarks Needed + +* Parse throughput vs Rust and Elixir implementations +* Memory usage (Haskell lazy evaluation can hide space leaks) +* Criterion benchmarks for parser and renderer + +==== Self-Tests + +* [ ] panic-attack assail on own repo +* [ ] Built-in doctor/check command (if applicable) + +=== Priority + +* *HIGH* — 4 Haskell source modules with ZERO tests. For a Haskell +library, the absence of property-based tests (QuickCheck/Hedgehog) is +especially damning. The fuzz directory is empty. No benchmark code +despite benchmark dir existing. diff --git a/haskell/TEST-NEEDS.md b/haskell/TEST-NEEDS.md deleted file mode 100644 index aa38800..0000000 --- a/haskell/TEST-NEEDS.md +++ /dev/null @@ -1,51 +0,0 @@ -# Test & Benchmark Requirements - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current State -- Unit tests: NONE (no Haskell test files found, no test-suite in .cabal verified) -- Integration tests: 1 Zig integration test (ABI/FFI template) -- E2E tests: NONE -- Benchmarks: NONE (benchmark dir has only README placeholder) -- panic-attack scan: NEVER RUN - -## What's Missing -### Point-to-Point (P2P) -- Data/A2ML.hs (main module) — no tests -- Data/A2ML/Types.hs — no tests -- Data/A2ML/Parser.hs — no tests (parser is most critical) -- Data/A2ML/Renderer.hs — no tests -- Idris2 ABI definitions — no verification tests -- Zig FFI — only template integration test -- tests/fuzz/ contains only placeholder.txt - -### End-to-End (E2E) -- Parse A2ML document and verify output -- Render A2ML and verify format -- Round-trip fidelity -- QuickCheck / Hedgehog property-based tests for parser correctness -- Error handling for malformed input - -### Aspect Tests -- [ ] Security (untrusted A2ML input) -- [ ] Performance (parsing large documents, lazy evaluation pitfalls) -- [ ] Concurrency (N/A for library) -- [ ] Error handling (partial parse, encoding issues) -- [ ] Accessibility (N/A) - -### Build & Execution -- [ ] cabal build — not verified -- [ ] cabal test — not verified (no test-suite section found) -- [ ] Self-diagnostic — none - -### Benchmarks Needed -- Parse throughput vs Rust and Elixir implementations -- Memory usage (Haskell lazy evaluation can hide space leaks) -- Criterion benchmarks for parser and renderer - -### Self-Tests -- [ ] panic-attack assail on own repo -- [ ] Built-in doctor/check command (if applicable) - -## Priority -- **HIGH** — 4 Haskell source modules with ZERO tests. For a Haskell library, the absence of property-based tests (QuickCheck/Hedgehog) is especially damning. The fuzz directory is empty. No benchmark code despite benchmark dir existing. diff --git a/haskell/TOPOLOGY.md b/haskell/TOPOLOGY.adoc similarity index 56% rename from haskell/TOPOLOGY.md rename to haskell/TOPOLOGY.adoc index 94f9af3..05e47f2 100644 --- a/haskell/TOPOLOGY.md +++ b/haskell/TOPOLOGY.adoc @@ -1,14 +1,15 @@ - - -# TOPOLOGY.md — a2ml-haskell +== TOPOLOGY.md — a2ml-haskell -## Purpose +=== Purpose -Haskell implementation of the A2ML (Attested Markup Language) parser and renderer. Provides strongly-typed parsing via Haskell's algebraic data types with full parse-render round-trip fidelity. Targets use in template validators, Scaffoldia, and type-heavy tooling. +Haskell implementation of the A2ML (Attested Markup Language) parser and +renderer. Provides strongly-typed parsing via Haskell’s algebraic data +types with full parse-render round-trip fidelity. Targets use in +template validators, Scaffoldia, and type-heavy tooling. -## Module Map +=== Module Map -``` +.... a2ml-haskell/ ├── src/ │ ├── Data/ # A2ML AST data types @@ -18,10 +19,10 @@ a2ml-haskell/ ├── examples/ # Usage examples ├── a2ml-haskell.cabal # Cabal build config └── container/ # Containerfile for CI -``` +.... -## Data Flow +=== Data Flow -``` +.... [A2ML text] ──► [Parser] ──► [Haskell ADT AST] ──► [Renderer] ──► [A2ML text] -``` +.... diff --git a/haskell/llm-warmup-dev.adoc b/haskell/llm-warmup-dev.adoc new file mode 100644 index 0000000..d5b7999 --- /dev/null +++ b/haskell/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — a2ml-haskell (Developer) + +=== What is a2ml-haskell? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/haskell/llm-warmup-dev.md b/haskell/llm-warmup-dev.md deleted file mode 100644 index 06ac0a9..0000000 --- a/haskell/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — a2ml-haskell (Developer) - -## What is a2ml-haskell? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/haskell/llm-warmup-user.adoc b/haskell/llm-warmup-user.adoc new file mode 100644 index 0000000..bb031e3 --- /dev/null +++ b/haskell/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — a2ml-haskell (User) + +=== What is a2ml-haskell? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/haskell/llm-warmup-user.md b/haskell/llm-warmup-user.md deleted file mode 100644 index fe59971..0000000 --- a/haskell/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — a2ml-haskell (User) - -## What is a2ml-haskell? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/members/tooling/a2ml-estate-normaliser/ARCHITECTURE.adoc b/members/tooling/a2ml-estate-normaliser/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/members/tooling/a2ml-estate-normaliser/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/members/tooling/a2ml-estate-normaliser/ARCHITECTURE.md b/members/tooling/a2ml-estate-normaliser/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/members/tooling/a2ml-estate-normaliser/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/members/tooling/a2ml-estate-normaliser/GOVERNANCE.adoc b/members/tooling/a2ml-estate-normaliser/GOVERNANCE.adoc index e41020d..9b836fb 100644 --- a/members/tooling/a2ml-estate-normaliser/GOVERNANCE.adoc +++ b/members/tooling/a2ml-estate-normaliser/GOVERNANCE.adoc @@ -1,162 +1,60 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell -= Governance Model -:toc: preamble +== Governance -This document describes the governance model for this repository. +=== Overview -== Overview +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. -This repository follows a **Sole Maintainer Governance Model**: +=== Roles and Responsibilities -* Single maintainer (@hyperpolymath) has full authority over the project -* All contributions are welcome and reviewed by the maintainer -* Decisions are made transparently through GitHub issues and discussions -* The project adheres to the hyperpolymath estate policies where applicable +==== Maintainers -== Core Principles +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support -[cols="1,2"] -|=== -| Principle | Description +==== Contributors -| **Benevolent Dictatorship** | Maintainer has final decision authority but seeks community input +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed -| **Meritocracy** | Contributions are judged on technical merit, not contributor identity +=== Decision Making -| **Transparency** | All significant decisions are documented publicly +==== Minor Changes -| **Consensus-Seeking** | Maintainer prefers consensus but will decide when necessary +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates -| **Open Contribution** | Anyone can contribute via fork and pull request +==== Major Changes -|=== +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers -== Roles and Permissions +==== Breaking Changes -[cols="1,2,2"] -|=== -| Role | Permissions | Assignment +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide -| **Maintainer** | Write access, merge rights, admin | @hyperpolymath -| **Contributors** | Read access, fork, submit PRs | All GitHub users -| **Users** | Use the software, report issues | All GitHub users +=== Code of Conduct -|=== +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. -== Decision Making Framework +=== Communication -=== Routine Decisions +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions -* Bug fixes -* Documentation improvements -* Minor feature additions -* Dependency updates +=== Licensing -**Process**: Maintainer reviews and merges PRs that meet quality standards. +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. -=== Significant Changes +''''' -* New major features -* API changes -* Architecture modifications -* Breaking changes - -**Process**: -. Open issue describing the change -. Discuss with community (minimum 72 hours) -. Maintainer makes final decision -. Document rationale in issue/PR - -=== Structural Decisions - -* Repository purpose/renaming -* License changes -* Ownership transfer -* Deprecation/archival - -**Process**: -. Extended discussion (minimum 1 week) -. Maintainer makes final decision -. Document in CHANGELOG and governance docs - -== Contribution Lifecycle - -[cols="1,2"] -|=== -| Stage | Process - -| **Ideation** | Open issue, discuss feasibility - -| **Development** | Fork, implement, test thoroughly - -| **Review** | Submit PR, maintainer reviews within 7 days - -| **Merge** | Maintainer merges or requests changes - -| **Release** | Maintainer publishes according to project conventions - -|=== - -== Conflict Resolution - -In case of disagreements: - -. Discuss in the relevant GitHub issue or PR -. Provide technical justification for positions -. Maintainer mediates and makes final decision -. Decision is documented and can be revisited later - -== Project Policies - -This repository adheres to hyperpolymath estate-wide policies: - -* **License**: MPL-2.0 for code, CC-BY-SA-4.0 for prose (per standards/LICENCE-POLICY.adoc) -* **Code of Conduct**: Follows hyperpolymath CODE_OF_CONDUCT.md -* **Security**: Follows hyperpolymath SECURITY.md -* **Contributing**: Follows hyperpolymath CONTRIBUTING.adoc conventions - -== Repository-Specific Conventions - -[cols="1,2"] -|=== -| Convention | Description - -| **Signing** | All commits must be signed (SSH or GPG) - -| **SPDX Headers** | All source files must have SPDX license identifiers - -| **Contractiles** | Mustfile, Trustfile, Intendfile, Adjustfile in root - -| **Machine Readable** | META.a2ml in .machine_readable/6a2/ - -| **CI/CD** | GitHub Actions workflows in .github/workflows/ - -|=== - -== Governance Evolution - -As the project grows, this governance model may evolve: - -* **Adding Co-Maintainers**: When contribution volume warrants it -* **Forming a Team**: For complex multi-maintainer projects -* **Adopting TPCF**: For large, multi-repository projects (see rhodium-standard-repositories) - -Changes to this document require the same process as Significant Changes above. - -== See Also - -* link:MAINTAINERS.adoc[Maintainers] -* link:CODE_OF_CONDUCT.md[Code of Conduct] -* link:CONTRIBUTING.adoc[Contributing Guide] -* link:https://github.com/hyperpolymath/standards/blob/main/LICENCE-POLICY.adoc[Estate License Policy] -* link:https://github.com/hyperpolymath/standards[rhodium-standard-repositories (TPCF)] - -== Changelog - -[cols="1,1,1"] -|=== -| Date | Change | By - -| 2026-06-07 | Initial governance model established | @hyperpolymath -|=== +_Last updated: 2026-07-18_ diff --git a/members/tooling/a2ml-estate-normaliser/GOVERNANCE.md b/members/tooling/a2ml-estate-normaliser/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/members/tooling/a2ml-estate-normaliser/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/members/tooling/a2ml-estate-normaliser/SOLUTION_SUMMARY.adoc b/members/tooling/a2ml-estate-normaliser/SOLUTION_SUMMARY.adoc new file mode 100644 index 0000000..ddf674a --- /dev/null +++ b/members/tooling/a2ml-estate-normaliser/SOLUTION_SUMMARY.adoc @@ -0,0 +1,178 @@ +== A2ML Estate Normaliser - Solution Summary + +=== Problem Statement + +The user requested a tool to normalize A2ML (Attestation Markup +Language) file structure across ~475 git repositories in the estate, +ensuring: + +[arabic] +. *File Format*: All `+.scm+` files (STATE.scm, META.scm, ECOSYSTEM.scm, +AGENTIC.scm, NEUROSYM.scm, PLAYBOOK.scm) are transpiled to `+.a2ml+` +format +. *File Location*: Core A2ML files must be in +`+repo-root/.machine_readable/6a2/+` +. *Anchor Files*: ANCHOR.a2ml files must be in +`+repo-root/.machine_readable/6a2/anchor/+` +. *Deduplication*: Only one version of each core file allowed (multiple +anchor versions with different dates are OK) +. *Documentation*: Each directory must have `+README.adoc+` and +`+AI-MANIFEST.a2ml+` files +. *Cleanup*: Remove old files from incorrect locations + +=== Solution + +Created a Rust project at +`+/home/hyperpolymath/developer/repos/a2ml/a2ml-estate-normaliser/+` +that implements all requirements. + +==== Features + +* *Repository Discovery*: Automatically finds all git repos under estate +root +* *SCM Transpilation*: Converts `+.scm+` files to `+.a2ml+` with proper +headers and metadata +* *File Organization*: Moves files to correct locations per standards +* *Deduplication*: Removes duplicate files, keeps only one version of +core files +* *Anchor Handling*: Allows multiple dated anchor versions, moves to +correct directory +* *Document Generation*: Creates README.adoc and AI manifest files for +directories +* *Cleanup*: Removes empty old directories + +==== Usage + +[source,bash] +---- +# Build +cd /home/hyperpolymath/developer/repos/a2ml/a2ml-estate-normaliser +cargo build --release + +# Dry-run (default) +./target/release/a2ml-estate-normaliser --estate-root /home/hyperpolymath/developer/repos + +# Execute changes +./target/release/a2ml-estate-normaliser --estate-root /home/hyperpolymath/developer/repos --execute + +# Process specific repos +./target/release/a2ml-estate-normaliser --repos repo1,repo2 --execute + +# Mode options: full, check, transpile, organize, documents +./target/release/a2ml-estate-normaliser --mode transpile --execute +---- + +==== Command Line Options + +[width="100%",cols="39%,61%",options="header",] +|=== +|Option |Description +|`+--estate-root DIRECTORY+` |Estate root directory (default: +auto-detect) + +|`+-x, --execute+` |Actually perform changes (default is dry-run) + +|`+-v, --verbose+` |Verbose output + +|`+-r, --repos REPOS+` |Only process specific repos (comma-separated) + +|`+-m, --mode MODE+` |Mode: full, check, transpile, organize, documents +(default: full) +|=== + +==== File Structure After Normalization + +.... +repo-root/ +└── .machine_readable/ + ├── 6a2/ + │ ├── AGENTIC.a2ml + │ ├── ECOSYSTEM.a2ml + │ ├── META.a2ml + │ ├── NEUROSYM.a2ml + │ ├── PLAYBOOK.a2ml + │ ├── STATE.a2ml + │ ├── README.adoc + │ ├── 0-AI-MANIFEST.a2ml + │ └── anchor/ + │ ├── ANCHOR.a2ml + │ ├── ANCHOR_YYYY_MM_DD.a2ml (dated versions) + │ ├── README.adoc + │ └── 0-AI-MANIFEST.a2ml + └── ... +.... + +=== Implementation Details + +==== Technology Stack + +* *Language*: Rust 2021 Edition +* *Dependencies*: clap, anyhow, walkdir, chrono, regex, serde +* *Build System*: Cargo + +==== Key Components + +[arabic] +. *Repository Discovery* (`+find_git_repos+`): Walks the estate +directory to find all `+.git+` directories +. *SCM Handling* (`+handle_scm_files+`): Recursively finds `+.scm+` +files, transpiles to `+.a2ml+` +. *Core A2ML Handling* (`+handle_core_a2ml_files+`): Finds and moves +core `+.a2ml+` files to 6a2/ +. *Anchor Handling* (`+handle_anchor_files+`): Moves anchor files to +6a2/anchor/, handles dated versions +. *Document Creation* (`+ensure_readme_and_manifest+`): Creates +README.adoc and AI manifest files +. *Cleanup* (`+cleanup_old_directories+`): Removes empty directories + +==== Transpilation Process + +When converting `+.scm+` to `+.a2ml+`: - Adds SPDX license header - Adds +copyright notice - Adds conversion metadata section with timestamp - +Preserves original content + +==== Anchor File Handling + +* Primary anchor: `+ANCHOR.a2ml+` (no date suffix) +* Dated anchors: `+ANCHOR_YYYY_MM_DD.a2ml+` (multiple allowed) +* If two files with same content exist, removes duplicate +* If two files with different content exist, keeps both with date suffix + +=== Current Estate Status + +Based on previous work summary (A2ML_FIX_SUMMARY.md): + +* *Total git repos*: 406 +* *Repos previously processed*: 311 +* *Remaining .scm files*: 62 (found in various locations) +* *Issues to address*: Files in wrong locations (e.g., +`+.machine_readable/6scm/6a2/+`, `+.machine_readable/anchors/+`, etc.) + +=== Next Steps + +[arabic] +. Build the release version: `+cargo build --release+` +. Run in check mode first: `+--mode check+` +. Review the changes that would be made +. Execute with `+--execute+` flag +. Verify results + +=== Standards Compliance + +This tool enforces the structure defined in: - +https://github.com/hyperpolymath/standards/blob/main/A2ML-REPO-TEMPLATE.adoc +- https://github.com/hyperpolymath/standards/tree/main/a2ml + +=== Note on the "`599 repos out of under 300`" Question + +The user asked: "`how can 599 repos out of under 300 have anchor.scm +files?!?`" + +This is likely due to: 1. Counting issue: The estate has 475 repos per +git status, but find may discover nested .git directories 2. Sub-repos: +Some repos contain sub-repos (e.g., in subdirectories) 3. Worktrees: Git +worktrees may be counted as separate repos 4. Previous counts may have +included non-git directories + +The tool uses proper git repository detection (looking for `+.git+` +directories) and should give accurate counts. diff --git a/members/tooling/a2ml-estate-normaliser/SOLUTION_SUMMARY.md b/members/tooling/a2ml-estate-normaliser/SOLUTION_SUMMARY.md deleted file mode 100644 index cc7dee1..0000000 --- a/members/tooling/a2ml-estate-normaliser/SOLUTION_SUMMARY.md +++ /dev/null @@ -1,149 +0,0 @@ - -# A2ML Estate Normaliser - Solution Summary - -## Problem Statement - -The user requested a tool to normalize A2ML (Attestation Markup Language) file structure across ~475 git repositories in the estate, ensuring: - -1. **File Format**: All `.scm` files (STATE.scm, META.scm, ECOSYSTEM.scm, AGENTIC.scm, NEUROSYM.scm, PLAYBOOK.scm) are transpiled to `.a2ml` format -2. **File Location**: Core A2ML files must be in `repo-root/.machine_readable/6a2/` -3. **Anchor Files**: ANCHOR.a2ml files must be in `repo-root/.machine_readable/6a2/anchor/` -4. **Deduplication**: Only one version of each core file allowed (multiple anchor versions with different dates are OK) -5. **Documentation**: Each directory must have `README.adoc` and `AI-MANIFEST.a2ml` files -6. **Cleanup**: Remove old files from incorrect locations - -## Solution - -Created a Rust project at `/home/hyperpolymath/developer/repos/a2ml/a2ml-estate-normaliser/` that implements all requirements. - -### Features - -- **Repository Discovery**: Automatically finds all git repos under estate root -- **SCM Transpilation**: Converts `.scm` files to `.a2ml` with proper headers and metadata -- **File Organization**: Moves files to correct locations per standards -- **Deduplication**: Removes duplicate files, keeps only one version of core files -- **Anchor Handling**: Allows multiple dated anchor versions, moves to correct directory -- **Document Generation**: Creates README.adoc and AI manifest files for directories -- **Cleanup**: Removes empty old directories - -### Usage - -```bash -# Build -cd /home/hyperpolymath/developer/repos/a2ml/a2ml-estate-normaliser -cargo build --release - -# Dry-run (default) -./target/release/a2ml-estate-normaliser --estate-root /home/hyperpolymath/developer/repos - -# Execute changes -./target/release/a2ml-estate-normaliser --estate-root /home/hyperpolymath/developer/repos --execute - -# Process specific repos -./target/release/a2ml-estate-normaliser --repos repo1,repo2 --execute - -# Mode options: full, check, transpile, organize, documents -./target/release/a2ml-estate-normaliser --mode transpile --execute -``` - -### Command Line Options - -| Option | Description | -|--------|-------------| -| `--estate-root DIRECTORY` | Estate root directory (default: auto-detect) | -| `-x, --execute` | Actually perform changes (default is dry-run) | -| `-v, --verbose` | Verbose output | -| `-r, --repos REPOS` | Only process specific repos (comma-separated) | -| `-m, --mode MODE` | Mode: full, check, transpile, organize, documents (default: full) | - -### File Structure After Normalization - -``` -repo-root/ -└── .machine_readable/ - ├── 6a2/ - │ ├── AGENTIC.a2ml - │ ├── ECOSYSTEM.a2ml - │ ├── META.a2ml - │ ├── NEUROSYM.a2ml - │ ├── PLAYBOOK.a2ml - │ ├── STATE.a2ml - │ ├── README.adoc - │ ├── 0-AI-MANIFEST.a2ml - │ └── anchor/ - │ ├── ANCHOR.a2ml - │ ├── ANCHOR_YYYY_MM_DD.a2ml (dated versions) - │ ├── README.adoc - │ └── 0-AI-MANIFEST.a2ml - └── ... -``` - -## Implementation Details - -### Technology Stack - -- **Language**: Rust 2021 Edition -- **Dependencies**: clap, anyhow, walkdir, chrono, regex, serde -- **Build System**: Cargo - -### Key Components - -1. **Repository Discovery** (`find_git_repos`): Walks the estate directory to find all `.git` directories -2. **SCM Handling** (`handle_scm_files`): Recursively finds `.scm` files, transpiles to `.a2ml` -3. **Core A2ML Handling** (`handle_core_a2ml_files`): Finds and moves core `.a2ml` files to 6a2/ -4. **Anchor Handling** (`handle_anchor_files`): Moves anchor files to 6a2/anchor/, handles dated versions -5. **Document Creation** (`ensure_readme_and_manifest`): Creates README.adoc and AI manifest files -6. **Cleanup** (`cleanup_old_directories`): Removes empty directories - -### Transpilation Process - -When converting `.scm` to `.a2ml`: -- Adds SPDX license header -- Adds copyright notice -- Adds conversion metadata section with timestamp -- Preserves original content - -### Anchor File Handling - -- Primary anchor: `ANCHOR.a2ml` (no date suffix) -- Dated anchors: `ANCHOR_YYYY_MM_DD.a2ml` (multiple allowed) -- If two files with same content exist, removes duplicate -- If two files with different content exist, keeps both with date suffix - -## Current Estate Status - -Based on previous work summary (A2ML_FIX_SUMMARY.md): - -- **Total git repos**: 406 -- **Repos previously processed**: 311 -- **Remaining .scm files**: 62 (found in various locations) -- **Issues to address**: Files in wrong locations (e.g., `.machine_readable/6scm/6a2/`, `.machine_readable/anchors/`, etc.) - -## Next Steps - -1. Build the release version: `cargo build --release` -2. Run in check mode first: `--mode check` -3. Review the changes that would be made -4. Execute with `--execute` flag -5. Verify results - -## Standards Compliance - -This tool enforces the structure defined in: -- https://github.com/hyperpolymath/standards/blob/main/A2ML-REPO-TEMPLATE.adoc -- https://github.com/hyperpolymath/standards/tree/main/a2ml - -## Note on the "599 repos out of under 300" Question - -The user asked: "how can 599 repos out of under 300 have anchor.scm files?!?" - -This is likely due to: -1. Counting issue: The estate has 475 repos per git status, but find may discover nested .git directories -2. Sub-repos: Some repos contain sub-repos (e.g., in subdirectories) -3. Worktrees: Git worktrees may be counted as separate repos -4. Previous counts may have included non-git directories - -The tool uses proper git repository detection (looking for `.git` directories) and should give accurate counts. diff --git a/members/tooling/scm2a2ml/A2ML_FIX_SUMMARY.adoc b/members/tooling/scm2a2ml/A2ML_FIX_SUMMARY.adoc new file mode 100644 index 0000000..83dba31 --- /dev/null +++ b/members/tooling/scm2a2ml/A2ML_FIX_SUMMARY.adoc @@ -0,0 +1,115 @@ +== A2ML Structure Fix Summary + +=== Date: 2026-06-01 + +=== Actions Performed + +==== 1. Transpiled .scm files to .a2ml format + +* *Repos affected*: 10 repos had .scm files in `+.machine_readable/+` +root +* *Files*: STATE.scm, META.scm, ECOSYSTEM.scm, AGENTIC.scm, +NEUROSYM.scm, PLAYBOOK.scm +* *Action*: Moved to `+.machine_readable/6a2/+` with .a2ml extension +* *Status*: ✅ Complete - 0 .scm files remaining + +*Repos with .scm files (now converted):* - absolute-zero - avow-protocol +- claude-integrations - coq-jr - hyperpolymath-archive - +ipv6-site-enforcer - network-ambulance - network-dashboard - oblienveny +- volumod + +*Note*: The .scm files use Scheme S-expression format. Current +conversion is a simple copy with header addition. Proper Scheme-to-A2ML +transpilation may be needed for full format compliance. + +==== 2. Moved anchor.a2ml files to correct location + +* *Repos with anchor in `+.machine_readable/anchors/+`*: 272 repos +* *Repos with anchor in `+.machine_readable/6a2/+`*: 5 repos + +* *Repos with anchor in both locations*: 4 repos +* *Action*: Moved all anchor files to `+.machine_readable/6a2/anchor/+` +* *Multiple versions*: Files with different dates are kept with date +suffix (e.g., ANCHOR_2026_05_19.a2ml) +* *Status*: ✅ Complete - 0 anchor files in old locations + +==== 3. Created README.adoc files + +* *6a2 directories*: 283 repos now have README.adoc in +`+.machine_readable/6a2/+` +* *Anchor directories*: 283 repos now have README.adoc in +`+.machine_readable/6a2/anchor/+` +* *Status*: ✅ Complete + +==== 4. Created AI manifest files + +* *6a2 directories*: 283 repos now have 0-AI-MANIFEST.a2ml in +`+.machine_readable/6a2/+` +* *Anchor directories*: 282 repos now have 0-AI-MANIFEST.a2ml in +`+.machine_readable/6a2/anchor/+` +* *Note*: 1 repo (claude-integrations) has 6a2/anchor directory but no +anchor files, so no AI manifest was created there +* *Status*: ✅ Complete + +==== 5. Cleaned up old directories + +* *Empty anchors/ directories*: Removed where applicable after moving +files +* *Status*: ✅ Complete + +=== Final State + +==== File Locations + +All A2ML files now follow the standard structure: + +.... +repo-root/ +└── .machine_readable/ + ├── 6a2/ + │ ├── AGENTIC.a2ml + │ ├── ECOSYSTEM.a2ml + │ ├── META.a2ml + │ ├── NEUROSYM.a2ml + │ ├── PLAYBOOK.a2ml + │ ├── STATE.a2ml + │ ├── README.adoc + │ ├── 0-AI-MANIFEST.a2ml + │ └── anchor/ + │ ├── ANCHOR.a2ml (primary) + │ ├── ANCHOR_YYYY_MM_DD.a2ml (additional versions with dates) + │ ├── README.adoc + │ └── 0-AI-MANIFEST.a2ml + └── ... (other machine_readable files) +.... + +==== Compliance + +* ✅ Only one version of each core file (STATE, META, ECOSYSTEM, +AGENTIC, NEUROSYM, PLAYBOOK) +* ✅ Multiple versions of anchor.a2ml allowed with different dates +* ✅ All files in correct locations +* ✅ All directories have README.adoc +* ✅ All directories have AI manifest + +=== Statistics + +* *Total git repos in estate*: 406 +* *Repos processed*: 311 +* *Repos with .scm files*: 10 (all converted) +* *Repos with anchor files*: 273 (all moved) +* *Repos with new 6a2/ directories*: 283 +* *Repos with new 6a2/anchor/ directories*: 283 + +=== Known Issues + +[arabic] +. *Scheme format*: The .scm files are in Scheme S-expression format, not +TOML-like A2ML format. Current conversion is a simple file copy. Proper +transpilation may be needed. +. *Claude-integrations*: Has 6a2/anchor directory but no anchor files or +AI manifest (not a bug - repo doesn’t use anchors) + +=== Scripts Used + +* `+fix_a2ml_structure_v2.sh+` - Main fix script +* `+fix_a2ml_structure.sh+` - Initial version diff --git a/members/tooling/scm2a2ml/A2ML_FIX_SUMMARY.md b/members/tooling/scm2a2ml/A2ML_FIX_SUMMARY.md deleted file mode 100644 index 3af6839..0000000 --- a/members/tooling/scm2a2ml/A2ML_FIX_SUMMARY.md +++ /dev/null @@ -1,100 +0,0 @@ - -# A2ML Structure Fix Summary - -## Date: 2026-06-01 - -## Actions Performed - -### 1. Transpiled .scm files to .a2ml format -- **Repos affected**: 10 repos had .scm files in `.machine_readable/` root -- **Files**: STATE.scm, META.scm, ECOSYSTEM.scm, AGENTIC.scm, NEUROSYM.scm, PLAYBOOK.scm -- **Action**: Moved to `.machine_readable/6a2/` with .a2ml extension -- **Status**: ✅ Complete - 0 .scm files remaining - -**Repos with .scm files (now converted):** -- absolute-zero -- avow-protocol -- claude-integrations -- coq-jr -- hyperpolymath-archive -- ipv6-site-enforcer -- network-ambulance -- network-dashboard -- oblienveny -- volumod - -**Note**: The .scm files use Scheme S-expression format. Current conversion is a simple copy with header addition. Proper Scheme-to-A2ML transpilation may be needed for full format compliance. - -### 2. Moved anchor.a2ml files to correct location -- **Repos with anchor in `.machine_readable/anchors/`**: 272 repos -- **Repos with anchor in `.machine_readable/6a2/`**: 5 repos -- **Repos with anchor in both locations**: 4 repos -- **Action**: Moved all anchor files to `.machine_readable/6a2/anchor/` -- **Multiple versions**: Files with different dates are kept with date suffix (e.g., ANCHOR_2026_05_19.a2ml) -- **Status**: ✅ Complete - 0 anchor files in old locations - -### 3. Created README.adoc files -- **6a2 directories**: 283 repos now have README.adoc in `.machine_readable/6a2/` -- **Anchor directories**: 283 repos now have README.adoc in `.machine_readable/6a2/anchor/` -- **Status**: ✅ Complete - -### 4. Created AI manifest files -- **6a2 directories**: 283 repos now have 0-AI-MANIFEST.a2ml in `.machine_readable/6a2/` -- **Anchor directories**: 282 repos now have 0-AI-MANIFEST.a2ml in `.machine_readable/6a2/anchor/` -- **Note**: 1 repo (claude-integrations) has 6a2/anchor directory but no anchor files, so no AI manifest was created there -- **Status**: ✅ Complete - -### 5. Cleaned up old directories -- **Empty anchors/ directories**: Removed where applicable after moving files -- **Status**: ✅ Complete - -## Final State - -### File Locations -All A2ML files now follow the standard structure: -``` -repo-root/ -└── .machine_readable/ - ├── 6a2/ - │ ├── AGENTIC.a2ml - │ ├── ECOSYSTEM.a2ml - │ ├── META.a2ml - │ ├── NEUROSYM.a2ml - │ ├── PLAYBOOK.a2ml - │ ├── STATE.a2ml - │ ├── README.adoc - │ ├── 0-AI-MANIFEST.a2ml - │ └── anchor/ - │ ├── ANCHOR.a2ml (primary) - │ ├── ANCHOR_YYYY_MM_DD.a2ml (additional versions with dates) - │ ├── README.adoc - │ └── 0-AI-MANIFEST.a2ml - └── ... (other machine_readable files) -``` - -### Compliance -- ✅ Only one version of each core file (STATE, META, ECOSYSTEM, AGENTIC, NEUROSYM, PLAYBOOK) -- ✅ Multiple versions of anchor.a2ml allowed with different dates -- ✅ All files in correct locations -- ✅ All directories have README.adoc -- ✅ All directories have AI manifest - -## Statistics -- **Total git repos in estate**: 406 -- **Repos processed**: 311 -- **Repos with .scm files**: 10 (all converted) -- **Repos with anchor files**: 273 (all moved) -- **Repos with new 6a2/ directories**: 283 -- **Repos with new 6a2/anchor/ directories**: 283 - -## Known Issues -1. **Scheme format**: The .scm files are in Scheme S-expression format, not TOML-like A2ML format. Current conversion is a simple file copy. Proper transpilation may be needed. -2. **Claude-integrations**: Has 6a2/anchor directory but no anchor files or AI manifest (not a bug - repo doesn't use anchors) - -## Scripts Used -- `fix_a2ml_structure_v2.sh` - Main fix script -- `fix_a2ml_structure.sh` - Initial version - diff --git a/members/tooling/scm2a2ml/ARCHITECTURE.adoc b/members/tooling/scm2a2ml/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/members/tooling/scm2a2ml/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/members/tooling/scm2a2ml/ARCHITECTURE.md b/members/tooling/scm2a2ml/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/members/tooling/scm2a2ml/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/members/tooling/scm2a2ml/CODE_OF_CONDUCT.adoc b/members/tooling/scm2a2ml/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..ff3f3db --- /dev/null +++ b/members/tooling/scm2a2ml/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +Squisher Corpus a harassment-free experience for everyone, regardless of +age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |j.d.a.jewell@open.ac.uk |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *48 hours* +. The maintainers will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a maintainers member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The maintainers will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* j.d.a.jewell@open.ac.uk with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different maintainers member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://github.com/hyperpolymath/squisher-corpus/discussions[Discussion] +(for general questions) +* Email j.d.a.jewell@open.ac.uk (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/members/tooling/scm2a2ml/CODE_OF_CONDUCT.md b/members/tooling/scm2a2ml/CODE_OF_CONDUCT.md deleted file mode 100644 index 8267cd4..0000000 --- a/members/tooling/scm2a2ml/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in Squisher Corpus a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | j.d.a.jewell@open.ac.uk | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **48 hours** -2. The maintainers will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a maintainers member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The maintainers will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** j.d.a.jewell@open.ac.uk with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different maintainers member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://github.com/hyperpolymath/squisher-corpus/discussions) (for general questions) -- Email j.d.a.jewell@open.ac.uk (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/members/tooling/scm2a2ml/CONTRIBUTING.adoc b/members/tooling/scm2a2ml/CONTRIBUTING.adoc new file mode 100644 index 0000000..47a707d --- /dev/null +++ b/members/tooling/scm2a2ml/CONTRIBUTING.adoc @@ -0,0 +1,109 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/squisher-corpus.git cd +squisher-corpus + +== Using Guix (recommended for reproducibility) + +guix develop + +== Or using toolbox/distrobox + +toolbox create squisher-corpus-dev toolbox enter squisher-corpus-dev # +Install dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +squisher-corpus/ ├── src/ # Source code (Perimeter 1-2) ├── lib/ # +Library code (Perimeter 1-2) ├── extensions/ # Extensions (Perimeter 2) +├── plugins/ # Plugins (Perimeter 2) ├── tools/ # Tooling (Perimeter 2) +├── docs/ # Documentation (Perimeter 3) │ ├── architecture/ # ADRs, +specs (Perimeter 2) │ └── proposals/ # RFCs (Perimeter 3) ├── examples/ +# Examples (Perimeter 3) ├── spec/ # Spec tests (Perimeter 3) ├── tests/ +# Test suite (Perimeter 2-3) ├── .well-known/ # Protocol files +(Perimeter 1-3) ├── .github/ # GitHub config (Perimeter 1) │ ├── +ISSUE_TEMPLATE/ │ └── workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md +├── CONTRIBUTING.md # This file ├── GOVERNANCE.md ├── LICENSE ├── +MAINTAINERS.md ├── README.adoc ├── SECURITY.md ├── flake.guix # Guix +flake (Perimeter 1) └── Justfile # Task runner (Perimeter 1) + +.... + +--- + +## How to Contribute + +### Reporting Bugs + +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects + +**When reporting**: + +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: + +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction + +### Suggesting Features + +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to + +**When suggesting**: + +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: + +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects + +### Your First Contribution + +Look for issues labelled: + +- [`good first issue`](https://github.com/hyperpolymath/squisher-corpus/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/squisher-corpus/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/squisher-corpus/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/squisher-corpus/labels/perimeter-3) — Community sandbox scope + +--- + +## Development Workflow + +### Branch Naming +.... + +docs/short-description # Documentation (P3) test/what-added # Test +additions (P3) feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) refactor/what-changed # +Code improvements (P2) security/what-fixed # Security fixes (P1-2) + +.... + +### Commit Messages + +We follow [Conventional Commits](https://www.conventionalcommits.org/): +.... + +(): + +{empty}[optional body] + +{empty}[optional footer] diff --git a/members/tooling/scm2a2ml/CONTRIBUTING.md b/members/tooling/scm2a2ml/CONTRIBUTING.md deleted file mode 100644 index 456dcad..0000000 --- a/members/tooling/scm2a2ml/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://github.com/hyperpolymath/squisher-corpus.git -cd squisher-corpus - -# Using Guix (recommended for reproducibility) -guix develop - -# Or using toolbox/distrobox -toolbox create squisher-corpus-dev -toolbox enter squisher-corpus-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -squisher-corpus/ -├── src/ # Source code (Perimeter 1-2) -├── lib/ # Library code (Perimeter 1-2) -├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) -├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) -│ ├── architecture/ # ADRs, specs (Perimeter 2) -│ └── proposals/ # RFCs (Perimeter 3) -├── examples/ # Examples (Perimeter 3) -├── spec/ # Spec tests (Perimeter 3) -├── tests/ # Test suite (Perimeter 2-3) -├── .well-known/ # Protocol files (Perimeter 1-3) -├── .github/ # GitHub config (Perimeter 1) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── GOVERNANCE.md -├── LICENSE -├── MAINTAINERS.md -├── README.adoc -├── SECURITY.md -├── flake.guix # Guix flake (Perimeter 1) -└── Justfile # Task runner (Perimeter 1) -``` - ---- - -## How to Contribute - -### Reporting Bugs - -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `main` -3. Determine which perimeter the bug affects - -**When reporting**: - -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction - -### Suggesting Features - -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: - -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: - -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/squisher-corpus/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/squisher-corpus/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/squisher-corpus/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/squisher-corpus/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -``` -docs/short-description # Documentation (P3) -test/what-added # Test additions (P3) -feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) -refactor/what-changed # Code improvements (P2) -security/what-fixed # Security fixes (P1-2) -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -``` -(): - -[optional body] - -[optional footer] diff --git a/members/tooling/scm2a2ml/GOVERNANCE.adoc b/members/tooling/scm2a2ml/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/members/tooling/scm2a2ml/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/members/tooling/scm2a2ml/GOVERNANCE.md b/members/tooling/scm2a2ml/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/members/tooling/scm2a2ml/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/members/tooling/scm2a2ml/SECURITY.adoc b/members/tooling/scm2a2ml/SECURITY.adoc new file mode 100644 index 0000000..4f3490a --- /dev/null +++ b/members/tooling/scm2a2ml/SECURITY.adoc @@ -0,0 +1,452 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/hyperpolymath/squisher-corpus/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[width="100%",cols="50%,50%",] +|=== +|*Email* |j.d.a.jewell@open.ac.uk +|*PGP Key* |https://github.com/hyperpolymath.gpg[Download Public Key] +|*Fingerprint* |`+TBD+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL https://github.com/hyperpolymath.gpg | gpg --import + +# Verify fingerprint +gpg --fingerprint j.d.a.jewell@open.ac.uk + +# Encrypt your report +gpg --armor --encrypt --recipient j.d.a.jewell@open.ac.uk report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+hyperpolymath/squisher-corpus+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/hyperpolymath/squisher-corpus/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using Squisher Corpus, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* https://github.com/hyperpolymath.gpg[Our PGP Public Key] +* https://github.com/hyperpolymath/squisher-corpus/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/hyperpolymath/squisher-corpus/security/advisories/new[Report +via GitHub] or j.d.a.jewell@open.ac.uk + +|*General questions* +|https://github.com/hyperpolymath/squisher-corpus/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep Squisher Corpus and its users safe._ 🛡️ + +''''' + +Last updated: 2026 · Policy version: 1.0.0 diff --git a/members/tooling/scm2a2ml/SECURITY.md b/members/tooling/scm2a2ml/SECURITY.md deleted file mode 100644 index 1ed5203..0000000 --- a/members/tooling/scm2a2ml/SECURITY.md +++ /dev/null @@ -1,406 +0,0 @@ -# Security Policy - - - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/hyperpolymath/squisher-corpus/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | j.d.a.jewell@open.ac.uk | -| **PGP Key** | [Download Public Key](https://github.com/hyperpolymath.gpg) | -| **Fingerprint** | `TBD` | - -```bash -# Import our PGP key -curl -sSL https://github.com/hyperpolymath.gpg | gpg --import - -# Verify fingerprint -gpg --fingerprint j.d.a.jewell@open.ac.uk - -# Encrypt your report -gpg --armor --encrypt --recipient j.d.a.jewell@open.ac.uk report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`hyperpolymath/squisher-corpus`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/hyperpolymath/squisher-corpus/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using Squisher Corpus, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key](https://github.com/hyperpolymath.gpg) -- [Security Advisories](https://github.com/hyperpolymath/squisher-corpus/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/hyperpolymath/squisher-corpus/security/advisories/new) or j.d.a.jewell@open.ac.uk | -| **General questions** | [GitHub Discussions](https://github.com/hyperpolymath/squisher-corpus/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep Squisher Corpus and its users safe.* 🛡️ - ---- - -Last updated: 2026 · Policy version: 1.0.0 diff --git a/members/tooling/vscode-a2ml/ARCHITECTURE.adoc b/members/tooling/vscode-a2ml/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/members/tooling/vscode-a2ml/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/members/tooling/vscode-a2ml/ARCHITECTURE.md b/members/tooling/vscode-a2ml/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/members/tooling/vscode-a2ml/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/members/tooling/vscode-a2ml/CHANGELOG.adoc b/members/tooling/vscode-a2ml/CHANGELOG.adoc new file mode 100644 index 0000000..ca1c652 --- /dev/null +++ b/members/tooling/vscode-a2ml/CHANGELOG.adoc @@ -0,0 +1,9 @@ +== Changelog + +All notable changes to this project will be documented in this file. + +The format is based on https://keepachangelog.com/en/1.1.0/[Keep a +Changelog], and this project adheres to +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] diff --git a/members/tooling/vscode-a2ml/CHANGELOG.md b/members/tooling/vscode-a2ml/CHANGELOG.md deleted file mode 100644 index 8109476..0000000 --- a/members/tooling/vscode-a2ml/CHANGELOG.md +++ /dev/null @@ -1,11 +0,0 @@ -# Changelog - -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - - - - -## [Unreleased] diff --git a/members/tooling/vscode-a2ml/CODE_OF_CONDUCT.adoc b/members/tooling/vscode-a2ml/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/members/tooling/vscode-a2ml/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/members/tooling/vscode-a2ml/CODE_OF_CONDUCT.md b/members/tooling/vscode-a2ml/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/members/tooling/vscode-a2ml/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/members/tooling/vscode-a2ml/CONTRIBUTING.adoc b/members/tooling/vscode-a2ml/CONTRIBUTING.adoc new file mode 100644 index 0000000..dd089ae --- /dev/null +++ b/members/tooling/vscode-a2ml/CONTRIBUTING.adoc @@ -0,0 +1,71 @@ +== Contributing + +Thank you for your interest in contributing! We follow a "`Dual-Track`" +architecture where human-readable documentation lives in the root and +machine-readable policies live in `+.machine_readable/+`. + +=== How to Contribute + +We welcome contributions in many forms: + +* *Code:* Improving the core stack or extensions +* *Documentation:* Enhancing docs or AI manifests +* *Testing:* Adding property-based tests or formal proofs +* *Bug reports:* Filing clear, reproducible issues + +=== Getting Started + +[arabic] +. *Read the AI Manifest:* Start with `+0-AI-MANIFEST.a2ml+` (if present) +to understand the repository structure. +. *Environment:* Use `+guix develop+` or `+direnv allow+` to set up your +tools. +. *Task Runner:* Use `+just+` to see available commands +(`+just --list+`). + +=== Development Workflow + +==== Branch Naming + +.... +docs/short-description # Documentation +test/what-added # Test additions +feat/short-description # New features +fix/issue-number-description # Bug fixes +refactor/what-changed # Code improvements +security/what-fixed # Security fixes +.... + +==== Commit Messages + +We follow https://www.conventionalcommits.org/[Conventional Commits]: + +.... +(): + +[optional body] + +[optional footer] +.... + +Types: `+feat+`, `+fix+`, `+docs+`, `+test+`, `+refactor+`, `+ci+`, +`+chore+`, `+security+` + +=== Reporting Bugs + +Before reporting: 1. Search existing issues 2. Check if it’s already +fixed in `+main+` + +When reporting, include: - Clear, descriptive title - Environment +details (OS, versions, toolchain) - Steps to reproduce - Expected vs +actual behaviour + +=== Code of Conduct + +All contributors are expected to adhere to our +link:CODE_OF_CONDUCT.md[Code of Conduct]. + +=== License + +By contributing, you agree that your contributions will be licensed +under the same license as the project (see LICENSE). diff --git a/members/tooling/vscode-a2ml/CONTRIBUTING.md b/members/tooling/vscode-a2ml/CONTRIBUTING.md deleted file mode 100644 index 90e87dc..0000000 --- a/members/tooling/vscode-a2ml/CONTRIBUTING.md +++ /dev/null @@ -1,66 +0,0 @@ - -# Contributing - -Thank you for your interest in contributing! We follow a "Dual-Track" architecture where human-readable documentation lives in the root and machine-readable policies live in `.machine_readable/`. - -## How to Contribute - -We welcome contributions in many forms: - -- **Code:** Improving the core stack or extensions -- **Documentation:** Enhancing docs or AI manifests -- **Testing:** Adding property-based tests or formal proofs -- **Bug reports:** Filing clear, reproducible issues - -## Getting Started - -1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` (if present) to understand the repository structure. -2. **Environment:** Use `guix develop` or `direnv allow` to set up your tools. -3. **Task Runner:** Use `just` to see available commands (`just --list`). - -## Development Workflow - -### Branch Naming - -``` -docs/short-description # Documentation -test/what-added # Test additions -feat/short-description # New features -fix/issue-number-description # Bug fixes -refactor/what-changed # Code improvements -security/what-fixed # Security fixes -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): - -``` -(): - -[optional body] - -[optional footer] -``` - -Types: `feat`, `fix`, `docs`, `test`, `refactor`, `ci`, `chore`, `security` - -## Reporting Bugs - -Before reporting: -1. Search existing issues -2. Check if it's already fixed in `main` - -When reporting, include: -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour - -## Code of Conduct - -All contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). - -## License - -By contributing, you agree that your contributions will be licensed under the same license as the project (see [LICENSE](LICENSE)). diff --git a/members/tooling/vscode-a2ml/GOVERNANCE.adoc b/members/tooling/vscode-a2ml/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/members/tooling/vscode-a2ml/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/members/tooling/vscode-a2ml/GOVERNANCE.md b/members/tooling/vscode-a2ml/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/members/tooling/vscode-a2ml/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/members/tooling/vscode-a2ml/PROOF-NEEDS.adoc b/members/tooling/vscode-a2ml/PROOF-NEEDS.adoc new file mode 100644 index 0000000..7d5132f --- /dev/null +++ b/members/tooling/vscode-a2ml/PROOF-NEEDS.adoc @@ -0,0 +1,12 @@ +== PROOF-NEEDS.md + +=== Template ABI Cleanup (2026-03-29) + +Template ABI removed – was creating false impression of formal +verification. The removed files (Types.idr, Layout.idr, Foreign.idr) +contained only RSR template scaffolding with unresolved +\{\{PROJECT}}/\{\{AUTHOR}} placeholders and no domain-specific proofs. + +When this project needs formal ABI verification, create domain-specific +Idris2 proofs following the pattern in repos like `+typed-wasm+`, +`+proven+`, `+echidna+`, or `+boj-server+`. diff --git a/members/tooling/vscode-a2ml/PROOF-NEEDS.md b/members/tooling/vscode-a2ml/PROOF-NEEDS.md deleted file mode 100644 index 8950320..0000000 --- a/members/tooling/vscode-a2ml/PROOF-NEEDS.md +++ /dev/null @@ -1,10 +0,0 @@ -# PROOF-NEEDS.md - -## Template ABI Cleanup (2026-03-29) - -Template ABI removed -- was creating false impression of formal verification. -The removed files (Types.idr, Layout.idr, Foreign.idr) contained only RSR template -scaffolding with unresolved {{PROJECT}}/{{AUTHOR}} placeholders and no domain-specific proofs. - -When this project needs formal ABI verification, create domain-specific Idris2 proofs -following the pattern in repos like `typed-wasm`, `proven`, `echidna`, or `boj-server`. diff --git a/members/tooling/vscode-a2ml/SECURITY.adoc b/members/tooling/vscode-a2ml/SECURITY.adoc new file mode 100644 index 0000000..e47fdd9 --- /dev/null +++ b/members/tooling/vscode-a2ml/SECURITY.adoc @@ -0,0 +1,16 @@ +== Security Policy + +=== Reporting a Vulnerability + +If you discover a security vulnerability, please report it responsibly. + +*Email:* j.d.a.jewell@open.ac.uk + +*Please include:* - Description of the vulnerability - Steps to +reproduce - Potential impact + +*Response timeline:* - Acknowledgement within 48 hours - Initial +assessment within 7 days - Fix or mitigation within 90 days + +*Safe harbour:* We will not pursue legal action against security +researchers who follow responsible disclosure. diff --git a/members/tooling/vscode-a2ml/SECURITY.md b/members/tooling/vscode-a2ml/SECURITY.md deleted file mode 100644 index 5c4d5e9..0000000 --- a/members/tooling/vscode-a2ml/SECURITY.md +++ /dev/null @@ -1,20 +0,0 @@ - -# Security Policy - -## Reporting a Vulnerability - -If you discover a security vulnerability, please report it responsibly. - -**Email:** j.d.a.jewell@open.ac.uk - -**Please include:** -- Description of the vulnerability -- Steps to reproduce -- Potential impact - -**Response timeline:** -- Acknowledgement within 48 hours -- Initial assessment within 7 days -- Fix or mitigation within 90 days - -**Safe harbour:** We will not pursue legal action against security researchers who follow responsible disclosure. diff --git a/members/tooling/vscode-a2ml/TEST-NEEDS.adoc b/members/tooling/vscode-a2ml/TEST-NEEDS.adoc new file mode 100644 index 0000000..1f37cf1 --- /dev/null +++ b/members/tooling/vscode-a2ml/TEST-NEEDS.adoc @@ -0,0 +1,35 @@ +== TEST-NEEDS.md — vscode-a2ml + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current Test State + +[cols=",,",options="header",] +|=== +|Category |Count |Notes +|Test infrastructure |Present |`+tests/+` directory structure +|FFI tests |Present |`+src/interface/ffi/test/+` +|Verification tests |Present |`+verification/tests/+` +|Aspect modules |Present |`+src/aspects/+` +|=== + +=== What’s Covered + +* [x] Test framework infrastructure +* [x] FFI verification layer +* [x] Aspect-based organization + +=== Still Missing (for CRG B+) + +* [ ] A2ML language syntax tests +* [ ] VSCode extension integration tests +* [ ] Highlighting tests +* [ ] Performance benchmarks +* [ ] End-to-end editor tests + +=== Run Tests + +[source,bash] +---- +cd /var/mnt/eclipse/repos/vscode-a2ml && npm test +---- diff --git a/members/tooling/vscode-a2ml/TEST-NEEDS.md b/members/tooling/vscode-a2ml/TEST-NEEDS.md deleted file mode 100644 index 8f638c5..0000000 --- a/members/tooling/vscode-a2ml/TEST-NEEDS.md +++ /dev/null @@ -1,32 +0,0 @@ -# TEST-NEEDS.md — vscode-a2ml - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current Test State - -| Category | Count | Notes | -|----------|-------|-------| -| Test infrastructure | Present | `tests/` directory structure | -| FFI tests | Present | `src/interface/ffi/test/` | -| Verification tests | Present | `verification/tests/` | -| Aspect modules | Present | `src/aspects/` | - -## What's Covered - -- [x] Test framework infrastructure -- [x] FFI verification layer -- [x] Aspect-based organization - -## Still Missing (for CRG B+) - -- [ ] A2ML language syntax tests -- [ ] VSCode extension integration tests -- [ ] Highlighting tests -- [ ] Performance benchmarks -- [ ] End-to-end editor tests - -## Run Tests - -```bash -cd /var/mnt/eclipse/repos/vscode-a2ml && npm test -``` diff --git a/members/tooling/vscode-a2ml/TOPOLOGY.md b/members/tooling/vscode-a2ml/TOPOLOGY.adoc similarity index 63% rename from members/tooling/vscode-a2ml/TOPOLOGY.md rename to members/tooling/vscode-a2ml/TOPOLOGY.adoc index b056abc..c488efb 100644 --- a/members/tooling/vscode-a2ml/TOPOLOGY.md +++ b/members/tooling/vscode-a2ml/TOPOLOGY.adoc @@ -1,15 +1,15 @@ - - - -# TOPOLOGY.md — vscode-a2ml +== TOPOLOGY.md — vscode-a2ml -## Purpose +=== Purpose -VS Code extension providing syntax highlighting, language configuration, and snippets for A2ML (AI-to-Machine Language) files. Enables editor support for `.a2ml` manifests used across RSR repos. Published to the VS Code marketplace (MPL-2.0 required by platform). +VS Code extension providing syntax highlighting, language configuration, +and snippets for A2ML (AI-to-Machine Language) files. Enables editor +support for `+.a2ml+` manifests used across RSR repos. Published to the +VS Code marketplace (MPL-2.0 required by platform). -## Module Map +=== Module Map -``` +.... vscode-a2ml/ ├── syntaxes/ # TextMate grammar for A2ML syntax highlighting ├── snippets/ # Code snippets for common A2ML patterns @@ -18,12 +18,12 @@ vscode-a2ml/ ├── language-configuration.json # Bracket matching, comment config ├── package.json # VS Code extension manifest └── docs/ # Extension documentation -``` +.... -## Data Flow +=== Data Flow -``` +.... [.a2ml file opened] ──► [syntaxes/ grammar] ──► [syntax highlighting] └──► [snippets/] ──► [completions] └──► [language-config] ──► [bracket/comment behaviour] -``` +.... diff --git a/members/tooling/vscode-a2ml/docs/reports/audit/audit-2026-04-15-post.adoc b/members/tooling/vscode-a2ml/docs/reports/audit/audit-2026-04-15-post.adoc new file mode 100644 index 0000000..3ce0753 --- /dev/null +++ b/members/tooling/vscode-a2ml/docs/reports/audit/audit-2026-04-15-post.adoc @@ -0,0 +1,39 @@ +== POST-audit status report + +Repo: vscode-a2ml Actions taken: - Added TS blocker workflow - Added +NPM/Bun blocker workflow - Managed lockfiles - Synced repo (Dependabot, +.scm, Justfile) Remaining findings: \{ "`program_path`": "`.`", +"`language`": "`shell`", "`frameworks`": [], "`weak_points`": [ \{ +"`category`": "`UncheckedError`", "`location`": +"`.machine_readable/contractiles/k9/template-hunt.k9.ncl`", "`file`": +"`.machine_readable/contractiles/k9/template-hunt.k9.ncl`", +"`severity`": "`Low`", "`description`": "`14 TODO/FIXME/HACK markers in +.machine_readable/contractiles/k9/template-hunt.k9.ncl`", +"`recommended_attack`": [ "`cpu`" ] }, \{ "`category`": "`SupplyChain`", +"`location`": "`flake.guix`", "`file`": "`flake.guix`", "`severity`": +"`High`", "`description`": "`flake.guix declares inputs without narHash, +rev pinning, or sibling flake.lock — dependency revision is unpinned in +flake.guix`", "`recommended_attack`": [] } ], "`statistics`": \{ +"`total_lines`": 2483, "`unsafe_blocks`": 0, "`panic_sites`": 0, +"`unwrap_calls`": 0, "`allocation_sites`": 1, "`io_operations`": 4, +"`threading_constructs`": 2 }, "`file_statistics`": [ \{ "`file_path`": +"`flake.guix`", "`lines`": 170, "`unsafe_blocks`": 0, "`panic_sites`": +0, "`unwrap_calls`": 0, "`allocation_sites`": 0, "`io_operations`": 1, +"`threading_constructs`": 0 }, \{ "`file_path`": +"`src/interface/ffi/src/main.zig`", "`lines`": 274, "`unsafe_blocks`": +0, "`panic_sites`": 0, "`unwrap_calls`": 0, "`allocation_sites`": 1, +"`io_operations`": 0, "`threading_constructs`": 0 }, \{ "`file_path`": +"`src/interface/ffi/test/integration_test.zig`", "`lines`": 182, +"`unsafe_blocks`": 0, "`panic_sites`": 0, "`unwrap_calls`": 0, +"`allocation_sites`": 0, "`io_operations`": 0, "`threading_constructs`": +2 }, \{ "`file_path`": "`setup.sh`", "`lines`": 278, "`unsafe_blocks`": +0, "`panic_sites`": 0, "`unwrap_calls`": 0, "`allocation_sites`": 0, +"`io_operations`": 3, "`threading_constructs`": 0 } ], +"`recommended_attacks`": [ "`cpu`" ], "`dependency_graph`": \{ +"`edges`": [ \{ "`from`": "`flake.guix`", "`to`": "`setup.sh`", +"`relation`": "`shared_dir:`", "`weight`": 1.0 } ] }, "`taint_matrix`": +\{ "`rows`": [ \{ "`source_category`": "`UncheckedError`", +"`sink_axis`": "`cpu`", "`severity_value`": 1.0, "`files`": [ +"`.machine_readable/contractiles/k9/template-hunt.k9.ncl`" ], +"`frameworks`": [], "`relation`": "`UncheckedError->Cpu`" } ] } } CRG +Grade: D diff --git a/members/tooling/vscode-a2ml/docs/reports/audit/audit-2026-04-15-post.md b/members/tooling/vscode-a2ml/docs/reports/audit/audit-2026-04-15-post.md deleted file mode 100644 index 2da1e7b..0000000 --- a/members/tooling/vscode-a2ml/docs/reports/audit/audit-2026-04-15-post.md +++ /dev/null @@ -1,111 +0,0 @@ -# POST-audit status report -Repo: vscode-a2ml -Actions taken: -- Added TS blocker workflow -- Added NPM/Bun blocker workflow -- Managed lockfiles -- Synced repo (Dependabot, .scm, Justfile) -Remaining findings: { - "program_path": ".", - "language": "shell", - "frameworks": [], - "weak_points": [ - { - "category": "UncheckedError", - "location": ".machine_readable/contractiles/k9/template-hunt.k9.ncl", - "file": ".machine_readable/contractiles/k9/template-hunt.k9.ncl", - "severity": "Low", - "description": "14 TODO/FIXME/HACK markers in .machine_readable/contractiles/k9/template-hunt.k9.ncl", - "recommended_attack": [ - "cpu" - ] - }, - { - "category": "SupplyChain", - "location": "flake.guix", - "file": "flake.guix", - "severity": "High", - "description": "flake.guix declares inputs without narHash, rev pinning, or sibling flake.lock — dependency revision is unpinned in flake.guix", - "recommended_attack": [] - } - ], - "statistics": { - "total_lines": 2483, - "unsafe_blocks": 0, - "panic_sites": 0, - "unwrap_calls": 0, - "allocation_sites": 1, - "io_operations": 4, - "threading_constructs": 2 - }, - "file_statistics": [ - { - "file_path": "flake.guix", - "lines": 170, - "unsafe_blocks": 0, - "panic_sites": 0, - "unwrap_calls": 0, - "allocation_sites": 0, - "io_operations": 1, - "threading_constructs": 0 - }, - { - "file_path": "src/interface/ffi/src/main.zig", - "lines": 274, - "unsafe_blocks": 0, - "panic_sites": 0, - "unwrap_calls": 0, - "allocation_sites": 1, - "io_operations": 0, - "threading_constructs": 0 - }, - { - "file_path": "src/interface/ffi/test/integration_test.zig", - "lines": 182, - "unsafe_blocks": 0, - "panic_sites": 0, - "unwrap_calls": 0, - "allocation_sites": 0, - "io_operations": 0, - "threading_constructs": 2 - }, - { - "file_path": "setup.sh", - "lines": 278, - "unsafe_blocks": 0, - "panic_sites": 0, - "unwrap_calls": 0, - "allocation_sites": 0, - "io_operations": 3, - "threading_constructs": 0 - } - ], - "recommended_attacks": [ - "cpu" - ], - "dependency_graph": { - "edges": [ - { - "from": "flake.guix", - "to": "setup.sh", - "relation": "shared_dir:", - "weight": 1.0 - } - ] - }, - "taint_matrix": { - "rows": [ - { - "source_category": "UncheckedError", - "sink_axis": "cpu", - "severity_value": 1.0, - "files": [ - ".machine_readable/contractiles/k9/template-hunt.k9.ncl" - ], - "frameworks": [], - "relation": "UncheckedError->Cpu" - } - ] - } -} -CRG Grade: D diff --git a/members/tooling/vscode-a2ml/docs/reports/audit/audit-2026-04-15-pre.adoc b/members/tooling/vscode-a2ml/docs/reports/audit/audit-2026-04-15-pre.adoc new file mode 100644 index 0000000..a748465 --- /dev/null +++ b/members/tooling/vscode-a2ml/docs/reports/audit/audit-2026-04-15-pre.adoc @@ -0,0 +1,4 @@ +== PRE-audit status report + +Repo: vscode-a2ml TS Blocker: yes NPM/Bun Blocker: yes deno.lock: no +Cargo.lock: no diff --git a/members/tooling/vscode-a2ml/docs/reports/audit/audit-2026-04-15-pre.md b/members/tooling/vscode-a2ml/docs/reports/audit/audit-2026-04-15-pre.md deleted file mode 100644 index e6a6dab..0000000 --- a/members/tooling/vscode-a2ml/docs/reports/audit/audit-2026-04-15-pre.md +++ /dev/null @@ -1,6 +0,0 @@ -# PRE-audit status report -Repo: vscode-a2ml -TS Blocker: yes -NPM/Bun Blocker: yes -deno.lock: no -Cargo.lock: no diff --git a/members/tooling/vscode-a2ml/llm-warmup-dev.adoc b/members/tooling/vscode-a2ml/llm-warmup-dev.adoc new file mode 100644 index 0000000..54f6bf2 --- /dev/null +++ b/members/tooling/vscode-a2ml/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — vscode-a2ml (Developer) + +=== What is vscode-a2ml? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/members/tooling/vscode-a2ml/llm-warmup-dev.md b/members/tooling/vscode-a2ml/llm-warmup-dev.md deleted file mode 100644 index 5b1e446..0000000 --- a/members/tooling/vscode-a2ml/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — vscode-a2ml (Developer) - -## What is vscode-a2ml? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/members/tooling/vscode-a2ml/llm-warmup-user.adoc b/members/tooling/vscode-a2ml/llm-warmup-user.adoc new file mode 100644 index 0000000..f6cd6d4 --- /dev/null +++ b/members/tooling/vscode-a2ml/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — vscode-a2ml (User) + +=== What is vscode-a2ml? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/members/tooling/vscode-a2ml/llm-warmup-user.md b/members/tooling/vscode-a2ml/llm-warmup-user.md deleted file mode 100644 index e29813e..0000000 --- a/members/tooling/vscode-a2ml/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — vscode-a2ml (User) - -## What is vscode-a2ml? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/rs/ARCHITECTURE.adoc b/rs/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/rs/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/rs/ARCHITECTURE.md b/rs/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/rs/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/rs/CHANGELOG.adoc b/rs/CHANGELOG.adoc new file mode 100644 index 0000000..b7cab79 --- /dev/null +++ b/rs/CHANGELOG.adoc @@ -0,0 +1,13 @@ +== Changelog + +All notable changes to this project will be documented in this file. + +The format is based on https://keepachangelog.com/en/1.1.0/[Keep a +Changelog], and this project adheres to +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Added (2026-04-04) + +* Enhanced A2ML validation tests from session 9 dogfooding integration diff --git a/rs/CHANGELOG.md b/rs/CHANGELOG.md deleted file mode 100644 index 3f312c4..0000000 --- a/rs/CHANGELOG.md +++ /dev/null @@ -1,14 +0,0 @@ -# Changelog - -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - - - - -## [Unreleased] - -### Added (2026-04-04) -- Enhanced A2ML validation tests from session 9 dogfooding integration diff --git a/rs/CODE_OF_CONDUCT.adoc b/rs/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/rs/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/rs/CODE_OF_CONDUCT.md b/rs/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/rs/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/rs/CONTRIBUTING.adoc b/rs/CONTRIBUTING.adoc new file mode 100644 index 0000000..dd089ae --- /dev/null +++ b/rs/CONTRIBUTING.adoc @@ -0,0 +1,71 @@ +== Contributing + +Thank you for your interest in contributing! We follow a "`Dual-Track`" +architecture where human-readable documentation lives in the root and +machine-readable policies live in `+.machine_readable/+`. + +=== How to Contribute + +We welcome contributions in many forms: + +* *Code:* Improving the core stack or extensions +* *Documentation:* Enhancing docs or AI manifests +* *Testing:* Adding property-based tests or formal proofs +* *Bug reports:* Filing clear, reproducible issues + +=== Getting Started + +[arabic] +. *Read the AI Manifest:* Start with `+0-AI-MANIFEST.a2ml+` (if present) +to understand the repository structure. +. *Environment:* Use `+guix develop+` or `+direnv allow+` to set up your +tools. +. *Task Runner:* Use `+just+` to see available commands +(`+just --list+`). + +=== Development Workflow + +==== Branch Naming + +.... +docs/short-description # Documentation +test/what-added # Test additions +feat/short-description # New features +fix/issue-number-description # Bug fixes +refactor/what-changed # Code improvements +security/what-fixed # Security fixes +.... + +==== Commit Messages + +We follow https://www.conventionalcommits.org/[Conventional Commits]: + +.... +(): + +[optional body] + +[optional footer] +.... + +Types: `+feat+`, `+fix+`, `+docs+`, `+test+`, `+refactor+`, `+ci+`, +`+chore+`, `+security+` + +=== Reporting Bugs + +Before reporting: 1. Search existing issues 2. Check if it’s already +fixed in `+main+` + +When reporting, include: - Clear, descriptive title - Environment +details (OS, versions, toolchain) - Steps to reproduce - Expected vs +actual behaviour + +=== Code of Conduct + +All contributors are expected to adhere to our +link:CODE_OF_CONDUCT.md[Code of Conduct]. + +=== License + +By contributing, you agree that your contributions will be licensed +under the same license as the project (see LICENSE). diff --git a/rs/CONTRIBUTING.md b/rs/CONTRIBUTING.md deleted file mode 100644 index 90e87dc..0000000 --- a/rs/CONTRIBUTING.md +++ /dev/null @@ -1,66 +0,0 @@ - -# Contributing - -Thank you for your interest in contributing! We follow a "Dual-Track" architecture where human-readable documentation lives in the root and machine-readable policies live in `.machine_readable/`. - -## How to Contribute - -We welcome contributions in many forms: - -- **Code:** Improving the core stack or extensions -- **Documentation:** Enhancing docs or AI manifests -- **Testing:** Adding property-based tests or formal proofs -- **Bug reports:** Filing clear, reproducible issues - -## Getting Started - -1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` (if present) to understand the repository structure. -2. **Environment:** Use `guix develop` or `direnv allow` to set up your tools. -3. **Task Runner:** Use `just` to see available commands (`just --list`). - -## Development Workflow - -### Branch Naming - -``` -docs/short-description # Documentation -test/what-added # Test additions -feat/short-description # New features -fix/issue-number-description # Bug fixes -refactor/what-changed # Code improvements -security/what-fixed # Security fixes -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): - -``` -(): - -[optional body] - -[optional footer] -``` - -Types: `feat`, `fix`, `docs`, `test`, `refactor`, `ci`, `chore`, `security` - -## Reporting Bugs - -Before reporting: -1. Search existing issues -2. Check if it's already fixed in `main` - -When reporting, include: -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour - -## Code of Conduct - -All contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). - -## License - -By contributing, you agree that your contributions will be licensed under the same license as the project (see [LICENSE](LICENSE)). diff --git a/rs/GOVERNANCE.adoc b/rs/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/rs/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/rs/GOVERNANCE.md b/rs/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/rs/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/rs/README.adoc b/rs/README.adoc new file mode 100644 index 0000000..4d966f3 --- /dev/null +++ b/rs/README.adoc @@ -0,0 +1,67 @@ +Rust parser and renderer for A2ML (Attested Markup Language) — the +structured markup format used across the hyperpolymath estate for +AI-agent communication, machine state files, and provenance-tracked +documentation. + +== Overview + +A2ML extends a Markdown-like surface syntax with two first-class +constructs: + +* `+@directives+` — single-line machine-readable metadata prefixed with +`+@+` +* `+!attest+` blocks — record identity, role, and trust-level on any +piece of content, enabling provenance tracking across AI-agent and human +review chains + +`+a2ml-rs+` implements: + +* `+src/parser.rs+` — line-oriented state machine: headings, directives, +attestation blocks, fenced code, block quotes, ordered/unordered lists. +Entry points: `+parse()+` and `+parse_file()+`. +* `+src/renderer.rs+` — serialises a `+Document+` AST back to canonical +A2ML, making round-trips deterministic. +* `+src/types.rs+` — core types: `+Document+`, `+Block+`, `+Inline+`, +`+Directive+`, `+Attestation+`, `+TrustLevel+` (Unverified → Automated → +Reviewed → Verified), `+Manifest+`. +* `+src/error.rs+` — `+A2mlError+`: `+ParseError+`, `+Io+`, +`+RenderError+`. + +The crate root is `+#![forbid(unsafe_code)]+`. Dependencies: +`+serde+`/`+serde_derive+` for serialisation, `+thiserror+` for error +types, `+criterion+` for benchmarks only. + +== Usage + +[source,rust] +---- +use a2ml::{parse, render}; + +let doc = parse(input_str)?; +let output = render(&doc)?; +---- + +== Attestation Trust Levels + +[width="100%",cols="20%,80%",options="header",] +|=== +|Level |Meaning +|`+Unverified+` |No review — raw agent or tool output +|`+Automated+` |Processed by a pipeline without human review +|`+Reviewed+` |Human-reviewed (claimed, not cryptographically proved) +|`+Verified+` |Formally verified or cryptographically attested +|=== + +Attestations are syntactic declarations, not cryptographic signatures. +Signature verification belongs in the Groove protocol stack. + +== Related + +* https://github.com/hyperpolymath/pandoc-a2ml[pandoc-a2ml] — Pandoc +reader/writer for A2ML +* https://github.com/hyperpolymath/a2ml-haskell[a2ml-haskell] — Haskell +implementation + +== License + +MPL-2.0. See LICENSE. diff --git a/rs/README.md b/rs/README.md deleted file mode 100644 index 9ad08e1..0000000 --- a/rs/README.md +++ /dev/null @@ -1,73 +0,0 @@ - - -Rust parser and renderer for A2ML (Attested Markup Language) — the -structured markup format used across the hyperpolymath estate for -AI-agent communication, machine state files, and provenance-tracked -documentation. - -# Overview - -A2ML extends a Markdown-like surface syntax with two first-class -constructs: - -- `@directives` — single-line machine-readable metadata prefixed with - `@` - -- `!attest` blocks — record identity, role, and trust-level on any piece - of content, enabling provenance tracking across AI-agent and human - review chains - -`a2ml-rs` implements: - -- `src/parser.rs` — line-oriented state machine: headings, directives, - attestation blocks, fenced code, block quotes, ordered/unordered - lists. Entry points: `parse()` and `parse_file()`. - -- `src/renderer.rs` — serialises a `Document` AST back to canonical - A2ML, making round-trips deterministic. - -- `src/types.rs` — core types: `Document`, `Block`, `Inline`, - `Directive`, `Attestation`, `TrustLevel` (Unverified → Automated → - Reviewed → Verified), `Manifest`. - -- `src/error.rs` — `A2mlError`: `ParseError`, `Io`, `RenderError`. - -The crate root is `#![forbid(unsafe_code)]`. Dependencies: -`serde`/`serde_derive` for serialisation, `thiserror` for error types, -`criterion` for benchmarks only. - -# Usage - -```rust -use a2ml::{parse, render}; - -let doc = parse(input_str)?; -let output = render(&doc)?; -``` - -# Attestation Trust Levels - -| Level | Meaning | -|--------------|--------------------------------------------------------| -| `Unverified` | No review — raw agent or tool output | -| `Automated` | Processed by a pipeline without human review | -| `Reviewed` | Human-reviewed (claimed, not cryptographically proved) | -| `Verified` | Formally verified or cryptographically attested | - -Attestations are syntactic declarations, not cryptographic signatures. -Signature verification belongs in the Groove protocol stack. - -# Related - -- [pandoc-a2ml](https://github.com/hyperpolymath/pandoc-a2ml) — Pandoc - reader/writer for A2ML - -- [a2ml-haskell](https://github.com/hyperpolymath/a2ml-haskell) — - Haskell implementation - -# License - -MPL-2.0. See [LICENSE](LICENSE). diff --git a/rs/SECURITY.adoc b/rs/SECURITY.adoc new file mode 100644 index 0000000..e47fdd9 --- /dev/null +++ b/rs/SECURITY.adoc @@ -0,0 +1,16 @@ +== Security Policy + +=== Reporting a Vulnerability + +If you discover a security vulnerability, please report it responsibly. + +*Email:* j.d.a.jewell@open.ac.uk + +*Please include:* - Description of the vulnerability - Steps to +reproduce - Potential impact + +*Response timeline:* - Acknowledgement within 48 hours - Initial +assessment within 7 days - Fix or mitigation within 90 days + +*Safe harbour:* We will not pursue legal action against security +researchers who follow responsible disclosure. diff --git a/rs/SECURITY.md b/rs/SECURITY.md deleted file mode 100644 index 5c4d5e9..0000000 --- a/rs/SECURITY.md +++ /dev/null @@ -1,20 +0,0 @@ - -# Security Policy - -## Reporting a Vulnerability - -If you discover a security vulnerability, please report it responsibly. - -**Email:** j.d.a.jewell@open.ac.uk - -**Please include:** -- Description of the vulnerability -- Steps to reproduce -- Potential impact - -**Response timeline:** -- Acknowledgement within 48 hours -- Initial assessment within 7 days -- Fix or mitigation within 90 days - -**Safe harbour:** We will not pursue legal action against security researchers who follow responsible disclosure. diff --git a/rs/TEST-NEEDS.adoc b/rs/TEST-NEEDS.adoc new file mode 100644 index 0000000..603cc5b --- /dev/null +++ b/rs/TEST-NEEDS.adoc @@ -0,0 +1,85 @@ +== Test & Benchmark Requirements + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current State + +* Unit tests: 14 pass / 0 fail (11 unit + 3 doc-tests) +* Integration tests: NONE +* E2E tests: NONE +* Benchmarks: NONE (benchmark dir has only README placeholder) +* panic-attack scan: NEVER RUN (feature dir exists but no report) + +=== What’s Missing + +==== Point-to-Point (P2P) + +* lib.rs — 11 inline tests exist, reasonable for module size +* parser.rs — tests exist but edge cases likely missing (malformed +input, unicode, deeply nested structures) +* renderer.rs — likely untested or minimally tested +* types.rs — likely untested +* error.rs — error paths and formatting not tested +* tests/fuzz/ contains only placeholder.txt — no fuzzing + +==== End-to-End (E2E) + +* Parse real-world A2ML files from other hyperpolymath repos +* Round-trip (parse -> render -> parse) equality check +* Cross-implementation compatibility with a2ml_ex, a2ml_gleam, +a2ml-haskell +* CLI integration if binary exists + +==== Aspect Tests + +* [ ] Security (untrusted A2ML input, DoS via deeply nested structures) +* [ ] Performance (large document parsing) +* [ ] Concurrency (N/A for library) +* [ ] Error handling (all error.rs variants reachable and tested) +* [ ] Accessibility (N/A) + +==== Build & Execution + +* [x] cargo build — clean +* [x] cargo test — 14 pass, 0 fail +* [ ] Self-diagnostic — none + +==== Benchmarks Needed + +* Parse throughput (Criterion benchmarks) +* Memory allocation profile +* Comparison vs a2ml_ex (BEAM) and a2ml-deno (V8) + +==== Self-Tests + +* [ ] panic-attack assail on own repo +* [ ] Built-in doctor/check command (if applicable) + +=== Priority + +* *MEDIUM* — 5 source files with 14 tests is decent ratio but renderer +and types likely lack coverage. Fuzz directory is empty. No benchmarks +despite benchmark dir existing. As the Rust reference implementation, +this should have the most comprehensive tests of all A2ML libraries. + +=== Session 9 additions (2026-04-04) + +==== What Was Added + +[width="100%",cols="22%,44%,34%",options="header",] +|=== +|Area |Tests Added |Location +|Benchmarks |Extended `+benches/a2ml_bench.rs+` with +`+attestation_benches+` group: 4 functions: +`+bench_parse_attestation_heavy+`, `+bench_parse_directive_heavy+`, +`+bench_attestation_access+`, `+bench_render_attestation_heavy+` +|`+benches/a2ml_bench.rs+` +|=== + +==== Updated Test Counts + +[width="100%",cols="33%,31%,36%",options="header",] +|=== +|Suite |Count |Status +|Benchmarks (attestation) |4 new |Added to attestation_benches group +|=== diff --git a/rs/TEST-NEEDS.md b/rs/TEST-NEEDS.md deleted file mode 100644 index 637bb7f..0000000 --- a/rs/TEST-NEEDS.md +++ /dev/null @@ -1,63 +0,0 @@ -# Test & Benchmark Requirements - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current State -- Unit tests: 14 pass / 0 fail (11 unit + 3 doc-tests) -- Integration tests: NONE -- E2E tests: NONE -- Benchmarks: NONE (benchmark dir has only README placeholder) -- panic-attack scan: NEVER RUN (feature dir exists but no report) - -## What's Missing -### Point-to-Point (P2P) -- lib.rs — 11 inline tests exist, reasonable for module size -- parser.rs — tests exist but edge cases likely missing (malformed input, unicode, deeply nested structures) -- renderer.rs — likely untested or minimally tested -- types.rs — likely untested -- error.rs — error paths and formatting not tested -- tests/fuzz/ contains only placeholder.txt — no fuzzing - -### End-to-End (E2E) -- Parse real-world A2ML files from other hyperpolymath repos -- Round-trip (parse -> render -> parse) equality check -- Cross-implementation compatibility with a2ml_ex, a2ml_gleam, a2ml-haskell -- CLI integration if binary exists - -### Aspect Tests -- [ ] Security (untrusted A2ML input, DoS via deeply nested structures) -- [ ] Performance (large document parsing) -- [ ] Concurrency (N/A for library) -- [ ] Error handling (all error.rs variants reachable and tested) -- [ ] Accessibility (N/A) - -### Build & Execution -- [x] cargo build — clean -- [x] cargo test — 14 pass, 0 fail -- [ ] Self-diagnostic — none - -### Benchmarks Needed -- Parse throughput (Criterion benchmarks) -- Memory allocation profile -- Comparison vs a2ml_ex (BEAM) and a2ml-deno (V8) - -### Self-Tests -- [ ] panic-attack assail on own repo -- [ ] Built-in doctor/check command (if applicable) - -## Priority -- **MEDIUM** — 5 source files with 14 tests is decent ratio but renderer and types likely lack coverage. Fuzz directory is empty. No benchmarks despite benchmark dir existing. As the Rust reference implementation, this should have the most comprehensive tests of all A2ML libraries. - -## Session 9 additions (2026-04-04) - -### What Was Added - -| Area | Tests Added | Location | -|------|-------------|----------| -| Benchmarks | Extended `benches/a2ml_bench.rs` with `attestation_benches` group: 4 functions: `bench_parse_attestation_heavy`, `bench_parse_directive_heavy`, `bench_attestation_access`, `bench_render_attestation_heavy` | `benches/a2ml_bench.rs` | - -### Updated Test Counts - -| Suite | Count | Status | -|-------|-------|--------| -| Benchmarks (attestation) | 4 new | Added to attestation_benches group | diff --git a/rs/TOPOLOGY.md b/rs/TOPOLOGY.adoc similarity index 62% rename from rs/TOPOLOGY.md rename to rs/TOPOLOGY.adoc index 5240a53..254ed8c 100644 --- a/rs/TOPOLOGY.md +++ b/rs/TOPOLOGY.adoc @@ -1,14 +1,16 @@ - - -# TOPOLOGY.md — a2ml-rs +== TOPOLOGY.md — a2ml-rs -## Purpose +=== Purpose -Rust parser and renderer for A2ML (Attested Markup Language), a structured markup format with built-in attestation provenance, directive metadata, and trust-level tracking. Provides a complete parse-render round-trip with typed AST. Intended for use in CI tooling, validators, and server-side pipelines. +Rust parser and renderer for A2ML (Attested Markup Language), a +structured markup format with built-in attestation provenance, directive +metadata, and trust-level tracking. Provides a complete parse-render +round-trip with typed AST. Intended for use in CI tooling, validators, +and server-side pipelines. -## Module Map +=== Module Map -``` +.... a2ml-rs/ ├── src/ │ ├── lib.rs # Public crate API @@ -20,12 +22,12 @@ a2ml-rs/ ├── examples/ # Usage examples ├── Cargo.toml └── container/ # Containerfile for CI -``` +.... -## Data Flow +=== Data Flow -``` +.... [A2ML text] ──► [parser.rs] ──► [Typed AST] ──► [renderer.rs] ──► [A2ML text] │ [types.rs / error.rs] -``` +.... diff --git a/rs/llm-warmup-dev.adoc b/rs/llm-warmup-dev.adoc new file mode 100644 index 0000000..b96e9d0 --- /dev/null +++ b/rs/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — a2ml-rs (Developer) + +=== What is a2ml-rs? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/rs/llm-warmup-dev.md b/rs/llm-warmup-dev.md deleted file mode 100644 index 887acf4..0000000 --- a/rs/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — a2ml-rs (Developer) - -## What is a2ml-rs? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/rs/llm-warmup-user.adoc b/rs/llm-warmup-user.adoc new file mode 100644 index 0000000..1c5a819 --- /dev/null +++ b/rs/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — a2ml-rs (User) + +=== What is a2ml-rs? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/rs/llm-warmup-user.md b/rs/llm-warmup-user.md deleted file mode 100644 index f79c345..0000000 --- a/rs/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — a2ml-rs (User) - -## What is a2ml-rs? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/showcase/ARCHITECTURE.adoc b/showcase/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/showcase/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/showcase/ARCHITECTURE.md b/showcase/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/showcase/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/showcase/CODE_OF_CONDUCT.adoc b/showcase/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/showcase/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/showcase/CODE_OF_CONDUCT.md b/showcase/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/showcase/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/showcase/CONTRIBUTING.adoc b/showcase/CONTRIBUTING.adoc new file mode 100644 index 0000000..dd089ae --- /dev/null +++ b/showcase/CONTRIBUTING.adoc @@ -0,0 +1,71 @@ +== Contributing + +Thank you for your interest in contributing! We follow a "`Dual-Track`" +architecture where human-readable documentation lives in the root and +machine-readable policies live in `+.machine_readable/+`. + +=== How to Contribute + +We welcome contributions in many forms: + +* *Code:* Improving the core stack or extensions +* *Documentation:* Enhancing docs or AI manifests +* *Testing:* Adding property-based tests or formal proofs +* *Bug reports:* Filing clear, reproducible issues + +=== Getting Started + +[arabic] +. *Read the AI Manifest:* Start with `+0-AI-MANIFEST.a2ml+` (if present) +to understand the repository structure. +. *Environment:* Use `+guix develop+` or `+direnv allow+` to set up your +tools. +. *Task Runner:* Use `+just+` to see available commands +(`+just --list+`). + +=== Development Workflow + +==== Branch Naming + +.... +docs/short-description # Documentation +test/what-added # Test additions +feat/short-description # New features +fix/issue-number-description # Bug fixes +refactor/what-changed # Code improvements +security/what-fixed # Security fixes +.... + +==== Commit Messages + +We follow https://www.conventionalcommits.org/[Conventional Commits]: + +.... +(): + +[optional body] + +[optional footer] +.... + +Types: `+feat+`, `+fix+`, `+docs+`, `+test+`, `+refactor+`, `+ci+`, +`+chore+`, `+security+` + +=== Reporting Bugs + +Before reporting: 1. Search existing issues 2. Check if it’s already +fixed in `+main+` + +When reporting, include: - Clear, descriptive title - Environment +details (OS, versions, toolchain) - Steps to reproduce - Expected vs +actual behaviour + +=== Code of Conduct + +All contributors are expected to adhere to our +link:CODE_OF_CONDUCT.md[Code of Conduct]. + +=== License + +By contributing, you agree that your contributions will be licensed +under the same license as the project (see LICENSE). diff --git a/showcase/CONTRIBUTING.md b/showcase/CONTRIBUTING.md deleted file mode 100644 index 90e87dc..0000000 --- a/showcase/CONTRIBUTING.md +++ /dev/null @@ -1,66 +0,0 @@ - -# Contributing - -Thank you for your interest in contributing! We follow a "Dual-Track" architecture where human-readable documentation lives in the root and machine-readable policies live in `.machine_readable/`. - -## How to Contribute - -We welcome contributions in many forms: - -- **Code:** Improving the core stack or extensions -- **Documentation:** Enhancing docs or AI manifests -- **Testing:** Adding property-based tests or formal proofs -- **Bug reports:** Filing clear, reproducible issues - -## Getting Started - -1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` (if present) to understand the repository structure. -2. **Environment:** Use `guix develop` or `direnv allow` to set up your tools. -3. **Task Runner:** Use `just` to see available commands (`just --list`). - -## Development Workflow - -### Branch Naming - -``` -docs/short-description # Documentation -test/what-added # Test additions -feat/short-description # New features -fix/issue-number-description # Bug fixes -refactor/what-changed # Code improvements -security/what-fixed # Security fixes -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): - -``` -(): - -[optional body] - -[optional footer] -``` - -Types: `feat`, `fix`, `docs`, `test`, `refactor`, `ci`, `chore`, `security` - -## Reporting Bugs - -Before reporting: -1. Search existing issues -2. Check if it's already fixed in `main` - -When reporting, include: -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour - -## Code of Conduct - -All contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). - -## License - -By contributing, you agree that your contributions will be licensed under the same license as the project (see [LICENSE](LICENSE)). diff --git a/showcase/GOVERNANCE.adoc b/showcase/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/showcase/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/showcase/GOVERNANCE.md b/showcase/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/showcase/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/showcase/README.adoc b/showcase/README.adoc new file mode 100644 index 0000000..edc8f11 --- /dev/null +++ b/showcase/README.adoc @@ -0,0 +1,21 @@ +Showcase examples and templates for A2ML (AI Attestation Markup +Language). + +https://securityscorecards.dev/viewer/?uri=github.com/hyperpolymath/a2ml-showcase[image:https://api.securityscorecards.dev/projects/github.com/hyperpolymath/a2ml-showcase/badge[OpenSSF +Scorecard]] + +== About + +This repository contains example A2ML documents, templates, and rendered +output demonstrating the capabilities of the A2ML format. It is a +content/showcase repository — there is no executable code. + +== Structure + +* `+content/+` — A2ML source documents +* `+output/+` — Rendered output +* `+template.html+` — HTML rendering template + +== License + +MPL-2.0. See LICENSE. diff --git a/showcase/README.md b/showcase/README.md deleted file mode 100644 index 58d8a22..0000000 --- a/showcase/README.md +++ /dev/null @@ -1,27 +0,0 @@ - - -Showcase examples and templates for A2ML (AI Attestation Markup -Language). - -[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/hyperpolymath/a2ml-showcase/badge)](https://securityscorecards.dev/viewer/?uri=github.com/hyperpolymath/a2ml-showcase) - -# About - -This repository contains example A2ML documents, templates, and rendered -output demonstrating the capabilities of the A2ML format. It is a -content/showcase repository — there is no executable code. - -# Structure - -- `content/` — A2ML source documents - -- `output/` — Rendered output - -- `template.html` — HTML rendering template - -# License - -MPL-2.0. See [LICENSE](LICENSE). diff --git a/showcase/SECURITY.adoc b/showcase/SECURITY.adoc new file mode 100644 index 0000000..cac7186 --- /dev/null +++ b/showcase/SECURITY.adoc @@ -0,0 +1,16 @@ +== Security Policy + +=== Reporting a Vulnerability + +Please report security vulnerabilities to j.d.a.jewell@open.ac.uk. + +We will acknowledge receipt within 48 hours and provide a detailed +response within 7 days. + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|Latest |Yes +|=== diff --git a/showcase/SECURITY.md b/showcase/SECURITY.md deleted file mode 100644 index c1ca2fc..0000000 --- a/showcase/SECURITY.md +++ /dev/null @@ -1,16 +0,0 @@ - - - -# Security Policy - -## Reporting a Vulnerability - -Please report security vulnerabilities to j.d.a.jewell@open.ac.uk. - -We will acknowledge receipt within 48 hours and provide a detailed response within 7 days. - -## Supported Versions - -| Version | Supported | -|---------|-----------| -| Latest | Yes | diff --git a/showcase/TEST-NEEDS.adoc b/showcase/TEST-NEEDS.adoc new file mode 100644 index 0000000..a3b35f3 --- /dev/null +++ b/showcase/TEST-NEEDS.adoc @@ -0,0 +1,183 @@ +== CRG Grade C Test Coverage + +=== CRG Grade: B — ACHIEVED 2026-04-04 + +____ +CRG B achieved 2026-04-04: Validated A2ML manifests from 6 diverse +external repos + ran 18 internal tests. +____ + +=== CRG B Evidence — External Targets + +[width="100%",cols="28%,22%,34%,16%",options="header",] +|=== +|Target Repo |A2ML File |What Was Tested |Result +|gossamer |0-AI-MANIFEST.a2ml |Structural compliance (8 required fields) +|SCORE 8/8 (106 lines, 4851B) + +|boj-server |0-AI-MANIFEST.a2ml |Structural compliance (8 required +fields) |SCORE 8/8 (110 lines, 5036B) + +|echidna |0-AI-MANIFEST.a2ml |Structural compliance (8 required fields) +|SCORE 3/8 (103 lines, 4507B) + +|panic-attacker |0-AI-MANIFEST.a2ml |Structural compliance (8 required +fields) |SCORE 4/8 (119 lines, 4007B) + +|hypatia |0-AI-MANIFEST.a2ml |Structural compliance (8 required fields) +|SCORE 8/8 (117 lines, 5295B) + +|standards |0-AI-MANIFEST.a2ml |Structural compliance (8 required +fields) |SCORE 1/8 (128 lines, 4383B) +|=== + +==== Compliance fields checked + +[arabic] +. `+SPDX-License-Identifier+` header +. `+(manifest ...)+` wrapper +. `+(identity ...)+` section +. `+(purpose ...)+` section +. `+(name ...)+` field +. `+(version ...)+` field +. `+(context ...)+` tiers +. `+(canonical ...)+` locations + +==== Target Details + +*1. gossamer (Gleam/Rust — window manager)* - File: +`+/var/mnt/eclipse/repos/gossamer/0-AI-MANIFEST.a2ml+` - Result: FULL +COMPLIANCE. All 8 structural fields present. Proper S-expression format +with identity, purpose, context-tiers, canonical-locations, and +invariants. + +*2. boj-server (AffineScript/Deno — MCP server)* - File: +`+/var/mnt/eclipse/repos/boj-server/0-AI-MANIFEST.a2ml+` - Result: FULL +COMPLIANCE. All 8 structural fields present. Well-structured manifest +with 110 lines. + +*3. echidna (Rust — theorem prover)* - File: +`+/var/mnt/eclipse/repos/verification-ecosystem/echidna/0-AI-MANIFEST.a2ml+` +- Result: INCOMPLETE (3/8). Has SPDX and context/canonical but uses +non-standard structure missing (manifest), (identity), (purpose), +(name), (version) wrappers. Needs migration to standard A2ML format. + +*4. panic-attacker (Rust — security scanner)* - File: +`+/var/mnt/eclipse/repos/games-ecosystem/panic-attacker/0-AI-MANIFEST.a2ml+` +- Result: INCOMPLETE (4/8). Has SPDX, (manifest), version, canonical but +missing (identity), (purpose), (name) sections. Partially migrated +format. + +*5. hypatia (Elixir/Rust — CI/CD scanner)* - File: +`+/var/mnt/eclipse/repos/verification-ecosystem/hypatia/0-AI-MANIFEST.a2ml+` +- Result: FULL COMPLIANCE. All 8 structural fields present. 117 lines +with comprehensive context tiers. + +*6. standards (Mixed — multi-standard monorepo)* - File: +`+/var/mnt/eclipse/repos/developer-ecosystem/standards/0-AI-MANIFEST.a2ml+` +- Result: MINIMAL (1/8). Large file (128 lines, 4383B) but uses legacy +format without standard S-expression structure. Only canonical locations +present. Needs full rewrite. + +==== Internal test suite also passing + +All 18 internal tests pass (Unit: 4, Smoke: 3, Contract: 2, Aspect: 3, +Property: 2, E2E: 2, Benchmark: 2). + +*Repository:* a2ml-showcase + +*Grade:* C + +*Last Updated:* 2026-04-04 + +=== Overview + +This repository contains A2ML showcase examples and documentation. As a +data/showcase repository with no executable code, tests focus on: - +Valid A2ML example structure - Consistency of formatting - Completeness +of required fields - Documentation accuracy + +=== Test Categories + +[width="100%",cols="33%,21%,25%,21%",options="header",] +|=== +|Category |Count |Status |Notes +|Unit Tests |4 |✓ PASS |File existence, structure, SPDX headers, content +files + +|Smoke Tests |3 |✓ PASS |A2ML syntax, attestation blocks, policy blocks + +|Contract Tests |2 |✓ PASS |Required A2ML fields, valid trust levels + +|Aspect Tests |3 |✓ PASS |Agent naming, formatting consistency, SPDX +consistency + +|Property-Based Tests |2 |✓ PASS |Agent-id declarations, trust level +progression + +|E2E/Reflexive Tests |2 |✓ PASS |Attestation parsing, reference +resolution + +|Benchmarks |2 |✓ PASS |File read performance, example count baseline +|=== + +*Total Test Count:* 18 + +*All Tests Passing:* Yes + +=== Running Tests + +[source,bash] +---- +deno test tests/validate.test.ts +---- + +=== Test Details + +==== Unit Tests (4) + +* Validates all required example files exist +* Checks for SPDX license headers in examples +* Verifies content structure has expected sections +* Confirms markdown files are readable + +==== Smoke Tests (3) + +* Verifies @attestation blocks are syntactically valid +* Checks @policy blocks are present and formatted +* Validates README cross-references + +==== Contract Tests (2) + +* Every attestation must have: agent-id, attested-by, trust-level +* Trust levels must be one of: self-declared, verified, audited + +==== Aspect Tests (3) + +* Agent IDs follow naming convention (lowercase-alphanumeric-hyphens) +* @attestation/@end blocks are balanced +* SPDX headers are consistent across documentation + +==== Property-Based Tests (2) + +* Every declared agent-id must appear in at least one attestation +* Documentation includes all three trust level progression stages + +==== E2E/Reflexive Tests (2) + +* A2ML attestation blocks can be parsed into key-value pairs +* All numbered references [1], [2], etc. are cited in text + +==== Benchmarks (2) + +* File read operations complete in < 100ms +* Contains expected number of documented examples (≥ 3) + +=== Dependencies + +* Deno 1.40+ +* deno_std (assert module) + +=== Future Enhancements + +* [ ] Add schema validation against formal A2ML grammar +* [ ] Validate agent capabilities against registry +* [ ] Check timestamp formats (RFC3339) +* [ ] Verify signature formats diff --git a/showcase/TEST-NEEDS.md b/showcase/TEST-NEEDS.md deleted file mode 100644 index 5604bec..0000000 --- a/showcase/TEST-NEEDS.md +++ /dev/null @@ -1,136 +0,0 @@ -# CRG Grade C Test Coverage - -## CRG Grade: B — ACHIEVED 2026-04-04 - -> CRG B achieved 2026-04-04: Validated A2ML manifests from 6 diverse external repos + ran 18 internal tests. - -## CRG B Evidence — External Targets - -| Target Repo | A2ML File | What Was Tested | Result | -|-------------|-----------|-----------------|--------| -| gossamer | 0-AI-MANIFEST.a2ml | Structural compliance (8 required fields) | SCORE 8/8 (106 lines, 4851B) | -| boj-server | 0-AI-MANIFEST.a2ml | Structural compliance (8 required fields) | SCORE 8/8 (110 lines, 5036B) | -| echidna | 0-AI-MANIFEST.a2ml | Structural compliance (8 required fields) | SCORE 3/8 (103 lines, 4507B) | -| panic-attacker | 0-AI-MANIFEST.a2ml | Structural compliance (8 required fields) | SCORE 4/8 (119 lines, 4007B) | -| hypatia | 0-AI-MANIFEST.a2ml | Structural compliance (8 required fields) | SCORE 8/8 (117 lines, 5295B) | -| standards | 0-AI-MANIFEST.a2ml | Structural compliance (8 required fields) | SCORE 1/8 (128 lines, 4383B) | - -### Compliance fields checked - -1. `SPDX-License-Identifier` header -2. `(manifest ...)` wrapper -3. `(identity ...)` section -4. `(purpose ...)` section -5. `(name ...)` field -6. `(version ...)` field -7. `(context ...)` tiers -8. `(canonical ...)` locations - -### Target Details - -**1. gossamer (Gleam/Rust — window manager)** -- File: `/var/mnt/eclipse/repos/gossamer/0-AI-MANIFEST.a2ml` -- Result: FULL COMPLIANCE. All 8 structural fields present. Proper S-expression format with identity, purpose, context-tiers, canonical-locations, and invariants. - -**2. boj-server (AffineScript/Deno — MCP server)** -- File: `/var/mnt/eclipse/repos/boj-server/0-AI-MANIFEST.a2ml` -- Result: FULL COMPLIANCE. All 8 structural fields present. Well-structured manifest with 110 lines. - -**3. echidna (Rust — theorem prover)** -- File: `/var/mnt/eclipse/repos/verification-ecosystem/echidna/0-AI-MANIFEST.a2ml` -- Result: INCOMPLETE (3/8). Has SPDX and context/canonical but uses non-standard structure missing (manifest), (identity), (purpose), (name), (version) wrappers. Needs migration to standard A2ML format. - -**4. panic-attacker (Rust — security scanner)** -- File: `/var/mnt/eclipse/repos/games-ecosystem/panic-attacker/0-AI-MANIFEST.a2ml` -- Result: INCOMPLETE (4/8). Has SPDX, (manifest), version, canonical but missing (identity), (purpose), (name) sections. Partially migrated format. - -**5. hypatia (Elixir/Rust — CI/CD scanner)** -- File: `/var/mnt/eclipse/repos/verification-ecosystem/hypatia/0-AI-MANIFEST.a2ml` -- Result: FULL COMPLIANCE. All 8 structural fields present. 117 lines with comprehensive context tiers. - -**6. standards (Mixed — multi-standard monorepo)** -- File: `/var/mnt/eclipse/repos/developer-ecosystem/standards/0-AI-MANIFEST.a2ml` -- Result: MINIMAL (1/8). Large file (128 lines, 4383B) but uses legacy format without standard S-expression structure. Only canonical locations present. Needs full rewrite. - -### Internal test suite also passing - -All 18 internal tests pass (Unit: 4, Smoke: 3, Contract: 2, Aspect: 3, Property: 2, E2E: 2, Benchmark: 2). - -**Repository:** a2ml-showcase -**Grade:** C -**Last Updated:** 2026-04-04 - -## Overview - -This repository contains A2ML showcase examples and documentation. As a data/showcase repository with no executable code, tests focus on: -- Valid A2ML example structure -- Consistency of formatting -- Completeness of required fields -- Documentation accuracy - -## Test Categories - -| Category | Count | Status | Notes | -|----------|-------|--------|-------| -| Unit Tests | 4 | ✓ PASS | File existence, structure, SPDX headers, content files | -| Smoke Tests | 3 | ✓ PASS | A2ML syntax, attestation blocks, policy blocks | -| Contract Tests | 2 | ✓ PASS | Required A2ML fields, valid trust levels | -| Aspect Tests | 3 | ✓ PASS | Agent naming, formatting consistency, SPDX consistency | -| Property-Based Tests | 2 | ✓ PASS | Agent-id declarations, trust level progression | -| E2E/Reflexive Tests | 2 | ✓ PASS | Attestation parsing, reference resolution | -| Benchmarks | 2 | ✓ PASS | File read performance, example count baseline | - -**Total Test Count:** 18 -**All Tests Passing:** Yes - -## Running Tests - -```bash -deno test tests/validate.test.ts -``` - -## Test Details - -### Unit Tests (4) -- Validates all required example files exist -- Checks for SPDX license headers in examples -- Verifies content structure has expected sections -- Confirms markdown files are readable - -### Smoke Tests (3) -- Verifies @attestation blocks are syntactically valid -- Checks @policy blocks are present and formatted -- Validates README cross-references - -### Contract Tests (2) -- Every attestation must have: agent-id, attested-by, trust-level -- Trust levels must be one of: self-declared, verified, audited - -### Aspect Tests (3) -- Agent IDs follow naming convention (lowercase-alphanumeric-hyphens) -- @attestation/@end blocks are balanced -- SPDX headers are consistent across documentation - -### Property-Based Tests (2) -- Every declared agent-id must appear in at least one attestation -- Documentation includes all three trust level progression stages - -### E2E/Reflexive Tests (2) -- A2ML attestation blocks can be parsed into key-value pairs -- All numbered references [1], [2], etc. are cited in text - -### Benchmarks (2) -- File read operations complete in < 100ms -- Contains expected number of documented examples (≥ 3) - -## Dependencies - -- Deno 1.40+ -- deno_std (assert module) - -## Future Enhancements - -- [ ] Add schema validation against formal A2ML grammar -- [ ] Validate agent capabilities against registry -- [ ] Check timestamp formats (RFC3339) -- [ ] Verify signature formats diff --git a/showcase/TOPOLOGY.adoc b/showcase/TOPOLOGY.adoc new file mode 100644 index 0000000..5253d01 --- /dev/null +++ b/showcase/TOPOLOGY.adoc @@ -0,0 +1,24 @@ +== TOPOLOGY.md — a2ml-showcase + +=== Purpose + +Content showcase for A2ML (AI Attestation Markup Language): example +documents, templates, and rendered output demonstrating A2ML format +capabilities. No executable code — pure content and documentation repo. +Generated output is produced by the Deno renderer via `+just render+`. + +=== Module Map + +.... +a2ml-showcase/ +├── content/ # A2ML source documents (examples, templates) +├── output/ # Rendered output (HTML, text) +├── deno.json # Deno task runner config +└── template.html # HTML rendering template +.... + +=== Data Flow + +.... +[content/*.a2ml] ──► [a2ml-deno renderer] ──► [output/] +.... diff --git a/showcase/TOPOLOGY.md b/showcase/TOPOLOGY.md deleted file mode 100644 index b3151db..0000000 --- a/showcase/TOPOLOGY.md +++ /dev/null @@ -1,23 +0,0 @@ - - -# TOPOLOGY.md — a2ml-showcase - -## Purpose - -Content showcase for A2ML (AI Attestation Markup Language): example documents, templates, and rendered output demonstrating A2ML format capabilities. No executable code — pure content and documentation repo. Generated output is produced by the Deno renderer via `just render`. - -## Module Map - -``` -a2ml-showcase/ -├── content/ # A2ML source documents (examples, templates) -├── output/ # Rendered output (HTML, text) -├── deno.json # Deno task runner config -└── template.html # HTML rendering template -``` - -## Data Flow - -``` -[content/*.a2ml] ──► [a2ml-deno renderer] ──► [output/] -``` diff --git a/showcase/content/examples.md b/showcase/content/examples.adoc similarity index 86% rename from showcase/content/examples.md rename to showcase/content/examples.adoc index 8ab0a40..aafb669 100644 --- a/showcase/content/examples.md +++ b/showcase/content/examples.adoc @@ -1,18 +1,15 @@ ---- -title: Examples -date: 2026-03-16 -order: 3 ---- +== Examples -# Examples +Real-world A2ML manifests demonstrating the format in practice. Each +example shows a different use case, from minimal declarations to +multi-agent orchestration. -Real-world A2ML manifests demonstrating the format in practice. Each example shows a different use case, from minimal declarations to multi-agent orchestration. +=== 1. Minimal Manifest -## 1. Minimal Manifest +The simplest possible A2ML file. Declares an agent with a single +self-attestation. -The simplest possible A2ML file. Declares an agent with a single self-attestation. - -``` +.... ;; SPDX-License-Identifier: CC-BY-SA-4.0 # Greeter Bot @@ -29,17 +26,20 @@ capabilities: - pr-comment scope: repository @end -``` +.... -This is enough for tooling to identify the agent, understand what it does, and record that its capabilities are self-declared (i.e., not yet independently verified). +This is enough for tooling to identify the agent, understand what it +does, and record that its capabilities are self-declared (i.e., not yet +independently verified). ---- +''''' -## 2. CI/CD Agent Manifest +=== 2. CI/CD Agent Manifest -A GitHub Actions bot that runs in CI pipelines, with a verified attestation from the security team. +A GitHub Actions bot that runs in CI pipelines, with a verified +attestation from the security team. -``` +.... ;; SPDX-License-Identifier: CC-BY-SA-4.0 # rhodibot — Repository Automation Agent @@ -101,15 +101,16 @@ action: allow-execution [1] gitbot-fleet Documentation, https://github.com/hyperpolymath/gitbot-fleet [2] Rhodium Standard Repositories, https://github.com/hyperpolymath/rhodium-standard-repositories @end -``` +.... ---- +''''' -## 3. Security Scanner Manifest +=== 3. Security Scanner Manifest -Hypatia, a neurosymbolic security scanner, declaring its scanning capabilities with an audited attestation. +Hypatia, a neurosymbolic security scanner, declaring its scanning +capabilities with an audited attestation. -``` +.... ;; SPDX-License-Identifier: CC-BY-SA-4.0 # Hypatia — Neurosymbolic Security Scanner @@ -175,15 +176,16 @@ signature: sha256:c91e5a3b0d... [2] OWASP Top 10 for LLM Applications [3] SLSA Build Provenance, https://slsa.dev @end -``` +.... ---- +''''' -## 4. Multi-Agent Orchestration +=== 4. Multi-Agent Orchestration -Multiple agents referencing each other's attestations to establish a trust network for a deployment pipeline. +Multiple agents referencing each other’s attestations to establish a +trust network for a deployment pipeline. -``` +.... ;; SPDX-License-Identifier: CC-BY-SA-4.0 # Deployment Pipeline — Agent Trust Network @@ -262,6 +264,9 @@ message: All pipeline agents must be verified. [2] Hypatia Scanner, https://github.com/hyperpolymath/hypatia [3] SLSA Framework, https://slsa.dev @end -``` +.... -This example shows how `finishbot` will refuse to approve a deployment unless `codebot` and `sustainabot` are at least `verified`, and `hypatia` has been independently `audited`. The policy block makes this machine-enforceable. +This example shows how `+finishbot+` will refuse to approve a deployment +unless `+codebot+` and `+sustainabot+` are at least `+verified+`, and +`+hypatia+` has been independently `+audited+`. The policy block makes +this machine-enforceable. diff --git a/showcase/content/getting-started.adoc b/showcase/content/getting-started.adoc new file mode 100644 index 0000000..ff40175 --- /dev/null +++ b/showcase/content/getting-started.adoc @@ -0,0 +1,213 @@ +== Get Started + +A step-by-step guide to creating your first A2ML manifest, validating +it, and integrating it into your project. + +=== Prerequisites + +* https://pandoc.org/installing.html[Pandoc] 3.0 or later +* Git (for cloning the tooling) +* A text editor (VS Code recommended for syntax highlighting) + +''''' + +=== Install pandoc-a2ml + +Clone the pandoc-a2ml repository and note the path to the Lua scripts. +No compilation needed — the reader, writer, and filter are pure Lua. + +[source,bash] +---- +git clone https://github.com/hyperpolymath/pandoc-a2ml.git +cd pandoc-a2ml +---- + +The key files are: - `+a2ml-reader.lua+` — reads `+.a2ml+` files into +Pandoc’s AST - `+a2ml-writer.lua+` — writes Pandoc AST as `+.a2ml+` +output - `+a2ml-filter.lua+` — Lua filter for attestation processing + +You can either add these to your Pandoc data directory +(`+~/.local/share/pandoc/+`) or reference them by path. + +=== Install the VS Code Extension + +For syntax highlighting while editing `+.a2ml+` files: + +[arabic] +. Open VS Code +. Go to Extensions (Ctrl+Shift+X) +. Search for *"`A2ML`"* +. Click Install + +Alternatively, clone and install manually: + +[source,bash] +---- +git clone https://github.com/hyperpolymath/vscode-a2ml.git +cd vscode-a2ml +code --install-extension . +---- + +You should now see syntax highlighting for `+.a2ml+` files, including +directive blocks, headings, and comments. + +=== Create Your First Manifest + +Create a file called `+0-AI-MANIFEST.a2ml+` in your repository root. +This is the entry point that AI agents and tooling will read first. + +.... +;; SPDX-License-Identifier: CC-BY-SA-4.0 + +# AI Manifest — my-project + +@abstract: +This repository contains my-project, a tool for doing useful things. +This manifest declares the AI agents that operate on this repository +and the policies that govern their behaviour. +@end + +@provenance: +created-by: Your Name +created: 2026-03-16 +source: https://github.com/your-org/my-project +version: 1.0.0 +@end + +## Repository Structure + +- Source code in `src/` +- Machine-readable metadata in `.machine_readable/` +- CI/CD workflows in `.github/workflows/` + +## Agents + +No AI agents currently operate on this repository. + +@refs: +[1] A2ML Specification, https://a2ml.hyperpolymath.dev/specification.html +@end +.... + +=== Validate with Pandoc + +Check that your manifest parses correctly by converting it to HTML: + +[source,bash] +---- +pandoc -f path/to/a2ml-reader.lua 0-AI-MANIFEST.a2ml -o manifest.html +---- + +If the file is well-formed, Pandoc will produce clean HTML output. Open +`+manifest.html+` in a browser to verify the structure. + +For deeper validation using the A2ML filter (checks attestation +structure): + +[source,bash] +---- +pandoc -f path/to/a2ml-reader.lua \ + --lua-filter path/to/a2ml-filter.lua \ + 0-AI-MANIFEST.a2ml \ + -o validated.html +---- + +=== Add Machine-Readable Metadata + +For full Rhodium Standard compliance, create the `+.machine_readable/+` +directory and add A2ML metadata files: + +[source,bash] +---- +mkdir -p .machine_readable/anchors .machine_readable/policies +---- + +Create `+.machine_readable/STATE.a2ml+`: + +.... +;; SPDX-License-Identifier: CC-BY-SA-4.0 + +# Project State + +@abstract: +Current state of my-project development. +@end + +## Status + +- Phase: initial setup +- Completion: 10% +- Next milestone: core functionality + +## Blockers + +None currently. +.... + +Create `+.machine_readable/META.a2ml+`: + +.... +;; SPDX-License-Identifier: CC-BY-SA-4.0 + +# Project Metadata + +@abstract: +Architecture decisions and governance for my-project. +@end + +## Architecture Decisions + +- Language: chosen based on team expertise +- License: MPL-2.0 for original code +.... + +These files give AI agents and automated tooling a structured +understanding of your project’s state, architecture, and ecosystem +position. + +=== Add an Agent Attestation + +When you introduce an AI agent to your workflow (a CI bot, a code +reviewer, a security scanner), declare it in the manifest: + +.... +;; Add this to 0-AI-MANIFEST.a2ml or a dedicated agent file + +@attestation: +agent-id: my-ci-bot +attested-by: my-ci-bot +trust-level: self-declared +timestamp: 2026-03-16T12:00:00Z +capabilities: + - lint-checking + - test-execution +scope: repository +@end +.... + +As the agent is reviewed and verified, add higher-trust attestations: + +.... +@attestation: +agent-id: my-ci-bot +attested-by: security-team +trust-level: verified +timestamp: 2026-03-20T15:00:00Z +verifies: my-ci-bot/self-declared/2026-03-16 +signature: sha256:your-signature-here +@end +.... + +''''' + +=== Next Steps + +* Read the full link:specification.html[Specification] for all +directives and fields +* Browse link:examples.html[Examples] for real-world patterns +* Explore link:integrations.html[Integrations] for editor and CI tooling +* Check out the source repositories: +** https://github.com/hyperpolymath/pandoc-a2ml[pandoc-a2ml] +** https://github.com/hyperpolymath/vscode-a2ml[vscode-a2ml] +** https://github.com/hyperpolymath/tree-sitter-a2ml[tree-sitter-a2ml] +** https://github.com/hyperpolymath/pandoc-k9[pandoc-k9] diff --git a/showcase/content/getting-started.md b/showcase/content/getting-started.md deleted file mode 100644 index af2795f..0000000 --- a/showcase/content/getting-started.md +++ /dev/null @@ -1,226 +0,0 @@ ---- -title: Get Started -date: 2026-03-16 -order: 5 ---- - -# Get Started - -A step-by-step guide to creating your first A2ML manifest, validating it, and integrating it into your project. - -## Prerequisites - -- [Pandoc](https://pandoc.org/installing.html) 3.0 or later -- Git (for cloning the tooling) -- A text editor (VS Code recommended for syntax highlighting) - ---- - -
- -## Install pandoc-a2ml - -Clone the pandoc-a2ml repository and note the path to the Lua scripts. No compilation needed — the reader, writer, and filter are pure Lua. - -```bash -git clone https://github.com/hyperpolymath/pandoc-a2ml.git -cd pandoc-a2ml -``` - -The key files are: -- `a2ml-reader.lua` — reads `.a2ml` files into Pandoc's AST -- `a2ml-writer.lua` — writes Pandoc AST as `.a2ml` output -- `a2ml-filter.lua` — Lua filter for attestation processing - -You can either add these to your Pandoc data directory (`~/.local/share/pandoc/`) or reference them by path. - -
- -
- -## Install the VS Code Extension - -For syntax highlighting while editing `.a2ml` files: - -1. Open VS Code -2. Go to Extensions (Ctrl+Shift+X) -3. Search for **"A2ML"** -4. Click Install - -Alternatively, clone and install manually: - -```bash -git clone https://github.com/hyperpolymath/vscode-a2ml.git -cd vscode-a2ml -code --install-extension . -``` - -You should now see syntax highlighting for `.a2ml` files, including directive blocks, headings, and comments. - -
- -
- -## Create Your First Manifest - -Create a file called `0-AI-MANIFEST.a2ml` in your repository root. This is the entry point that AI agents and tooling will read first. - -``` -;; SPDX-License-Identifier: CC-BY-SA-4.0 - -# AI Manifest — my-project - -@abstract: -This repository contains my-project, a tool for doing useful things. -This manifest declares the AI agents that operate on this repository -and the policies that govern their behaviour. -@end - -@provenance: -created-by: Your Name -created: 2026-03-16 -source: https://github.com/your-org/my-project -version: 1.0.0 -@end - -## Repository Structure - -- Source code in `src/` -- Machine-readable metadata in `.machine_readable/` -- CI/CD workflows in `.github/workflows/` - -## Agents - -No AI agents currently operate on this repository. - -@refs: -[1] A2ML Specification, https://a2ml.hyperpolymath.dev/specification.html -@end -``` - -
- -
- -## Validate with Pandoc - -Check that your manifest parses correctly by converting it to HTML: - -```bash -pandoc -f path/to/a2ml-reader.lua 0-AI-MANIFEST.a2ml -o manifest.html -``` - -If the file is well-formed, Pandoc will produce clean HTML output. Open `manifest.html` in a browser to verify the structure. - -For deeper validation using the A2ML filter (checks attestation structure): - -```bash -pandoc -f path/to/a2ml-reader.lua \ - --lua-filter path/to/a2ml-filter.lua \ - 0-AI-MANIFEST.a2ml \ - -o validated.html -``` - -
- -
- -## Add Machine-Readable Metadata - -For full Rhodium Standard compliance, create the `.machine_readable/` directory and add A2ML metadata files: - -```bash -mkdir -p .machine_readable/anchors .machine_readable/policies -``` - -Create `.machine_readable/STATE.a2ml`: - -``` -;; SPDX-License-Identifier: CC-BY-SA-4.0 - -# Project State - -@abstract: -Current state of my-project development. -@end - -## Status - -- Phase: initial setup -- Completion: 10% -- Next milestone: core functionality - -## Blockers - -None currently. -``` - -Create `.machine_readable/META.a2ml`: - -``` -;; SPDX-License-Identifier: CC-BY-SA-4.0 - -# Project Metadata - -@abstract: -Architecture decisions and governance for my-project. -@end - -## Architecture Decisions - -- Language: chosen based on team expertise -- License: MPL-2.0 for original code -``` - -These files give AI agents and automated tooling a structured understanding of your project's state, architecture, and ecosystem position. - -
- -
- -## Add an Agent Attestation - -When you introduce an AI agent to your workflow (a CI bot, a code reviewer, a security scanner), declare it in the manifest: - -``` -;; Add this to 0-AI-MANIFEST.a2ml or a dedicated agent file - -@attestation: -agent-id: my-ci-bot -attested-by: my-ci-bot -trust-level: self-declared -timestamp: 2026-03-16T12:00:00Z -capabilities: - - lint-checking - - test-execution -scope: repository -@end -``` - -As the agent is reviewed and verified, add higher-trust attestations: - -``` -@attestation: -agent-id: my-ci-bot -attested-by: security-team -trust-level: verified -timestamp: 2026-03-20T15:00:00Z -verifies: my-ci-bot/self-declared/2026-03-16 -signature: sha256:your-signature-here -@end -``` - -
- ---- - -## Next Steps - -- Read the full [Specification](specification.html) for all directives and fields -- Browse [Examples](examples.html) for real-world patterns -- Explore [Integrations](integrations.html) for editor and CI tooling -- Check out the source repositories: - - [pandoc-a2ml](https://github.com/hyperpolymath/pandoc-a2ml) - - [vscode-a2ml](https://github.com/hyperpolymath/vscode-a2ml) - - [tree-sitter-a2ml](https://github.com/hyperpolymath/tree-sitter-a2ml) - - [pandoc-k9](https://github.com/hyperpolymath/pandoc-k9) diff --git a/showcase/content/index.adoc b/showcase/content/index.adoc new file mode 100644 index 0000000..119c6ac --- /dev/null +++ b/showcase/content/index.adoc @@ -0,0 +1,88 @@ +A2ML + +Attested Markup Language + +Every AI agent needs an identity. A2ML gives them one. + +A universal manifest format that lets AI agents declare their +capabilities, prove their provenance through attestation chains, and +establish trust through verifiable metadata. + +Get Started + +== What is A2ML? + +A2ML (Attested Markup Language) is a structured document format designed +for the age of AI agents. It solves a fundamental problem: *how do you +know what an AI agent is, what it can do, and whether you should trust +it?* + +A2ML files (`+.a2ml+`) act as identity documents for software agents. +They combine human-readable markup with machine-verifiable attestation +blocks, creating a chain of trust that can be audited by both people and +automated systems. + +Attestation Chains + +Every claim is backed by a verifiable attestation. Agents sign their +capabilities, and auditors countersign. Trust is earned, not assumed. + +Provenance Tracking + +Know exactly where a manifest came from, who authored it, and what has +changed. Full lineage from creation to deployment. + +Agent Identity + +Unique agent identifiers, capability declarations, and trust levels. +Every agent in your system has a clear, auditable identity. + +CI/CD Native + +Designed to live in repositories alongside code. Validate manifests in +pipelines, enforce policies in pull requests, audit in production. + +== Why A2ML? + +As AI agents proliferate across CI/CD pipelines, security scanners, code +reviewers, and orchestration systems, the question of *agent +accountability* becomes critical. Who deployed this bot? What +permissions does it have? Who attested to its behaviour? + +A2ML answers these questions with a format that is: + +* *Human-readable* — uses familiar markup syntax with headings, lists, +and paragraphs +* *Machine-parseable* — directive blocks (`+@attestation:+` … `+@end+`) +carry structured data +* *Auditable* — attestation chains create a verifiable trust graph +* *Composable* — agents can reference each other’s manifests to build +multi-agent trust networks + +== Tooling Ecosystem + +A2ML is not a paper specification. It ships with real, working tools: + +* *https://pandoc.org[Pandoc]* reader, writer, filter, and template via +https://github.com/hyperpolymath/pandoc-a2ml[pandoc-a2ml] — convert A2ML +to HTML, PDF, Markdown, and 40+ other formats +* *https://code.visualstudio.com[VS Code]* syntax highlighting via +https://github.com/hyperpolymath/vscode-a2ml[vscode-a2ml] +* *https://tree-sitter.github.io[Tree-sitter]* grammar via +https://github.com/hyperpolymath/tree-sitter-a2ml[tree-sitter-a2ml] — +works in Neovim, Helix, Zed, and GitHub +* *GitHub Linguist* — language detection (submission pending) + +== Part of a Larger Ecosystem + +A2ML integrates with the broader hyperpolymath standards: + +* *https://github.com/hyperpolymath/pandoc-k9[K9 Validators]* — +contractile enforcement for repository policies +* *https://github.com/hyperpolymath/hypatia[Hypatia]* — neurosymbolic +CI/CD security scanning that consumes A2ML manifests +* *https://github.com/hyperpolymath/panll[PanLL]* — panel framework with +A2ML-based panel identity +* *https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories]* — repository quality standard that requires A2ML +manifests diff --git a/showcase/content/index.md b/showcase/content/index.md deleted file mode 100644 index d8b8920..0000000 --- a/showcase/content/index.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: A2ML -date: 2026-03-16 -order: 1 ---- - -
-

A2ML

-

Attested Markup Language

-

Every AI agent needs an identity. A2ML gives them one.

-

A universal manifest format that lets AI agents declare their capabilities, -prove their provenance through attestation chains, and establish trust -through verifiable metadata.

-Get Started -
- -## What is A2ML? - -A2ML (Attested Markup Language) is a structured document format designed for the age of AI agents. It solves a fundamental problem: **how do you know what an AI agent is, what it can do, and whether you should trust it?** - -A2ML files (`.a2ml`) act as identity documents for software agents. They combine human-readable markup with machine-verifiable attestation blocks, creating a chain of trust that can be audited by both people and automated systems. - -
-
-

Attestation Chains

-

Every claim is backed by a verifiable attestation. Agents sign their capabilities, and auditors countersign. Trust is earned, not assumed.

-
-
-

Provenance Tracking

-

Know exactly where a manifest came from, who authored it, and what has changed. Full lineage from creation to deployment.

-
-
-

Agent Identity

-

Unique agent identifiers, capability declarations, and trust levels. Every agent in your system has a clear, auditable identity.

-
-
-

CI/CD Native

-

Designed to live in repositories alongside code. Validate manifests in pipelines, enforce policies in pull requests, audit in production.

-
-
- -## Why A2ML? - -As AI agents proliferate across CI/CD pipelines, security scanners, code reviewers, and orchestration systems, the question of **agent accountability** becomes critical. Who deployed this bot? What permissions does it have? Who attested to its behaviour? - -A2ML answers these questions with a format that is: - -- **Human-readable** — uses familiar markup syntax with headings, lists, and paragraphs -- **Machine-parseable** — directive blocks (`@attestation:` ... `@end`) carry structured data -- **Auditable** — attestation chains create a verifiable trust graph -- **Composable** — agents can reference each other's manifests to build multi-agent trust networks - -## Tooling Ecosystem - -A2ML is not a paper specification. It ships with real, working tools: - -- **[Pandoc](https://pandoc.org)** reader, writer, filter, and template via [pandoc-a2ml](https://github.com/hyperpolymath/pandoc-a2ml) — convert A2ML to HTML, PDF, Markdown, and 40+ other formats -- **[VS Code](https://code.visualstudio.com)** syntax highlighting via [vscode-a2ml](https://github.com/hyperpolymath/vscode-a2ml) -- **[Tree-sitter](https://tree-sitter.github.io)** grammar via [tree-sitter-a2ml](https://github.com/hyperpolymath/tree-sitter-a2ml) — works in Neovim, Helix, Zed, and GitHub -- **GitHub Linguist** — language detection (submission pending) - -## Part of a Larger Ecosystem - -A2ML integrates with the broader hyperpolymath standards: - -- **[K9 Validators](https://github.com/hyperpolymath/pandoc-k9)** — contractile enforcement for repository policies -- **[Hypatia](https://github.com/hyperpolymath/hypatia)** — neurosymbolic CI/CD security scanning that consumes A2ML manifests -- **[PanLL](https://github.com/hyperpolymath/panll)** — panel framework with A2ML-based panel identity -- **[Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories)** — repository quality standard that requires A2ML manifests diff --git a/showcase/content/integrations.adoc b/showcase/content/integrations.adoc new file mode 100644 index 0000000..78ab8c2 --- /dev/null +++ b/showcase/content/integrations.adoc @@ -0,0 +1,131 @@ +== Integrations + +A2ML has working integrations across editors, build tools, and language +ecosystems. This is not a roadmap — these tools exist today. + +''''' + +=== Pandoc [.badge .badge-live]#Live# + +Full Pandoc integration via +https://github.com/hyperpolymath/pandoc-a2ml[pandoc-a2ml]: custom +reader, writer, Lua filter, and HTML template. + +Convert A2ML to any of Pandoc’s 40+ output formats (HTML, PDF, DOCX, +LaTeX, Markdown, reStructuredText, EPUB, and more), or convert _from_ +any Pandoc input format into A2ML. + +[source,bash] +---- +# Read A2ML, output HTML +pandoc -f a2ml-reader.lua manifest.a2ml -o manifest.html + +# Read A2ML, output PDF +pandoc -f a2ml-reader.lua manifest.a2ml -o manifest.pdf + +# Convert Markdown to A2ML +pandoc README.md -t a2ml-writer.lua -o README.a2ml + +# Apply the A2ML filter for attestation validation +pandoc -f a2ml-reader.lua --lua-filter a2ml-filter.lua manifest.a2ml -o report.html +---- + +*Install:* Clone the repo and add the Lua scripts to your Pandoc data +directory, or reference them by path. + +*Repository:* +https://github.com/hyperpolymath/pandoc-a2ml[github.com/hyperpolymath/pandoc-a2ml] + +=== VS Code [.badge .badge-live]#Live# + +Syntax highlighting, bracket matching, and snippet support for `+.a2ml+` +files in Visual Studio Code. + +Features: - Full TextMate grammar for A2ML syntax - Highlighting for +directives (`+@attestation:+` … `+@end+`), headings, inline formatting, +and comments - Snippets for common patterns (attestation block, policy +block, provenance block) - File icon for `+.a2ml+` files - Language +configuration for bracket/comment auto-pairing + +*Install:* Search "`A2ML`" in the VS Code marketplace, or install from +VSIX. + +*Repository:* +https://github.com/hyperpolymath/vscode-a2ml[github.com/hyperpolymath/vscode-a2ml] + +=== Tree-sitter [.badge .badge-live]#Live# + +A https://tree-sitter.github.io[tree-sitter] grammar for A2ML, enabling +syntax highlighting and structural queries in any editor that supports +tree-sitter. + +Works with: - *Neovim* (via nvim-treesitter) - *Helix* (built-in +tree-sitter support) - *Zed* (built-in tree-sitter support) - *GitHub* +(syntax highlighting in code views, via tree-sitter) - *Emacs* (via +tree-sitter-langs) + +The grammar parses the full A2ML syntax including nested directive +blocks, attestation fields, and inline formatting. + +*Repository:* +https://github.com/hyperpolymath/tree-sitter-a2ml[github.com/hyperpolymath/tree-sitter-a2ml] + +=== GitHub Linguist [.badge .badge-pending]#Pending# + +A pull request to add A2ML to +https://github.com/github-linguist/linguist[GitHub Linguist] is in +preparation. Once merged, GitHub will: + +* Detect `+.a2ml+` files automatically +* Show A2ML in repository language statistics +* Apply syntax highlighting using the tree-sitter grammar +* Recognise `+application/vnd.a2ml+` as a registered media type + +=== K9 Validators [.badge .badge-live]#Live# + +https://github.com/hyperpolymath/pandoc-k9[pandoc-k9] provides +contractile validation for A2ML files. K9 validators enforce structural +and policy constraints: + +* *must* — required fields and sections +* *trust* — attestation chain validity +* *dust* — deprecated pattern detection +* *intend* — intent declaration verification + +K9 runs in CI/CD pipelines and can block merges when A2ML manifests fail +validation. + +*Repository:* +https://github.com/hyperpolymath/pandoc-k9[github.com/hyperpolymath/pandoc-k9] + +=== LuaRocks [.badge .badge-live]#Live# + +The A2ML Pandoc components are available as a Lua library via +https://luarocks.org[LuaRocks], making it straightforward to integrate +A2ML parsing into any Lua-based toolchain. + +[source,bash] +---- +luarocks install pandoc-a2ml +---- + +=== Hypatia CI/CD Scanner [.badge .badge-live]#Live# + +https://github.com/hyperpolymath/hypatia[Hypatia] consumes A2ML +manifests as part of its neurosymbolic security scanning. It: + +* Reads `+0-AI-MANIFEST.a2ml+` to understand repository structure +* Validates attestation chains in `+.machine_readable/*.a2ml+` files +* Enforces that all agents operating on a repository have valid +manifests +* Reports trust-level gaps in CI pipeline output + +=== Hackage (Haskell) [.badge .badge-soon]#Coming Soon# + +A native Haskell library for parsing and generating A2ML is in +development. It will provide: + +* Pure Haskell parser (no Pandoc dependency) +* Type-safe AST for A2ML documents +* Attestation chain validation +* Integration with the Pandoc Haskell library diff --git a/showcase/content/integrations.md b/showcase/content/integrations.md deleted file mode 100644 index fdbfe5a..0000000 --- a/showcase/content/integrations.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: Integrations -date: 2026-03-16 -order: 4 ---- - -# Integrations - -A2ML has working integrations across editors, build tools, and language ecosystems. This is not a roadmap — these tools exist today. - ---- - -
- -## Pandoc Live - -Full Pandoc integration via [pandoc-a2ml](https://github.com/hyperpolymath/pandoc-a2ml): custom reader, writer, Lua filter, and HTML template. - -Convert A2ML to any of Pandoc's 40+ output formats (HTML, PDF, DOCX, LaTeX, Markdown, reStructuredText, EPUB, and more), or convert *from* any Pandoc input format into A2ML. - -```bash -# Read A2ML, output HTML -pandoc -f a2ml-reader.lua manifest.a2ml -o manifest.html - -# Read A2ML, output PDF -pandoc -f a2ml-reader.lua manifest.a2ml -o manifest.pdf - -# Convert Markdown to A2ML -pandoc README.md -t a2ml-writer.lua -o README.a2ml - -# Apply the A2ML filter for attestation validation -pandoc -f a2ml-reader.lua --lua-filter a2ml-filter.lua manifest.a2ml -o report.html -``` - -**Install:** Clone the repo and add the Lua scripts to your Pandoc data directory, or reference them by path. - -**Repository:** [github.com/hyperpolymath/pandoc-a2ml](https://github.com/hyperpolymath/pandoc-a2ml) - -
- -
- -## VS Code Live - -Syntax highlighting, bracket matching, and snippet support for `.a2ml` files in Visual Studio Code. - -Features: -- Full TextMate grammar for A2ML syntax -- Highlighting for directives (`@attestation:` ... `@end`), headings, inline formatting, and comments -- Snippets for common patterns (attestation block, policy block, provenance block) -- File icon for `.a2ml` files -- Language configuration for bracket/comment auto-pairing - -**Install:** Search "A2ML" in the VS Code marketplace, or install from VSIX. - -**Repository:** [github.com/hyperpolymath/vscode-a2ml](https://github.com/hyperpolymath/vscode-a2ml) - -
- -
- -## Tree-sitter Live - -A [tree-sitter](https://tree-sitter.github.io) grammar for A2ML, enabling syntax highlighting and structural queries in any editor that supports tree-sitter. - -Works with: -- **Neovim** (via nvim-treesitter) -- **Helix** (built-in tree-sitter support) -- **Zed** (built-in tree-sitter support) -- **GitHub** (syntax highlighting in code views, via tree-sitter) -- **Emacs** (via tree-sitter-langs) - -The grammar parses the full A2ML syntax including nested directive blocks, attestation fields, and inline formatting. - -**Repository:** [github.com/hyperpolymath/tree-sitter-a2ml](https://github.com/hyperpolymath/tree-sitter-a2ml) - -
- -
- -## GitHub Linguist Pending - -A pull request to add A2ML to [GitHub Linguist](https://github.com/github-linguist/linguist) is in preparation. Once merged, GitHub will: - -- Detect `.a2ml` files automatically -- Show A2ML in repository language statistics -- Apply syntax highlighting using the tree-sitter grammar -- Recognise `application/vnd.a2ml` as a registered media type - -
- -
- -## K9 Validators Live - -[pandoc-k9](https://github.com/hyperpolymath/pandoc-k9) provides contractile validation for A2ML files. K9 validators enforce structural and policy constraints: - -- **must** — required fields and sections -- **trust** — attestation chain validity -- **dust** — deprecated pattern detection -- **intend** — intent declaration verification - -K9 runs in CI/CD pipelines and can block merges when A2ML manifests fail validation. - -**Repository:** [github.com/hyperpolymath/pandoc-k9](https://github.com/hyperpolymath/pandoc-k9) - -
- -
- -## LuaRocks Live - -The A2ML Pandoc components are available as a Lua library via [LuaRocks](https://luarocks.org), making it straightforward to integrate A2ML parsing into any Lua-based toolchain. - -```bash -luarocks install pandoc-a2ml -``` - -
- -
- -## Hypatia CI/CD Scanner Live - -[Hypatia](https://github.com/hyperpolymath/hypatia) consumes A2ML manifests as part of its neurosymbolic security scanning. It: - -- Reads `0-AI-MANIFEST.a2ml` to understand repository structure -- Validates attestation chains in `.machine_readable/*.a2ml` files -- Enforces that all agents operating on a repository have valid manifests -- Reports trust-level gaps in CI pipeline output - -
- -
- -## Hackage (Haskell) Coming Soon - -A native Haskell library for parsing and generating A2ML is in development. It will provide: - -- Pure Haskell parser (no Pandoc dependency) -- Type-safe AST for A2ML documents -- Attestation chain validation -- Integration with the Pandoc Haskell library - -
diff --git a/showcase/content/specification.md b/showcase/content/specification.adoc similarity index 52% rename from showcase/content/specification.md rename to showcase/content/specification.adoc index c4d0e0f..53d9771 100644 --- a/showcase/content/specification.md +++ b/showcase/content/specification.adoc @@ -1,104 +1,109 @@ ---- -title: Specification -date: 2026-03-16 -order: 2 ---- +== A2ML Specification -# A2ML Specification +=== Overview -## Overview +A2ML (Attested Markup Language) is a text-based document format that +combines human-readable markup with machine-verifiable attestation +blocks. This page describes the format as currently implemented in the +https://github.com/hyperpolymath/pandoc-a2ml[pandoc-a2ml] toolchain. -A2ML (Attested Markup Language) is a text-based document format that combines human-readable markup with machine-verifiable attestation blocks. This page describes the format as currently implemented in the [pandoc-a2ml](https://github.com/hyperpolymath/pandoc-a2ml) toolchain. +=== File Format -## File Format +* *Extension:* `+.a2ml+` +* *Media type:* `+application/vnd.a2ml+` (IANA registration pending) +* *Encoding:* UTF-8 +* *Line endings:* LF (Unix-style) recommended; CRLF accepted -- **Extension:** `.a2ml` -- **Media type:** `application/vnd.a2ml` (IANA registration pending) -- **Encoding:** UTF-8 -- **Line endings:** LF (Unix-style) recommended; CRLF accepted +=== Basic Syntax -## Basic Syntax +A2ML uses a Markdown-like syntax with additional constructs for +attestation and structured metadata. -A2ML uses a Markdown-like syntax with additional constructs for attestation and structured metadata. +==== Headings -### Headings - -``` +.... # Top-level heading ## Second-level heading ### Third-level heading -``` +.... -### Inline Formatting +==== Inline Formatting -``` +.... **Bold text** for emphasis *Italic text* for secondary emphasis [Link text](https://example.com) for hyperlinks @ref(section-id) for internal cross-references `inline code` for identifiers -``` +.... -### Lists +==== Lists -``` +.... - Unordered list item - Another item * Asterisk syntax also works 1. Ordered list item 2. Another item -``` +.... -### Code Blocks +==== Code Blocks -```` +.... ```language code goes here ``` -```` +.... -### Comments +==== Comments -``` +.... ;; Scheme-style comments are stripped during parsing. ;; Use these for notes that should not appear in output. -``` +.... -## Directive Blocks +=== Directive Blocks -Directives are the core extension that distinguishes A2ML from plain Markdown. They carry structured, machine-readable content within annotated blocks. +Directives are the core extension that distinguishes A2ML from plain +Markdown. They carry structured, machine-readable content within +annotated blocks. -### Syntax +==== Syntax -``` +.... @directive-name: Content of the directive. Can span multiple lines. @end -``` +.... -The parser collects everything between `@directive-name:` and `@end` into a named container (rendered as a `
` with `class="directive-name"` in HTML output). +The parser collects everything between `+@directive-name:+` and `+@end+` +into a named container (rendered as a `+
+` with +`+class="directive-name"+` in HTML output). -### Standard Directives +==== Standard Directives -The following directives have conventional meaning across the A2ML ecosystem. Tooling may validate or enforce these. +The following directives have conventional meaning across the A2ML +ecosystem. Tooling may validate or enforce these. -#### `@abstract` +===== `+@abstract+` -A short summary of the document's purpose. Typically one to three sentences. +A short summary of the document’s purpose. Typically one to three +sentences. -``` +.... @abstract: A2ML is a typed, attested markup format for AI agent identity. @end -``` +.... -#### `@attestation` +===== `+@attestation+` -A trust claim with structured fields. This is the fundamental unit of the A2ML trust model. +A trust claim with structured fields. This is the fundamental unit of +the A2ML trust model. -``` +.... @attestation: agent-id: hypatia-scanner-v3 attested-by: rhodibot @@ -111,48 +116,59 @@ capabilities: - dependency-audit scope: repository @end -``` +.... -**Fields:** +*Fields:* -| Field | Required | Description | -|-------|----------|-------------| -| `agent-id` | Yes | Unique identifier for the agent being attested | -| `attested-by` | Yes | Identifier of the attesting authority | -| `trust-level` | Yes | One of: `self-declared`, `peer-reviewed`, `verified`, `audited` | -| `timestamp` | Yes | ISO 8601 timestamp of the attestation | -| `signature` | Recommended | Cryptographic signature (algorithm:hash) | -| `capabilities` | Yes | List of declared capabilities | -| `scope` | No | Scope of the attestation (e.g., `repository`, `organization`, `global`) | +[width="100%",cols="24%,33%,43%",options="header",] +|=== +|Field |Required |Description +|`+agent-id+` |Yes |Unique identifier for the agent being attested -#### `@refs` +|`+attested-by+` |Yes |Identifier of the attesting authority -References and citations. Used for linking to external specifications, standards, or related documents. +|`+trust-level+` |Yes |One of: `+self-declared+`, `+peer-reviewed+`, +`+verified+`, `+audited+` -``` +|`+timestamp+` |Yes |ISO 8601 timestamp of the attestation + +|`+signature+` |Recommended |Cryptographic signature (algorithm:hash) + +|`+capabilities+` |Yes |List of declared capabilities + +|`+scope+` |No |Scope of the attestation (e.g., `+repository+`, +`+organization+`, `+global+`) +|=== + +===== `+@refs+` + +References and citations. Used for linking to external specifications, +standards, or related documents. + +.... @refs: [1] Attested Markup Language Specification (draft), 2026 [2] SLSA Supply Chain Framework, https://slsa.dev @end -``` +.... -#### `@policy` +===== `+@policy+` Declares a policy constraint that tooling should enforce. -``` +.... @policy: require: attestation.trust-level >= verified enforce: ci-pipeline action: block-merge @end -``` +.... -#### `@provenance` +===== `+@provenance+` Records the origin and lineage of the document. -``` +.... @provenance: created-by: Jonathan D.A. Jewell created: 2026-01-15 @@ -160,13 +176,14 @@ last-modified: 2026-03-16 source: https://github.com/hyperpolymath/a2ml-spec version: 0.3.0 @end -``` +.... -## Attestation Chains +=== Attestation Chains -The real power of A2ML comes from **attestation chains** — sequences of attestations where each one references or builds upon previous ones. +The real power of A2ML comes from *attestation chains* — sequences of +attestations where each one references or builds upon previous ones. -``` +.... ;; Agent declares its own capabilities @attestation: agent-id: codebot-v2 @@ -195,24 +212,36 @@ verifies: codebot-v2/verified/2026-03-12 audit-report: https://audits.example.com/codebot-v2 signature: sha256:7b1e4d... @end -``` +.... -Each successive attestation raises the trust level and creates an auditable trail from `self-declared` through `verified` to `audited`. +Each successive attestation raises the trust level and creates an +auditable trail from `+self-declared+` through `+verified+` to +`+audited+`. -## Trust Levels +=== Trust Levels -| Level | Meaning | Typical Attester | -|-------|---------|------------------| -| `self-declared` | Agent claims its own capabilities | The agent itself | -| `peer-reviewed` | Another agent or team has reviewed the claims | A peer agent or team lead | -| `verified` | A security or operations team has validated behaviour | Security team, CI system | -| `audited` | An independent audit has confirmed the claims | External auditor | +[width="100%",cols="22%,26%,52%",options="header",] +|=== +|Level |Meaning |Typical Attester +|`+self-declared+` |Agent claims its own capabilities |The agent itself -## Canonical File Locations +|`+peer-reviewed+` |Another agent or team has reviewed the claims |A +peer agent or team lead -In repositories following the [Rhodium Standard](https://github.com/hyperpolymath/rhodium-standard-repositories), A2ML files live in the `.machine_readable/` directory: +|`+verified+` |A security or operations team has validated behaviour +|Security team, CI system -``` +|`+audited+` |An independent audit has confirmed the claims |External +auditor +|=== + +=== Canonical File Locations + +In repositories following the +https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard], A2ML files live in the `+.machine_readable/+` directory: + +.... .machine_readable/ STATE.a2ml # Project state and progress META.a2ml # Architecture decisions, governance @@ -225,15 +254,18 @@ In repositories following the [Rhodium Standard](https://github.com/hyperpolymat policies/ MAINTENANCE-AXES.a2ml MAINTENANCE-CHECKLIST.a2ml -``` +.... -The top-level `0-AI-MANIFEST.a2ml` serves as the entry point that all AI agents must read first. +The top-level `+0-AI-MANIFEST.a2ml+` serves as the entry point that all +AI agents must read first. -## Pandoc Integration +=== Pandoc Integration -A2ML is a first-class Pandoc format. Convert between A2ML and any Pandoc-supported format: +A2ML is a first-class Pandoc format. Convert between A2ML and any +Pandoc-supported format: -```bash +[source,bash] +---- # A2ML to HTML pandoc -f a2ml-reader.lua input.a2ml -o output.html @@ -245,4 +277,4 @@ pandoc input.md -t a2ml-writer.lua -o output.a2ml # A2ML to A2ML (normalise) pandoc -f a2ml-reader.lua input.a2ml -t a2ml-writer.lua -o normalised.a2ml -``` +---- diff --git a/showcase/llm-warmup-dev.adoc b/showcase/llm-warmup-dev.adoc new file mode 100644 index 0000000..9f2974d --- /dev/null +++ b/showcase/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — a2ml-showcase (Developer) + +=== What is a2ml-showcase? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/showcase/llm-warmup-dev.md b/showcase/llm-warmup-dev.md deleted file mode 100644 index 2cf425f..0000000 --- a/showcase/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — a2ml-showcase (Developer) - -## What is a2ml-showcase? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/showcase/llm-warmup-user.adoc b/showcase/llm-warmup-user.adoc new file mode 100644 index 0000000..ba582c2 --- /dev/null +++ b/showcase/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — a2ml-showcase (User) + +=== What is a2ml-showcase? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/showcase/llm-warmup-user.md b/showcase/llm-warmup-user.md deleted file mode 100644 index 7998946..0000000 --- a/showcase/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — a2ml-showcase (User) - -## What is a2ml-showcase? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/showcase/tests/README.adoc b/showcase/tests/README.adoc new file mode 100644 index 0000000..396b8fd --- /dev/null +++ b/showcase/tests/README.adoc @@ -0,0 +1,7 @@ +== Tests + +This is a showcase/content repository for A2ML examples. There is no +executable code to test. + +The `+fuzz/+` directory contains placeholder structure for OpenSSF +compliance. diff --git a/showcase/tests/README.md b/showcase/tests/README.md deleted file mode 100644 index 828acf1..0000000 --- a/showcase/tests/README.md +++ /dev/null @@ -1,8 +0,0 @@ - - -# Tests - -This is a showcase/content repository for A2ML examples. There is no executable -code to test. - -The `fuzz/` directory contains placeholder structure for OpenSSF compliance. diff --git a/validate-action/ARCHITECTURE.adoc b/validate-action/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/validate-action/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/validate-action/ARCHITECTURE.md b/validate-action/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/validate-action/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/validate-action/CHANGELOG.adoc b/validate-action/CHANGELOG.adoc new file mode 100644 index 0000000..4e420ac --- /dev/null +++ b/validate-action/CHANGELOG.adoc @@ -0,0 +1,24 @@ +== Changelog + +All notable changes to this project will be documented in this file. + +The format is based on https://keepachangelog.com/en/1.1.0/[Keep a +Changelog], and this project adheres to +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +=== [1.0.0] - 2026-05-29 + +==== Added + +* Initial Marketplace-ready composite action for validating `+.a2ml+` +manifests. +* Configurable `+path+`, `+strict+`, and `+paths-ignore+` inputs. +* GitHub Actions outputs for scanned files, validation errors, and +warnings. + +==== Fixed + +* Allow local smoke runs outside GitHub Actions by defaulting missing +`+GITHUB_OUTPUT+` to `+/dev/null+`. diff --git a/validate-action/CHANGELOG.md b/validate-action/CHANGELOG.md deleted file mode 100644 index 903612d..0000000 --- a/validate-action/CHANGELOG.md +++ /dev/null @@ -1,23 +0,0 @@ -# Changelog - -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - - - - -## [Unreleased] - -## [1.0.0] - 2026-05-29 - -### Added - -- Initial Marketplace-ready composite action for validating `.a2ml` manifests. -- Configurable `path`, `strict`, and `paths-ignore` inputs. -- GitHub Actions outputs for scanned files, validation errors, and warnings. - -### Fixed - -- Allow local smoke runs outside GitHub Actions by defaulting missing `GITHUB_OUTPUT` to `/dev/null`. diff --git a/validate-action/CODE_OF_CONDUCT.adoc b/validate-action/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/validate-action/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/validate-action/CODE_OF_CONDUCT.md b/validate-action/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/validate-action/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/validate-action/CONTRIBUTING.adoc b/validate-action/CONTRIBUTING.adoc new file mode 100644 index 0000000..dd089ae --- /dev/null +++ b/validate-action/CONTRIBUTING.adoc @@ -0,0 +1,71 @@ +== Contributing + +Thank you for your interest in contributing! We follow a "`Dual-Track`" +architecture where human-readable documentation lives in the root and +machine-readable policies live in `+.machine_readable/+`. + +=== How to Contribute + +We welcome contributions in many forms: + +* *Code:* Improving the core stack or extensions +* *Documentation:* Enhancing docs or AI manifests +* *Testing:* Adding property-based tests or formal proofs +* *Bug reports:* Filing clear, reproducible issues + +=== Getting Started + +[arabic] +. *Read the AI Manifest:* Start with `+0-AI-MANIFEST.a2ml+` (if present) +to understand the repository structure. +. *Environment:* Use `+guix develop+` or `+direnv allow+` to set up your +tools. +. *Task Runner:* Use `+just+` to see available commands +(`+just --list+`). + +=== Development Workflow + +==== Branch Naming + +.... +docs/short-description # Documentation +test/what-added # Test additions +feat/short-description # New features +fix/issue-number-description # Bug fixes +refactor/what-changed # Code improvements +security/what-fixed # Security fixes +.... + +==== Commit Messages + +We follow https://www.conventionalcommits.org/[Conventional Commits]: + +.... +(): + +[optional body] + +[optional footer] +.... + +Types: `+feat+`, `+fix+`, `+docs+`, `+test+`, `+refactor+`, `+ci+`, +`+chore+`, `+security+` + +=== Reporting Bugs + +Before reporting: 1. Search existing issues 2. Check if it’s already +fixed in `+main+` + +When reporting, include: - Clear, descriptive title - Environment +details (OS, versions, toolchain) - Steps to reproduce - Expected vs +actual behaviour + +=== Code of Conduct + +All contributors are expected to adhere to our +link:CODE_OF_CONDUCT.md[Code of Conduct]. + +=== License + +By contributing, you agree that your contributions will be licensed +under the same license as the project (see LICENSE). diff --git a/validate-action/CONTRIBUTING.md b/validate-action/CONTRIBUTING.md deleted file mode 100644 index 90e87dc..0000000 --- a/validate-action/CONTRIBUTING.md +++ /dev/null @@ -1,66 +0,0 @@ - -# Contributing - -Thank you for your interest in contributing! We follow a "Dual-Track" architecture where human-readable documentation lives in the root and machine-readable policies live in `.machine_readable/`. - -## How to Contribute - -We welcome contributions in many forms: - -- **Code:** Improving the core stack or extensions -- **Documentation:** Enhancing docs or AI manifests -- **Testing:** Adding property-based tests or formal proofs -- **Bug reports:** Filing clear, reproducible issues - -## Getting Started - -1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` (if present) to understand the repository structure. -2. **Environment:** Use `guix develop` or `direnv allow` to set up your tools. -3. **Task Runner:** Use `just` to see available commands (`just --list`). - -## Development Workflow - -### Branch Naming - -``` -docs/short-description # Documentation -test/what-added # Test additions -feat/short-description # New features -fix/issue-number-description # Bug fixes -refactor/what-changed # Code improvements -security/what-fixed # Security fixes -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): - -``` -(): - -[optional body] - -[optional footer] -``` - -Types: `feat`, `fix`, `docs`, `test`, `refactor`, `ci`, `chore`, `security` - -## Reporting Bugs - -Before reporting: -1. Search existing issues -2. Check if it's already fixed in `main` - -When reporting, include: -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour - -## Code of Conduct - -All contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). - -## License - -By contributing, you agree that your contributions will be licensed under the same license as the project (see [LICENSE](LICENSE)). diff --git a/validate-action/GOVERNANCE.adoc b/validate-action/GOVERNANCE.adoc index 393df47..9b836fb 100644 --- a/validate-action/GOVERNANCE.adoc +++ b/validate-action/GOVERNANCE.adoc @@ -1,94 +1,60 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Governance +== Governance -[NOTE] -==== -Personal / solo-project model (Benevolent Maintainer). Last reviewed: 2026-06-22. -==== +=== Overview -== Project status +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. -This project is governed by a *Benevolent Maintainer* model. +=== Roles and Responsibilities -The project founder retains final authority over project direction, -architecture, releases, licensing, and governance. +==== Maintainers -== Founder +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support -Current founder and lead maintainer: +==== Contributors -* Jonathan D.A. Jewell (`@hyperpolymath`) +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed -== Decision making +=== Decision Making -Normal decisions are made by the founder. +==== Minor Changes -Contributors are encouraged to: +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates -* open issues -* submit pull requests -* propose designs -* discuss alternatives +==== Major Changes -Feedback is considered in good faith but does not bind the project. +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers -== Contributions +==== Breaking Changes -Contributions are welcome. See `CONTRIBUTING.md` for how to get started. +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide -Submitting a contribution does not guarantee acceptance. The founder may: +=== Code of Conduct -* accept a contribution -* request changes -* reject a contribution -* replace a contribution with an alternative implementation +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. -without further justification. +=== Communication -== Architectural direction +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions -The founder is responsible for: +=== Licensing -* project vision -* long-term roadmap -* architecture -* naming -* release strategy +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. -== Maintainers +''''' -Additional maintainers may be appointed by the founder (see `MAINTAINERS.adoc`). -Maintainers may review changes, merge pull requests, and manage issues unless -otherwise restricted. The founder may remove maintainers at any time. - -== Code of conduct - -All participants are expected to follow the project's `CODE_OF_CONDUCT.md`. -The founder is the point of contact for enforcement. - -== Security - -Report suspected vulnerabilities *privately* as described in `SECURITY.md`. -Please do not disclose vulnerabilities in public issues. - -== Forking - -Users are free to fork the project according to the license. Forks are -independent projects and are not considered official unless explicitly -designated. - -== Governance changes - -This document may be amended by the founder. - -== Project continuity - -If the founder permanently ceases maintenance: - -. a successor may be appointed; -. ownership may be transferred; -. the project may become community-maintained. - -Until such designation exists, no successor is implied. +_Last updated: 2026-07-18_ diff --git a/validate-action/GOVERNANCE.md b/validate-action/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/validate-action/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/validate-action/PROOF-NEEDS.adoc b/validate-action/PROOF-NEEDS.adoc new file mode 100644 index 0000000..7d5132f --- /dev/null +++ b/validate-action/PROOF-NEEDS.adoc @@ -0,0 +1,12 @@ +== PROOF-NEEDS.md + +=== Template ABI Cleanup (2026-03-29) + +Template ABI removed – was creating false impression of formal +verification. The removed files (Types.idr, Layout.idr, Foreign.idr) +contained only RSR template scaffolding with unresolved +\{\{PROJECT}}/\{\{AUTHOR}} placeholders and no domain-specific proofs. + +When this project needs formal ABI verification, create domain-specific +Idris2 proofs following the pattern in repos like `+typed-wasm+`, +`+proven+`, `+echidna+`, or `+boj-server+`. diff --git a/validate-action/PROOF-NEEDS.md b/validate-action/PROOF-NEEDS.md deleted file mode 100644 index 8950320..0000000 --- a/validate-action/PROOF-NEEDS.md +++ /dev/null @@ -1,10 +0,0 @@ -# PROOF-NEEDS.md - -## Template ABI Cleanup (2026-03-29) - -Template ABI removed -- was creating false impression of formal verification. -The removed files (Types.idr, Layout.idr, Foreign.idr) contained only RSR template -scaffolding with unresolved {{PROJECT}}/{{AUTHOR}} placeholders and no domain-specific proofs. - -When this project needs formal ABI verification, create domain-specific Idris2 proofs -following the pattern in repos like `typed-wasm`, `proven`, `echidna`, or `boj-server`. diff --git a/validate-action/README.adoc b/validate-action/README.adoc new file mode 100644 index 0000000..fef8651 --- /dev/null +++ b/validate-action/README.adoc @@ -0,0 +1,102 @@ +== Overview + +*GitHub Action to validate A2ML manifest files in your repository.* + +A2ML (Agnostic Agent Markup Language) is a manifest format used across +RSR (Rhodium Standard Repository) projects to declare machine-readable +metadata, AI agent instructions, and project state. This action scans +for `+.a2ml+` files and validates their structure and required fields. + +== Checks Performed + +[arabic] +. *SPDX header* — Verifies `+SPDX-License-Identifier+` is present in the +first 10 lines +. *Identity fields* — Requires `+agent-id+`, `+name+`, or `+project+` +field (relaxed for AI-MANIFEST files) +. *Version field* — Checks for `+version+` or `+schema_version+` +. *Attestation blocks* — If an `+[attestation]+` section exists, +validates it contains `+proof+`, `+signature+`, or `+hash+` fields +. *Section syntax* — Warns on malformed `+[section]+` headings with +unclosed brackets + +== Usage + +Add to your workflow: + +[source,yaml] +---- +name: Validate A2ML +on: [push, pull_request] + +permissions: + contents: read + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: hyperpolymath/a2ml-validate-action@v1 + with: + path: '.' # Directory to scan (default: repo root) + strict: 'false' # Promote warnings to errors (default: false) + # paths-ignore: defaults to vendored / fixture patterns; override + # via newline-separated string. Use '' to disable. +---- + +=== Inputs + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Input |Default |Description +|`+path+` |`+.+` |Directory path to scan for `+.a2ml+` files + +|`+strict+` |`+false+` |When `+true+`, warnings become errors and the +action fails on any issue + +|`+paths-ignore+` |_vendored & fixture defaults_ |Newline-separated path +fragments to skip. Substring match against each file path. Default set: +`+vendor/+`, `+vendored/+`, `+verified-container-spec/+`, +`+.audittraining/+`, `+integration/fixtures/+`, `+test/fixtures/+`, +`+tests/fixtures/+`. Pass an empty string (`+paths-ignore:+` `+’’+`) to +disable and scan everything. See +https://github.com/hyperpolymath/hypatia/pull/243 for the architectural +rationale (content-pattern validators must distinguish targets from +fixtures / vendored / training-corpus files that legitimately contain +the very pattern being checked). +|=== + +==== Why default-on path exemptions? + +A2ML files inside vendored projects (e.g. `+verified-container-spec/+`) +have their own identity declarations elsewhere or are themselves +training corpora. Flagging every such file as "`missing identity field`" +is provenance noise, not signal. The defaults match the canonical RSR +vendored-content paths; override for project-specific carve-outs. + +=== Outputs + +[cols=",",options="header",] +|=== +|Output |Description +|`+files-scanned+` |Number of `+.a2ml+` files processed +|`+errors+` |Count of validation errors +|`+warnings+` |Count of validation warnings +|=== + +== Strict Mode + +In strict mode (`+strict:+` `+’true’+`), all warnings are promoted to +errors. This is useful for repositories that require full A2ML +compliance, such as those following the RSR standard. + +== Author + +Jonathan D.A. Jewell + +== License + +SPDX-License-Identifier: CC-BY-SA-4.0 + +See LICENSE for details. diff --git a/validate-action/README.md b/validate-action/README.md deleted file mode 100644 index b54f2bf..0000000 --- a/validate-action/README.md +++ /dev/null @@ -1,93 +0,0 @@ - - -# Overview - -**GitHub Action to validate A2ML manifest files in your repository.** - -A2ML (Agnostic Agent Markup Language) is a manifest format used across -RSR (Rhodium Standard Repository) projects to declare machine-readable -metadata, AI agent instructions, and project state. This action scans -for `.a2ml` files and validates their structure and required fields. - -# Checks Performed - -1. **SPDX header** — Verifies `SPDX-License-Identifier` is present in - the first 10 lines - -2. **Identity fields** — Requires `agent-id`, `name`, or `project` - field (relaxed for AI-MANIFEST files) - -3. **Version field** — Checks for `version` or `schema_version` - -4. **Attestation blocks** — If an `[attestation]` section exists, - validates it contains `proof`, `signature`, or `hash` fields - -5. **Section syntax** — Warns on malformed `[section]` headings with - unclosed brackets - -# Usage - -Add to your workflow: - -```yaml -name: Validate A2ML -on: [push, pull_request] - -permissions: - contents: read - -jobs: - validate: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: hyperpolymath/a2ml-validate-action@v1 - with: - path: '.' # Directory to scan (default: repo root) - strict: 'false' # Promote warnings to errors (default: false) - # paths-ignore: defaults to vendored / fixture patterns; override - # via newline-separated string. Use '' to disable. -``` - -## Inputs - -| Input | Default | Description | -|----|----|----| -| `path` | `.` | Directory path to scan for `.a2ml` files | -| `strict` | `false` | When `true`, warnings become errors and the action fails on any issue | -| `paths-ignore` | *vendored & fixture defaults* | Newline-separated path fragments to skip. Substring match against each file path. Default set: `vendor/`, `vendored/`, `verified-container-spec/`, `.audittraining/`, `integration/fixtures/`, `test/fixtures/`, `tests/fixtures/`. Pass an empty string (`paths-ignore:` `’’`) to disable and scan everything. See for the architectural rationale (content-pattern validators must distinguish targets from fixtures / vendored / training-corpus files that legitimately contain the very pattern being checked). | - -### Why default-on path exemptions? - -A2ML files inside vendored projects (e.g. `verified-container-spec/`) -have their own identity declarations elsewhere or are themselves -training corpora. Flagging every such file as "missing identity field" -is provenance noise, not signal. The defaults match the canonical RSR -vendored-content paths; override for project-specific carve-outs. - -## Outputs - -| Output | Description | -|-----------------|-----------------------------------| -| `files-scanned` | Number of `.a2ml` files processed | -| `errors` | Count of validation errors | -| `warnings` | Count of validation warnings | - -# Strict Mode - -In strict mode (`strict:` `’true’`), all warnings are promoted to -errors. This is useful for repositories that require full A2ML -compliance, such as those following the RSR standard. - -# Author - -Jonathan D.A. Jewell \<[j.d.a.jewell@open.ac](j.d.a.jewell@open.ac).uk\> - -# License - -SPDX-License-Identifier: CC-BY-SA-4.0 - -See [LICENSE](LICENSE) for details. diff --git a/validate-action/SECURITY.adoc b/validate-action/SECURITY.adoc new file mode 100644 index 0000000..e47fdd9 --- /dev/null +++ b/validate-action/SECURITY.adoc @@ -0,0 +1,16 @@ +== Security Policy + +=== Reporting a Vulnerability + +If you discover a security vulnerability, please report it responsibly. + +*Email:* j.d.a.jewell@open.ac.uk + +*Please include:* - Description of the vulnerability - Steps to +reproduce - Potential impact + +*Response timeline:* - Acknowledgement within 48 hours - Initial +assessment within 7 days - Fix or mitigation within 90 days + +*Safe harbour:* We will not pursue legal action against security +researchers who follow responsible disclosure. diff --git a/validate-action/SECURITY.md b/validate-action/SECURITY.md deleted file mode 100644 index 5c4d5e9..0000000 --- a/validate-action/SECURITY.md +++ /dev/null @@ -1,20 +0,0 @@ - -# Security Policy - -## Reporting a Vulnerability - -If you discover a security vulnerability, please report it responsibly. - -**Email:** j.d.a.jewell@open.ac.uk - -**Please include:** -- Description of the vulnerability -- Steps to reproduce -- Potential impact - -**Response timeline:** -- Acknowledgement within 48 hours -- Initial assessment within 7 days -- Fix or mitigation within 90 days - -**Safe harbour:** We will not pursue legal action against security researchers who follow responsible disclosure. diff --git a/validate-action/TEST-NEEDS.adoc b/validate-action/TEST-NEEDS.adoc new file mode 100644 index 0000000..a759295 --- /dev/null +++ b/validate-action/TEST-NEEDS.adoc @@ -0,0 +1,32 @@ +== TEST-NEEDS.md — a2ml-validate-action + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current Test State + +[cols=",,",options="header",] +|=== +|Category |Count |Notes +|Test directories |2 |Location(s): /verification/tests, /tests +|CI workflows |14 |Running tests on GitHub Actions +|Tests |Present |Configured in CI workflows +|=== + +=== What’s Covered + +* [x] Tests present and running +* [x] CI integration active + +=== Still Missing (for CRG B+) + +* [ ] Code coverage reports (codecov integration) +* [ ] Detailed test documentation in CONTRIBUTING.md +* [ ] Integration tests beyond unit tests +* [ ] Performance benchmarking suite + +=== Run Tests + +[source,bash] +---- +(check Makefile/justfile/package.json for test command) +---- diff --git a/validate-action/TEST-NEEDS.md b/validate-action/TEST-NEEDS.md deleted file mode 100644 index 3099e2a..0000000 --- a/validate-action/TEST-NEEDS.md +++ /dev/null @@ -1,33 +0,0 @@ - -# TEST-NEEDS.md — a2ml-validate-action - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current Test State - -| Category | Count | Notes | -|----------|-------|-------| -| Test directories | 2 | Location(s): /verification/tests, /tests | -| CI workflows | 14 | Running tests on GitHub Actions | -| Tests | Present | Configured in CI workflows | - -## What's Covered - -- [x] Tests present and running -- [x] CI integration active - -## Still Missing (for CRG B+) - -- [ ] Code coverage reports (codecov integration) -- [ ] Detailed test documentation in CONTRIBUTING.md -- [ ] Integration tests beyond unit tests -- [ ] Performance benchmarking suite - -## Run Tests - -```bash -(check Makefile/justfile/package.json for test command) -``` diff --git a/validate-action/TOPOLOGY.md b/validate-action/TOPOLOGY.adoc similarity index 60% rename from validate-action/TOPOLOGY.md rename to validate-action/TOPOLOGY.adoc index 59254d6..64d8f81 100644 --- a/validate-action/TOPOLOGY.md +++ b/validate-action/TOPOLOGY.adoc @@ -1,14 +1,15 @@ - - -# TOPOLOGY.md — a2ml-validate-action +== TOPOLOGY.md — a2ml-validate-action -## Purpose +=== Purpose -GitHub Action that validates `.a2ml` manifest files in a repository. Checks SPDX headers, required identity/version fields, attestation block structure, and section syntax. Used in CI pipelines across RSR repos to enforce A2ML compliance. +GitHub Action that validates `+.a2ml+` manifest files in a repository. +Checks SPDX headers, required identity/version fields, attestation block +structure, and section syntax. Used in CI pipelines across RSR repos to +enforce A2ML compliance. -## Module Map +=== Module Map -``` +.... a2ml-validate-action/ ├── action.yml # GitHub Action metadata and entry point ├── src/ @@ -16,14 +17,14 @@ a2ml-validate-action/ ├── examples/ # Example workflows using this action ├── docs/ # Usage documentation └── container/ # Containerfile for CI -``` +.... -## Data Flow +=== Data Flow -``` +.... [GitHub workflow trigger] ──► [action.yml] ──► [validate-a2ml.sh] │ [scan repo for .a2ml files] │ [pass / fail with annotations] -``` +.... diff --git a/validate-action/llm-warmup-dev.adoc b/validate-action/llm-warmup-dev.adoc new file mode 100644 index 0000000..0ab33cf --- /dev/null +++ b/validate-action/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — a2ml-validate-action (Developer) + +=== What is a2ml-validate-action? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/validate-action/llm-warmup-dev.md b/validate-action/llm-warmup-dev.md deleted file mode 100644 index 3eb00e8..0000000 --- a/validate-action/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — a2ml-validate-action (Developer) - -## What is a2ml-validate-action? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/validate-action/llm-warmup-user.adoc b/validate-action/llm-warmup-user.adoc new file mode 100644 index 0000000..ae07d02 --- /dev/null +++ b/validate-action/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — a2ml-validate-action (User) + +=== What is a2ml-validate-action? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/validate-action/llm-warmup-user.md b/validate-action/llm-warmup-user.md deleted file mode 100644 index 24a4350..0000000 --- a/validate-action/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — a2ml-validate-action (User) - -## What is a2ml-validate-action? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture