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/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 0000000..b75ec5d --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,71 @@ +== Changelog + +All notable changes to `+maa-framework+` 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 comprehensive test suite to achieve CRG C compliance +* feat: add benchmarks, unit tests, E2E and aspect tests for +absolute-zero +* feat: add stapeln.toml container definition +* feat: deploy UX Manifesto infrastructure +* feat: add CLADE.a2ml — clade taxonomy declaration + +==== Fixed + +* fix(baseline): unblock 2 baseline-rot checks blocking dependabot #69 +(#70) +* fix(ci): pin upload-artifact to valid SHA in hypatia-scan.yml (Refs +standards#48) (#57) +* fix(ci): bump a2ml/k9-validate-action pins to canonical (#55) +* fix(ci): sync hypatia-scan.yml to canonical (#54) +* fix(ci): build Hypatia escript from repo root (estate dogfood drift) +* fix(ci): adopt canonical hypatia-scan.yml (#52) +* fix(ci): rsr-antipattern.yml duplicate heredoc (#49) +* fix(ci): move secret-scanner Cargo.toml gate from job-level if: to +step-level (#50) +* fix: remove eval, quote vars, use mktemp in absolute-zero shell +scripts +* fix: eliminate all 3 sorry in LambdaCNO proofs + +==== Documentation + +* docs: substantive CRG C annotation (EXPLAINME.adoc) +* docs(test): achieve CRG C — document all test categories passing +* docs: add EXPLAINME.adoc — prove-it file backing README claims + +==== CI + +* build(deps): bump dtolnay/rust-toolchain from +efa25f7f19611383d5b0ccf2d1c8914531636bf9 to +3c5f7ea28cd621ae0bf5283f0e981fb97b8a7af9 (#69) +* build(deps): bump haskell-actions/setup from 2.7.5 to 2.11.0 (#68) +* build(deps): bump actions/upload-pages-artifact from 3.0.1 to 5.0.0 +(#67) +* build(deps): bump actions/checkout from 4.1.1 to 6.0.2 (#66) +* build(deps): bump actions/configure-pages from 5.0.0 to 6.0.0 (#65) + +=== 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/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index f9e0086..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,62 +0,0 @@ - -# Changelog - -All notable changes to `maa-framework` 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 comprehensive test suite to achieve CRG C compliance -- feat: add benchmarks, unit tests, E2E and aspect tests for absolute-zero -- feat: add stapeln.toml container definition -- feat: deploy UX Manifesto infrastructure -- feat: add CLADE.a2ml — clade taxonomy declaration - -### Fixed - -- fix(baseline): unblock 2 baseline-rot checks blocking dependabot #69 (#70) -- fix(ci): pin upload-artifact to valid SHA in hypatia-scan.yml (Refs standards#48) (#57) -- fix(ci): bump a2ml/k9-validate-action pins to canonical (#55) -- fix(ci): sync hypatia-scan.yml to canonical (#54) -- fix(ci): build Hypatia escript from repo root (estate dogfood drift) -- fix(ci): adopt canonical hypatia-scan.yml (#52) -- fix(ci): rsr-antipattern.yml duplicate heredoc (#49) -- fix(ci): move secret-scanner Cargo.toml gate from job-level if: to step-level (#50) -- fix: remove eval, quote vars, use mktemp in absolute-zero shell scripts -- fix: eliminate all 3 sorry in LambdaCNO proofs - -### Documentation - -- docs: substantive CRG C annotation (EXPLAINME.adoc) -- docs(test): achieve CRG C — document all test categories passing -- docs: add EXPLAINME.adoc — prove-it file backing README claims - -### CI - -- build(deps): bump dtolnay/rust-toolchain from efa25f7f19611383d5b0ccf2d1c8914531636bf9 to 3c5f7ea28cd621ae0bf5283f0e981fb97b8a7af9 (#69) -- build(deps): bump haskell-actions/setup from 2.7.5 to 2.11.0 (#68) -- build(deps): bump actions/upload-pages-artifact from 3.0.1 to 5.0.0 (#67) -- build(deps): bump actions/checkout from 4.1.1 to 6.0.2 (#66) -- build(deps): bump actions/configure-pages from 5.0.0 to 6.0.0 (#65) - -## 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/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 bbe9219..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,30 +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..eb7f0f9 --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,109 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/maa-framework.git cd +maa-framework + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create maa-framework-dev toolbox enter maa-framework-dev # +Install dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +maa-framework/ ├── 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.nix # Nix 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/maa-framework/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/maa-framework/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/maa-framework/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/maa-framework/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/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 8d64548..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/maa-framework.git -cd maa-framework - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create maa-framework-dev -toolbox enter maa-framework-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -maa-framework/ -├── 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.nix # Nix 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/maa-framework/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/maa-framework/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/maa-framework/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/maa-framework/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/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/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 0000000..501a955 --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,119 @@ +== PROOF-NEEDS.md — maa-framework + +=== Current State + +_Re-measured 2026-07-27 against the `+absolute-zero+` submodule at +`+87902bb7+`._ + +* **src/abi/*.idr**: NO +* *`+Admitted+` count*: *0* +(`+grep -rn Admitted absolute-zero --include=*.v+`) +* *Trusted base*: *23 `+Axiom+` declarations across 6 `+.v+` files*, +each classified in-source. See the *AXIOM AUDIT* block at the end of +`+proofs/coq/physics/LandauerDerivation.v+` — that audit, not this file, +is the authoritative record. +* *LOC*: ~22,700 (Rust + Coq) +* *ABI layer*: Missing +* *Existing proofs*: Coq proofs for lambda CNO, Landauer derivation +chain, quantum mechanics exactness + +____ +*Correction (2026-07-27).* This file previously claimed _"`1 +`+Admitted+` in `+proofs/coq/lambda/LambdaCNO.v+` (y_not_cno)`"_. There +are *zero* `+Admitted+` anywhere. `+y_not_cno+` is a *KEPT AXIOM* — a +declared trust assumption with a written rationale +(`+LambdaCNO.v:388-399+`), not an unproven hole. The old wording was +wrong in both directions: it overstated the incompleteness _and_ +understated the trusted base by a factor of 23. + +The distinction matters operationally: an `+Axiom+` *passes* a "`no +`+sorry+` / no `+Admitted+``" gate silently, so counting only +`+Admitted+` measures the wrong thing. Any proof gate for this repo must +scan for `+Axiom+` too. +____ + +==== Axiom classification (summarised from the in-source audit) + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Class |Count |Meaning +|METAL-BOUNDARY |6 |genuine empirical physics, not derivable (k_B, +temperature, Second Law, isothermal work bound, Landauer lower bound, +reversible ⇒ zero dissipation) + +|SPECIFICATION |4 |sound, but not dischargeable while +`+shannon_entropy+` / `+product_dist+` stay opaque + +|NOT-YET-DISCHARGED (class A) |2 |`+cno_preserves_shannon_entropy+`, +`+cno_zero_energy_dissipation_derived+` + +|SOUNDNESS WARNINGS |3 |*false as stated*, currently *unused* — see +below +|=== + +The audit is notably self-critical: it records that +`+cno_zero_energy_dissipation_derived+` is an axiom *despite its +`+_derived+` name*, and that the triage docs’ "`DISCHARGE`" marks on it +and on `+reversible_zero_dissipation+` are *inaccurate*. Both are kept +honestly rather than fake-derived. + +=== What Needs Proving + +[width="100%",cols="51%,27%,22%",options="header",] +|=== +|Component |What |Why +|*Unsound-but-unused axioms* |Fix or delete `+prob_nonneg+`, +`+prob_normalized+` (false over unconstrained function-type +distributions — need a bundled distribution type) and +`+shannon_entropy_maximum+` (*stated inequality is backwards* — asserts +uniform _minimises_ entropy) |They are false. Unused today, so harmless +today; the moment anything cites one, it proves anything. *Highest +priority.* + +|`+cno_preserves_shannon_entropy+` |Discharge, or accept as a stated +postulate |class A — carrier/quotient issue + +|`+cno_zero_energy_dissipation_derived+` |Rename, or supply +`+internal_energy+` CNO-invariance |`+internal_energy+` is an opaque +`+Parameter+` with no preservation law, so this cannot be a pure +derivation + +|Absolute-zero brainfuck interpreter |Interpreter preserves CNO +properties |Claims of computational zero need formal backing + +|Absolute-zero whitespace interpreter |Same as brainfuck — CNO +preservation |Both esoteric interpreters need the same guarantee + +|Aletheia verification checks |Verification pipeline produces sound +results |Rhodibot extraction depends on correct checks + +|Quantum mechanics proofs |Extend QuantumMechanicsExact.v coverage +|Existing proofs are partial +|=== + +*Not on this list: `+y_not_cno+`.* It is not a "`concrete, closable +proof obligation`". The in-source rationale explains why: a rigorous +proof must rule out reaching the argument under _every_ interleaving of +`+beta_reduce+` (which permits reduction under binders and on either +side of an application), requiring an invariant closed under the full +reduction congruence, or a coinductive / step-indexed non-termination +argument. Genuinely out of scope, not merely tedious. + +=== Recommended Prover + +*Coq* — the existing proof infrastructure is in Coq. Aletheia (Rust) +verification would benefit from an *Idris2* ABI layer. + +=== Priority + +*MEDIUM* — the proof infrastructure is real and its trusted base is +honestly documented. The one genuinely urgent item is the three +*unsound* axioms: they are currently unused, so this is cheap to fix now +and expensive to discover later. + +=== 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/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index 4ce5099..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,81 +0,0 @@ - -# PROOF-NEEDS.md — maa-framework - -## Current State - -*Re-measured 2026-07-27 against the `absolute-zero` submodule at `87902bb7`.* - -- **src/abi/*.idr**: NO -- **`Admitted` count**: **0** (`grep -rn Admitted absolute-zero --include=*.v`) -- **Trusted base**: **23 `Axiom` declarations across 6 `.v` files**, each classified - in-source. See the **AXIOM AUDIT** block at the end of - `proofs/coq/physics/LandauerDerivation.v` — that audit, not this file, is the - authoritative record. -- **LOC**: ~22,700 (Rust + Coq) -- **ABI layer**: Missing -- **Existing proofs**: Coq proofs for lambda CNO, Landauer derivation chain, - quantum mechanics exactness - -> **Correction (2026-07-27).** This file previously claimed *"1 `Admitted` in -> `proofs/coq/lambda/LambdaCNO.v` (y_not_cno)"*. There are **zero** `Admitted` -> anywhere. `y_not_cno` is a **KEPT AXIOM** — a declared trust assumption with a -> written rationale (`LambdaCNO.v:388-399`), not an unproven hole. The old wording was -> wrong in both directions: it overstated the incompleteness *and* understated the -> trusted base by a factor of 23. -> -> The distinction matters operationally: an `Axiom` **passes** a "no `sorry` / -> no `Admitted`" gate silently, so counting only `Admitted` measures the wrong thing. -> Any proof gate for this repo must scan for `Axiom` too. - -### Axiom classification (summarised from the in-source audit) - -| Class | Count | Meaning | -|---|---|---| -| METAL-BOUNDARY | 6 | genuine empirical physics, not derivable (k_B, temperature, Second Law, isothermal work bound, Landauer lower bound, reversible ⇒ zero dissipation) | -| SPECIFICATION | 4 | sound, but not dischargeable while `shannon_entropy` / `product_dist` stay opaque | -| NOT-YET-DISCHARGED (class A) | 2 | `cno_preserves_shannon_entropy`, `cno_zero_energy_dissipation_derived` | -| SOUNDNESS WARNINGS | 3 | **false as stated**, currently **unused** — see below | - -The audit is notably self-critical: it records that -`cno_zero_energy_dissipation_derived` is an axiom **despite its `_derived` name**, and -that the triage docs' "DISCHARGE" marks on it and on `reversible_zero_dissipation` are -**inaccurate**. Both are kept honestly rather than fake-derived. - -## What Needs Proving - -| Component | What | Why | -|-----------|------|-----| -| **Unsound-but-unused axioms** | Fix or delete `prob_nonneg`, `prob_normalized` (false over unconstrained function-type distributions — need a bundled distribution type) and `shannon_entropy_maximum` (**stated inequality is backwards** — asserts uniform *minimises* entropy) | They are false. Unused today, so harmless today; the moment anything cites one, it proves anything. **Highest priority.** | -| `cno_preserves_shannon_entropy` | Discharge, or accept as a stated postulate | class A — carrier/quotient issue | -| `cno_zero_energy_dissipation_derived` | Rename, or supply `internal_energy` CNO-invariance | `internal_energy` is an opaque `Parameter` with no preservation law, so this cannot be a pure derivation | -| Absolute-zero brainfuck interpreter | Interpreter preserves CNO properties | Claims of computational zero need formal backing | -| Absolute-zero whitespace interpreter | Same as brainfuck — CNO preservation | Both esoteric interpreters need the same guarantee | -| Aletheia verification checks | Verification pipeline produces sound results | Rhodibot extraction depends on correct checks | -| Quantum mechanics proofs | Extend QuantumMechanicsExact.v coverage | Existing proofs are partial | - -**Not on this list: `y_not_cno`.** It is not a "concrete, closable proof obligation". -The in-source rationale explains why: a rigorous proof must rule out reaching the -argument under *every* interleaving of `beta_reduce` (which permits reduction under -binders and on either side of an application), requiring an invariant closed under the -full reduction congruence, or a coinductive / step-indexed non-termination argument. -Genuinely out of scope, not merely tedious. - -## Recommended Prover - -**Coq** — the existing proof infrastructure is in Coq. Aletheia (Rust) verification -would benefit from an **Idris2** ABI layer. - -## Priority - -**MEDIUM** — the proof infrastructure is real and its trusted base is honestly -documented. The one genuinely urgent item is the three **unsound** axioms: they are -currently unused, so this is cheap to fix now and expensive to discover later. - -## 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/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..75518d1 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,65 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|main |:white_check_mark: +|=== + +=== Reporting a Vulnerability + +If you discover a security vulnerability in this project, please report +it responsibly: + +[arabic] +. *Do NOT* create a public GitHub issue for security vulnerabilities +. Send a private report to the repository maintainers via GitHub’s +private vulnerability reporting feature +. Include as much detail as possible: +* Description of the vulnerability +* Steps to reproduce +* Potential impact +* Suggested fix (if any) + +=== Security Measures + +This repository implements the following security practices: + +==== GitHub Actions Security + +* *SHA-pinned actions*: All GitHub Actions are pinned to specific commit +SHAs to prevent supply chain attacks +* *Minimal permissions*: Workflows use the least privilege principle +with `+contents: read+` permission +* *SSH host key verification*: Known hosts are verified to prevent MITM +attacks during mirroring +* *Concurrency controls*: Prevents race conditions during parallel +workflow runs +* *Timeout limits*: All jobs have timeout limits to prevent resource +exhaustion + +==== Secret Management + +* SSH keys for mirror targets are stored as GitHub encrypted secrets +* Mirror operations are conditionally enabled via repository variables +* No secrets are logged or exposed in workflow outputs + +==== Force Push Warning + +This repository uses `+--force+` push for mirroring operations. This is +intentional for maintaining exact mirrors but means: - History on mirror +targets will be overwritten - Tags on mirror targets will be +force-updated - Only trusted maintainers should have push access to the +main branch + +=== Dependency Updates + +This project monitors for security updates in: - GitHub Actions +(checkout, ssh-agent) - SSH host keys for mirror targets + +=== Contact + +For security concerns, use GitHub’s private security advisory feature or +contact the repository maintainers directly. diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 0f62a43..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,58 +0,0 @@ - -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| main | :white_check_mark: | - -## Reporting a Vulnerability - -If you discover a security vulnerability in this project, please report it responsibly: - -1. **Do NOT** create a public GitHub issue for security vulnerabilities -2. Send a private report to the repository maintainers via GitHub's private vulnerability reporting feature -3. Include as much detail as possible: - - Description of the vulnerability - - Steps to reproduce - - Potential impact - - Suggested fix (if any) - -## Security Measures - -This repository implements the following security practices: - -### GitHub Actions Security - -- **SHA-pinned actions**: All GitHub Actions are pinned to specific commit SHAs to prevent supply chain attacks -- **Minimal permissions**: Workflows use the least privilege principle with `contents: read` permission -- **SSH host key verification**: Known hosts are verified to prevent MITM attacks during mirroring -- **Concurrency controls**: Prevents race conditions during parallel workflow runs -- **Timeout limits**: All jobs have timeout limits to prevent resource exhaustion - -### Secret Management - -- SSH keys for mirror targets are stored as GitHub encrypted secrets -- Mirror operations are conditionally enabled via repository variables -- No secrets are logged or exposed in workflow outputs - -### Force Push Warning - -This repository uses `--force` push for mirroring operations. This is intentional for maintaining exact mirrors but means: -- History on mirror targets will be overwritten -- Tags on mirror targets will be force-updated -- Only trusted maintainers should have push access to the main branch - -## Dependency Updates - -This project monitors for security updates in: -- GitHub Actions (checkout, ssh-agent) -- SSH host keys for mirror targets - -## Contact - -For security concerns, use GitHub's private security advisory feature or contact the repository maintainers directly. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..79f6471 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,138 @@ +== TEST-NEEDS.md — maa-framework + +____ +Generated 2026-03-29 by punishing audit. +____ + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +All CRG C requirements met across the absolute-zero crate: - Unit tests: +47 total (*29* in aletheia src, 13 brainfuck, 5 whitespace) - Smoke +tests: build and self-verification pass - P2P/property-based: 11 +deterministic property tests in +`+absolute-zero/tests/property_based.rs+` (100% pass) - E2E/reflexive: +10 brainfuck interpreter E2E tests in +`+absolute-zero/tests/brainfuck_e2e.rs+` (100% pass) - Security aspect +tests: 11 tests in `+absolute-zero/tests/security_aspects.rs+` (100% +pass) - Criterion benchmarks: +`+absolute-zero/benches/cno_benchmarks.rs+` (compiles and runs) + +____ +*Updated 2026-07-29.* aletheia unit tests went 26 → *29*: three new +tests for SHA-pin detection (PR #144), added alongside a fix for a check +that could never fail. One tautological `+assert!(true)+` was replaced +with a real assertion at the same time. `+absolute-zero/+` is a +submodule — its tests run in the upstream repo, not in this repository’s +CI. +____ + +==== The 27 failing aletheia integration tests + +They fail *by design, not by regression* — and the distinction matters: + +`+tests/integration_tests.rs+` (806 lines, 32 tests) describes a CLI +that has never been written: 16 Bronze checks plus Silver, `+--help+`, +`+--version+`, `+--verbose+`, `+--badge+`, `+--init-hook+`, +`+--format=+`, HTML output. `+main.rs+` currently parses `++` +plus `+--json+`/`+--sarif+` and wires *three* checks. + +____ +[!CAUTION] Every assertion in that suite is on a *stdout substring*, +e.g. +`+assert!(stdout.contains("Bronze-level RSR compliance: ACHIEVED"))+`. +That pins the _wording_ of the verdict and says nothing about what the +checks must verify — so the whole suite can be satisfied by checks that +verify nothing. + +*Do not "`fix`" these by writing checks that emit the expected strings.* +That would invent a definition of RSR compliance and encode it as +canonical, while a definition already exists in the estate (hypatia’s +`+rsr-conformance+` oracle). Tracked as issue #124, blocked on that +source-of-truth ruling. +____ + +They are deliberately *not* in the CI gate and *not* in `+just test+` +(`+--bins+` only). Adding them without resolving #124 would make the bar +green by breaking it. + +=== Current State + +[width="100%",cols="50%,25%,25%",options="header",] +|=== +|Category |Count |Notes +|Unit tests |0 |No inline tests in source + +|Integration |3 |absolute-zero FFI integration_test.zig, aletheia FFI +integration_test.zig, rhodibot integration_tests.rs + +|E2E |0 |None + +|Benchmarks |1 |aletheia/benches/verification_benchmark.rs — uses +std::time, not criterion (manual benchmark, not automated) +|=== + +*Source modules:* ~23 across 2 subsystems. absolute-zero: brainfuck +interpreter, whitespace interpreter, main + ABI/FFI. aletheia: checks, +config, main, output, types + rhodibot + rhodium-pipeline + ABI/FFI. + +=== What’s Missing + +==== P2P (Property-Based) Tests + +* [ ] absolute-zero: arbitrary brainfuck program fuzzing (already has +fuzz target, good) +* [ ] aletheia: arbitrary repo structure verification fuzzing +* [ ] Config parsing: property tests for all config formats + +==== E2E Tests + +* [ ] absolute-zero: compile -> execute -> verify program output +* [ ] aletheia: full RSR verification pipeline (scan repo -> check rules +-> report) +* [ ] rhodibot: full bot operation cycle +* [ ] rhodium-pipeline: extraction pipeline end-to-end + +==== Aspect Tests + +* *Security:* No tests for aletheia bypass (can a repo trick the +verifier?), rhodibot credential handling +* *Performance:* Benchmark exists but is manual (std::time), not +integrated into CI, not criterion-based +* *Concurrency:* No tests for parallel verification of multiple repos +* *Error handling:* No tests for malformed repos, missing files, invalid +configurations + +==== Build & Execution + +* [ ] `+cargo test+` for all Rust crates +* [ ] `+zig build test+` for FFI tests +* [ ] `+cargo fuzz+` for absolute-zero fuzz targets + +==== Benchmarks Needed + +* [ ] Verification speed per repo size/complexity (aletheia) +* [ ] Brainfuck/whitespace interpreter throughput (absolute-zero) +* [ ] rhodibot processing rate +* [ ] Pipeline extraction throughput + +==== Self-Tests + +* [ ] aletheia: verify itself against RSR standards +* [ ] Config schema validation +* [ ] ABI version agreement + +=== Priority + +*HIGH.* An RSR compliance verification framework that cannot verify +itself is the definition of irony. 23 source modules with 0 unit tests. +The 3 integration tests are a start but cover only FFI seams. The +benchmark is manual and not CI-integrated. Fuzz targets for +absolute-zero are good but need complementary structured tests. + +=== FAKE-FUZZ ALERT + +* `+tests/fuzz/placeholder.txt+` is a scorecard placeholder inherited +from rsr-template-repo — it does NOT provide real fuzz testing +* Replace with an actual fuzz harness (see +rsr-template-repo/tests/fuzz/README.adoc) or remove the file +* Priority: P2 — creates false impression of fuzz coverage diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 7950185..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,103 +0,0 @@ - -# TEST-NEEDS.md — maa-framework - -> Generated 2026-03-29 by punishing audit. - -## CRG Grade: C — ACHIEVED 2026-04-04 - -All CRG C requirements met across the absolute-zero crate: -- Unit tests: 47 total (**29** in aletheia src, 13 brainfuck, 5 whitespace) -- Smoke tests: build and self-verification pass -- P2P/property-based: 11 deterministic property tests in `absolute-zero/tests/property_based.rs` (100% pass) -- E2E/reflexive: 10 brainfuck interpreter E2E tests in `absolute-zero/tests/brainfuck_e2e.rs` (100% pass) -- Security aspect tests: 11 tests in `absolute-zero/tests/security_aspects.rs` (100% pass) -- Criterion benchmarks: `absolute-zero/benches/cno_benchmarks.rs` (compiles and runs) - -> **Updated 2026-07-29.** aletheia unit tests went 26 → **29**: three new tests for -> SHA-pin detection (PR #144), added alongside a fix for a check that could never -> fail. One tautological `assert!(true)` was replaced with a real assertion at the -> same time. `absolute-zero/` is a submodule — its tests run in the upstream repo, -> not in this repository's CI. - -### The 27 failing aletheia integration tests - -They fail **by design, not by regression** — and the distinction matters: - -`tests/integration_tests.rs` (806 lines, 32 tests) describes a CLI that has never -been written: 16 Bronze checks plus Silver, `--help`, `--version`, `--verbose`, -`--badge`, `--init-hook`, `--format=`, HTML output. `main.rs` currently parses -`` plus `--json`/`--sarif` and wires **three** checks. - -> [!CAUTION] -> Every assertion in that suite is on a **stdout substring**, e.g. -> `assert!(stdout.contains("Bronze-level RSR compliance: ACHIEVED"))`. That pins -> the *wording* of the verdict and says nothing about what the checks must -> verify — so the whole suite can be satisfied by checks that verify nothing. -> -> **Do not "fix" these by writing checks that emit the expected strings.** That -> would invent a definition of RSR compliance and encode it as canonical, while -> a definition already exists in the estate (hypatia's `rsr-conformance` oracle). -> Tracked as issue #124, blocked on that source-of-truth ruling. - -They are deliberately **not** in the CI gate and **not** in `just test` -(`--bins` only). Adding them without resolving #124 would make the bar green by -breaking it. - -## Current State - -| Category | Count | Notes | -|-------------|-------|-------| -| Unit tests | 0 | No inline tests in source | -| Integration | 3 | absolute-zero FFI integration_test.zig, aletheia FFI integration_test.zig, rhodibot integration_tests.rs | -| E2E | 0 | None | -| Benchmarks | 1 | aletheia/benches/verification_benchmark.rs — uses std::time, not criterion (manual benchmark, not automated) | - -**Source modules:** ~23 across 2 subsystems. absolute-zero: brainfuck interpreter, whitespace interpreter, main + ABI/FFI. aletheia: checks, config, main, output, types + rhodibot + rhodium-pipeline + ABI/FFI. - -## What's Missing - -### P2P (Property-Based) Tests -- [ ] absolute-zero: arbitrary brainfuck program fuzzing (already has fuzz target, good) -- [ ] aletheia: arbitrary repo structure verification fuzzing -- [ ] Config parsing: property tests for all config formats - -### E2E Tests -- [ ] absolute-zero: compile -> execute -> verify program output -- [ ] aletheia: full RSR verification pipeline (scan repo -> check rules -> report) -- [ ] rhodibot: full bot operation cycle -- [ ] rhodium-pipeline: extraction pipeline end-to-end - -### Aspect Tests -- **Security:** No tests for aletheia bypass (can a repo trick the verifier?), rhodibot credential handling -- **Performance:** Benchmark exists but is manual (std::time), not integrated into CI, not criterion-based -- **Concurrency:** No tests for parallel verification of multiple repos -- **Error handling:** No tests for malformed repos, missing files, invalid configurations - -### Build & Execution -- [ ] `cargo test` for all Rust crates -- [ ] `zig build test` for FFI tests -- [ ] `cargo fuzz` for absolute-zero fuzz targets - -### Benchmarks Needed -- [ ] Verification speed per repo size/complexity (aletheia) -- [ ] Brainfuck/whitespace interpreter throughput (absolute-zero) -- [ ] rhodibot processing rate -- [ ] Pipeline extraction throughput - -### Self-Tests -- [ ] aletheia: verify itself against RSR standards -- [ ] Config schema validation -- [ ] ABI version agreement - -## Priority - -**HIGH.** An RSR compliance verification framework that cannot verify itself is the definition of irony. 23 source modules with 0 unit tests. The 3 integration tests are a start but cover only FFI seams. The benchmark is manual and not CI-integrated. Fuzz targets for absolute-zero are good but need complementary structured tests. - -## FAKE-FUZZ ALERT - -- `tests/fuzz/placeholder.txt` is a scorecard placeholder inherited from rsr-template-repo — it does NOT provide real fuzz testing -- Replace with an actual fuzz harness (see rsr-template-repo/tests/fuzz/README.adoc) or remove the file -- Priority: P2 — creates false impression of fuzz coverage diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 87% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index b8ba783..7c0fa37 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,15 +1,8 @@ - - - +== MAA Framework — Project Topology -# MAA Framework — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ MAA FRAMEWORK │ │ (Full-Stack System Paradigm) │ @@ -44,11 +37,11 @@ Copyright (c) Jonathan D.A. Jewell │ Justfile / Mustfile .machine_readable/ │ │ Multi-Forge Hub 0-AI-MANIFEST.a2ml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── SPECIFICATIONS @@ -69,25 +62,26 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ██████░░░░ ~60% Governance stable, Core pending -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Framework Spec ───► Oblíbený Lang ───► Aletheia Kernel ───► Runtime │ │ │ │ ▼ ▼ ▼ ▼ RSR Standards ───► Infrastructure ───► Multi-Forge ──────► Compliance -``` +.... -## Update Protocol +=== Update Protocol This file is maintained by both humans and AI agents. When updating: -1. **After completing a component**: Change its bar and percentage -2. **After adding a component**: Add a new row in the appropriate section -3. **After architectural changes**: Update the ASCII diagram -4. **Date**: Update the `Last updated` comment at the top of this file +[arabic] +. *After completing a component*: Change its bar and percentage +. *After adding a component*: Add a new row in the appropriate section +. *After architectural changes*: Update the ASCII diagram +. *Date*: Update the `+Last updated+` comment at the top of this file -Progress bars use: `█` (filled) and `░` (empty), 10 characters wide. -Percentages: 0%, 10%, 20%, ... 100% (in 10% increments). +Progress bars use: `+█+` (filled) and `+░+` (empty), 10 characters wide. +Percentages: 0%, 10%, 20%, … 100% (in 10% increments). diff --git a/aletheia/ABI-FFI-README.md b/aletheia/ABI-FFI-README.adoc similarity index 74% rename from aletheia/ABI-FFI-README.md rename to aletheia/ABI-FFI-README.adoc index fc438c6..b2533a8 100644 --- a/aletheia/ABI-FFI-README.md +++ b/aletheia/ABI-FFI-README.adoc @@ -1,23 +1,22 @@ - -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# maa-framework ABI/FFI Documentation +== maa-framework ABI/FFI Documentation -## Overview +=== Overview -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -49,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... maa-framework/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -81,15 +80,17 @@ maa-framework/ ├── rust/ ├── rescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -101,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -115,13 +117,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -129,13 +132,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -144,71 +148,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/maa-framework.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -219,13 +230,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "maa-framework.h" int main() { @@ -241,16 +253,19 @@ int main() { maa-framework_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -lmaa-framework -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import maa-framework.ABI.Foreign main : IO () @@ -263,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "maa-framework")] extern "C" { fn maa-framework_init() -> *mut std::ffi::c_void; @@ -286,11 +302,12 @@ fn main() { maa-framework_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const libmaa-framework = "libmaa-framework" function init() @@ -316,27 +333,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -346,44 +366,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/maa-framework.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/maa-framework.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License MPL-2.0 -## See Also +=== See Also -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/aletheia/ALETHEIA-HANDOVER.adoc b/aletheia/ALETHEIA-HANDOVER.adoc new file mode 100644 index 0000000..86916b7 --- /dev/null +++ b/aletheia/ALETHEIA-HANDOVER.adoc @@ -0,0 +1,203 @@ +== Aletheia Project Handover + +*For*: AI assistants starting work on the Aletheia project *Updated*: +2026-02-05 + +=== Conformance Badges + +link:conformance/RSR-CONFORMANCE.md[image:https://img.shields.io/badge/RSR-Bronze-cd7f32[RSR +Bronze]] +link:conformance/PALIMPSEST-CONFORMANCE.md[image:https://img.shields.io/badge/License-Palimpsest%20v0.8-blue[Palimpsest +License]] +link:conformance/OIKOS-CONFORMANCE.md[image:https://img.shields.io/badge/Oikos-Pending-lightgrey[Oikos +Pending]] +link:conformance/ECHIDNA-CONFORMANCE.md[image:https://img.shields.io/badge/Echidna-Pending-lightgrey[Echidna +Pending]] +link:docs/VALUE-CHAIN-POLICY.md[image:https://img.shields.io/badge/Value%20Chain-Defined-green[Value +Chain]] + +=== What is Aletheia? + +*Aletheia* (ἀλήθεια - "`truth`", "`disclosure`", "`unconcealment`") is +the *precursor research project* for building a reversible operating +system based on Minix. + +==== Core Purpose + +Aletheia explores *reversible system operations* - the foundational +research required before undertaking a full rewrite of Minix into a +modern, reversible operating system (*r-Minix*). + +==== What Aletheia is NOT + +* ❌ NOT an RSR compliance checking tool (that’s +link:extraction/rhodibot/[rhodibot]) +* ❌ NOT a CI/CD pipeline generator (that’s +link:extraction/rhodium-pipeline/[rhodium-pipeline]) +* ❌ NOT just about repository standards + +==== What Aletheia IS + +* ✅ Research into reversible computing at the OS level +* ✅ Practical application of CNO (Certified Null Operation) theory +* ✅ Precursor work for r-Minix +* ✅ Connected to +https://gitlab.com/hyperpolymath/absolute-zero[Absolute Zero] formal +proofs + +=== Value Chain Position + +.... +┌────────────────────────────────────────────────────────────────┐ +│ ALETHEIA VALUE CHAIN │ +├────────────────────────────────────────────────────────────────┤ +│ │ +│ INBOUND OPERATIONS OUTBOUND │ +│ ════════ ══════════ ════════ │ +│ Absolute Zero Reversible CCCP Stack │ +│ • CNO proofs Minix research • Valence Shell │ +│ • Landauer • OS primitives • Future r-Minix │ +│ • Bennett • Undo/redo • Svalinn integration │ +│ • State capture │ +│ │ +└────────────────────────────────────────────────────────────────┘ +.... + +For the complete value chain model, see +link:docs/VALUE-CHAIN-POLICY.md[VALUE-CHAIN-POLICY.md]. + +=== Theoretical Foundation + +Aletheia builds on *Absolute Zero* - formal verification of Certified +Null Operations: + +[width="100%",cols="41%,59%",options="header",] +|=== +|Concept |Description +|*CNO* |Certified Null Operation: `+op ;; reverse(op) ≡ identity+` + +|*Landauer’s Principle* |Computation dissipates heat (kT ln 2 per bit +erased) + +|*Bennett’s Insight* |Reversible computation = zero heat dissipation + +|*Reversibility* |Every operation has an inverse +|=== + +=== Ecosystem Connections + +.... + ┌─────────────────────┐ + │ absolute-zero │ + │ (Formal Proofs) │ + └──────────┬──────────┘ + │ provides CNOs + ▼ +┌───────────────┐ ┌─────────────────────┐ ┌───────────────┐ +│ valence-shell │◀───│ ALETHEIA │───▶│ r-Minix │ +│ (Reversible │ │ │ │ (FUTURE) │ +│ Filesystem) │ │ Precursor research │ │ │ +└───────────────┘ └─────────────────────┘ └───────────────┘ +.... + +=== Project Setup + +==== Bots Present + +* *echidnabot* - Formal proof-based code validation +* *oikos bot* - Economic/ecological analysis +* *rhodibot* - RSR compliance checking + +==== AI Support Files (.scm - Guile Scheme) + +[cols=",",options="header",] +|=== +|File |Purpose +|`+META.scm+` |Project metadata +|`+ECOSYSTEM.scm+` |Ecosystem connections +|`+STATE.scm+` |Current project state +|`+PLAYBOOK.scm+` |Development workflows +|`+AGENTIC.scm+` |AI agent configuration +|`+NEUROSYM.scm+` |Neurosymbolic settings +|=== + +==== Build System + +* `+mustfile+` - Hyperpolymath build/task automation + +==== Licensing + +* *Primary*: link:LICENSE[Palimpsest License (MPL-2.0)] + +=== Quick Reference + +==== Language Policy + +[cols=",",options="header",] +|=== +|Allowed |Use Case +|Rust |Systems, performance-critical +|ReScript |Application code +|Deno |Runtime +|Gleam |Backend services +|=== + +[cols=",",options="header",] +|=== +|Banned |Use Instead +|TypeScript |ReScript +|Node.js/npm |Deno +|Go |Rust +|Python (general) |Rust/AffineScript +|=== + +==== Key Files + +[cols=",",options="header",] +|=== +|File |Purpose +|`+ALETHEIA-HANDOVER.md+` |This file - project handover +|`+CROSSREPO-HANDOVER.md+` |Full ecosystem documentation +|`+CLAUDE.md+` |AI assistant instructions +|`+docs/VALUE-CHAIN-POLICY.md+` |Value chain model +|`+conformance/+` |Conformance reports +|=== + +=== Conformance Reports + +All conformance reports are in the link:conformance/[`+conformance/+`] +folder: + +[width="100%",cols="29%,27%,44%",options="header",] +|=== +|Report |Status |Description +|link:conformance/RSR-CONFORMANCE.md[RSR-CONFORMANCE.md] |Bronze +|Repository standards + +|link:conformance/PALIMPSEST-CONFORMANCE.md[PALIMPSEST-CONFORMANCE.md] +|Active |License compliance + +|link:conformance/OIKOS-CONFORMANCE.md[OIKOS-CONFORMANCE.md] |Pending +|Economic/ecological + +|link:conformance/ECHIDNA-CONFORMANCE.md[ECHIDNA-CONFORMANCE.md] +|Pending |Formal verification +|=== + +=== Getting Started + +[arabic] +. *Read this document* to understand Aletheia’s purpose +. *Check CLAUDE.md* for development constraints +. *Review conformance/* for current compliance status +. *Start with the research* - focus on reversible OS primitives + +=== Contact + +*Jonathan D. A. Jewell* - GitLab: +https://gitlab.com/hyperpolymath[@hyperpolymath] - GitHub: +https://github.com/Hyperpolymath[@Hyperpolymath] + +''''' + +_Aletheia: Unconcealing the path to reversible operating systems._ diff --git a/aletheia/ALETHEIA-HANDOVER.md b/aletheia/ALETHEIA-HANDOVER.md deleted file mode 100644 index 00a78a1..0000000 --- a/aletheia/ALETHEIA-HANDOVER.md +++ /dev/null @@ -1,163 +0,0 @@ - -# Aletheia Project Handover - -**For**: AI assistants starting work on the Aletheia project -**Updated**: 2026-02-05 - -## Conformance Badges - -[![RSR Bronze](https://img.shields.io/badge/RSR-Bronze-cd7f32)](conformance/RSR-CONFORMANCE.md) -[![Palimpsest License](https://img.shields.io/badge/License-Palimpsest%20v0.8-blue)](conformance/PALIMPSEST-CONFORMANCE.md) -[![Oikos Pending](https://img.shields.io/badge/Oikos-Pending-lightgrey)](conformance/OIKOS-CONFORMANCE.md) -[![Echidna Pending](https://img.shields.io/badge/Echidna-Pending-lightgrey)](conformance/ECHIDNA-CONFORMANCE.md) -[![Value Chain](https://img.shields.io/badge/Value%20Chain-Defined-green)](docs/VALUE-CHAIN-POLICY.md) - -## What is Aletheia? - -**Aletheia** (ἀλήθεια - "truth", "disclosure", "unconcealment") is the **precursor research project** for building a reversible operating system based on Minix. - -### Core Purpose - -Aletheia explores **reversible system operations** - the foundational research required before undertaking a full rewrite of Minix into a modern, reversible operating system (**r-Minix**). - -### What Aletheia is NOT - -- ❌ NOT an RSR compliance checking tool (that's [rhodibot](extraction/rhodibot/)) -- ❌ NOT a CI/CD pipeline generator (that's [rhodium-pipeline](extraction/rhodium-pipeline/)) -- ❌ NOT just about repository standards - -### What Aletheia IS - -- ✅ Research into reversible computing at the OS level -- ✅ Practical application of CNO (Certified Null Operation) theory -- ✅ Precursor work for r-Minix -- ✅ Connected to [Absolute Zero](https://gitlab.com/hyperpolymath/absolute-zero) formal proofs - -## Value Chain Position - -``` -┌────────────────────────────────────────────────────────────────┐ -│ ALETHEIA VALUE CHAIN │ -├────────────────────────────────────────────────────────────────┤ -│ │ -│ INBOUND OPERATIONS OUTBOUND │ -│ ════════ ══════════ ════════ │ -│ Absolute Zero Reversible CCCP Stack │ -│ • CNO proofs Minix research • Valence Shell │ -│ • Landauer • OS primitives • Future r-Minix │ -│ • Bennett • Undo/redo • Svalinn integration │ -│ • State capture │ -│ │ -└────────────────────────────────────────────────────────────────┘ -``` - -For the complete value chain model, see [VALUE-CHAIN-POLICY.md](docs/VALUE-CHAIN-POLICY.md). - -## Theoretical Foundation - -Aletheia builds on **Absolute Zero** - formal verification of Certified Null Operations: - -| Concept | Description | -|---------|-------------| -| **CNO** | Certified Null Operation: `op ;; reverse(op) ≡ identity` | -| **Landauer's Principle** | Computation dissipates heat (kT ln 2 per bit erased) | -| **Bennett's Insight** | Reversible computation = zero heat dissipation | -| **Reversibility** | Every operation has an inverse | - -## Ecosystem Connections - -``` - ┌─────────────────────┐ - │ absolute-zero │ - │ (Formal Proofs) │ - └──────────┬──────────┘ - │ provides CNOs - ▼ -┌───────────────┐ ┌─────────────────────┐ ┌───────────────┐ -│ valence-shell │◀───│ ALETHEIA │───▶│ r-Minix │ -│ (Reversible │ │ │ │ (FUTURE) │ -│ Filesystem) │ │ Precursor research │ │ │ -└───────────────┘ └─────────────────────┘ └───────────────┘ -``` - -## Project Setup - -### Bots Present -- **echidnabot** - Formal proof-based code validation -- **oikos bot** - Economic/ecological analysis -- **rhodibot** - RSR compliance checking - -### AI Support Files (.scm - Guile Scheme) -| File | Purpose | -|------|---------| -| `META.scm` | Project metadata | -| `ECOSYSTEM.scm` | Ecosystem connections | -| `STATE.scm` | Current project state | -| `PLAYBOOK.scm` | Development workflows | -| `AGENTIC.scm` | AI agent configuration | -| `NEUROSYM.scm` | Neurosymbolic settings | - -### Build System -- `mustfile` - Hyperpolymath build/task automation - -### Licensing -- **Primary**: [Palimpsest License (MPL-2.0)](LICENSE) - -## Quick Reference - -### Language Policy - -| Allowed | Use Case | -|---------|----------| -| Rust | Systems, performance-critical | -| ReScript | Application code | -| Deno | Runtime | -| Gleam | Backend services | - -| Banned | Use Instead | -|--------|-------------| -| TypeScript | ReScript | -| Node.js/npm | Deno | -| Go | Rust | -| Python (general) | Rust/AffineScript | - -### Key Files - -| File | Purpose | -|------|---------| -| `ALETHEIA-HANDOVER.md` | This file - project handover | -| `CROSSREPO-HANDOVER.md` | Full ecosystem documentation | -| `CLAUDE.md` | AI assistant instructions | -| `docs/VALUE-CHAIN-POLICY.md` | Value chain model | -| `conformance/` | Conformance reports | - -## Conformance Reports - -All conformance reports are in the [`conformance/`](conformance/) folder: - -| Report | Status | Description | -|--------|--------|-------------| -| [RSR-CONFORMANCE.md](conformance/RSR-CONFORMANCE.md) | Bronze | Repository standards | -| [PALIMPSEST-CONFORMANCE.md](conformance/PALIMPSEST-CONFORMANCE.md) | Active | License compliance | -| [OIKOS-CONFORMANCE.md](conformance/OIKOS-CONFORMANCE.md) | Pending | Economic/ecological | -| [ECHIDNA-CONFORMANCE.md](conformance/ECHIDNA-CONFORMANCE.md) | Pending | Formal verification | - -## Getting Started - -1. **Read this document** to understand Aletheia's purpose -2. **Check CLAUDE.md** for development constraints -3. **Review conformance/** for current compliance status -4. **Start with the research** - focus on reversible OS primitives - -## Contact - -**Jonathan D. A. Jewell** -- GitLab: [@hyperpolymath](https://gitlab.com/hyperpolymath) -- GitHub: [@Hyperpolymath](https://github.com/Hyperpolymath) - ---- - -*Aletheia: Unconcealing the path to reversible operating systems.* diff --git a/aletheia/CHANGELOG.adoc b/aletheia/CHANGELOG.adoc index e64fe48..913b4b6 100644 --- a/aletheia/CHANGELOG.adoc +++ b/aletheia/CHANGELOG.adoc @@ -1,99 +1,114 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Changelog +== 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.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -== [Unreleased] - -=== Added - -- **JSON output format**: `--format json` for CI/CD integration -- **Quiet mode**: `-q` / `--quiet` - outputs only PASS/FAIL -- **Verbose mode**: `-v` / `--verbose` - detailed output with explanations -- **Distinct exit codes**: 0=success, 1=compliance failed, 2=security warning, 3=invalid path, 4=invalid args -- **GitHub Actions workflow**: `.github/workflows/aletheia.yml` template for GitHub users -- **Performance benchmarks**: `cargo run --release --bin verification_benchmark` -- **Help text**: `--help` with usage, options, exit codes, and examples -- **Version flag**: `--version` displays version information -- **Security warning system**: Three-level warning system (Info, Warning, Critical) -- **Symlink detection**: Detects symlinks and warns if they escape repository bounds -- **Verification timestamps**: ISO 8601 UTC timestamp in output (TOCTOU mitigation) -- **README.adoc support**: Accepts AsciiDoc README as alternative to Markdown -- **18 integration tests**: Comprehensive test coverage for all CLI features -- **ROADMAP.md**: Comprehensive roadmap from MVP to v10.0.0 -- **PRIORITIES.md**: MoSCoW prioritization document - -=== Changed - -- Consistent 16-check count regardless of .well-known directory existence -- Critical symlink warnings now cause verification failure -- Updated SECURITY.md with accurate threat model -- Updated MAINTAINERS.md with actual maintainer information -- Codebase expanded from ~300 lines to ~810 lines (still zero dependencies) - -=== Security - -- **Security Audit**: Conducted 2025-12-26, zero vulnerabilities found -- Removed false "large files" limitation from SECURITY.md (we don't read file contents) -- Added symlink escape detection to prevent directory traversal -- Exit code 2 reserved for security warnings - -=== Fixed - -- Self-verification now passes (was 76.9%, now 100%) -- Integration tests updated to match actual check count -- Removed unused code warnings - -== [0.1.0] - 2025-11-22 - -=== Added - -- **Initial release** of Aletheia RSR compliance verification tool -- **Core verification engine** for RSR Bronze-level compliance -- **Documentation checks**: README.md, LICENSE.txt, SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, MAINTAINERS.md, CHANGELOG.md -- **Well-known directory checks**: `.well-known/security.txt`, `.well-known/ai.txt`, `.well-known/humans.txt` -- **Build system checks**: Justfile, flake.nix, .gitlab-ci.yml -- **Source structure checks**: src/ directory, tests/ directory -- **Comprehensive test suite**: 5 unit tests with 100% pass rate -- **Zero dependencies**: Only uses Rust standard library -- **Offline-first**: No network calls, works completely air-gapped -- **Type safety**: Full Rust compile-time guarantees, zero unsafe blocks -- **Memory safety**: Rust ownership model, no manual memory management -- **Complete documentation**: - - README.md with quick start guide - - SECURITY.md with vulnerability disclosure policy - - CONTRIBUTING.md with contribution guidelines - - CODE_OF_CONDUCT.md with community standards - - MAINTAINERS.md with governance structure - - CHANGELOG.md (this file) -- **.well-known directory**: - - security.txt (RFC 9116 compliant) - - ai.txt (AI training policies) - - humans.txt (human attribution) -- **Build automation**: - - Justfile with 20+ recipes - - flake.nix for Nix reproducible builds - - .gitlab-ci.yml for CI/CD pipeline -- **Dual licensing**: MIT + Palimpsest v0.8 -- **TPCF Perimeter 3**: Community Sandbox - fully open contribution -- **RSR self-verification**: Aletheia verifies its own RSR compliance - -=== Design Decisions - -- **Single-file implementation**: All code in `src/main.rs` for easy auditing (~300 lines) -- **Zero unsafe code**: No `unsafe` blocks anywhere in the codebase -- **Explicit error handling**: All errors handled with `Result` and `Option` -- **Minimal attack surface**: No dependencies = no supply chain vulnerabilities -- **Clear output**: Human-readable compliance report with emoji indicators - -=== Architecture - -[source,] ----- +The format is based on https://keepachangelog.com/en/1.0.0/[Keep a +Changelog], and this project adheres to +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Added + +* *JSON output format*: `+--format json+` for CI/CD integration +* *Quiet mode*: `+-q+` / `+--quiet+` - outputs only PASS/FAIL +* *Verbose mode*: `+-v+` / `+--verbose+` - detailed output with +explanations +* *Distinct exit codes*: 0=success, 1=compliance failed, 2=security +warning, 3=invalid path, 4=invalid args +* *GitHub Actions workflow*: `+.github/workflows/aletheia.yml+` template +for GitHub users +* *Performance benchmarks*: +`+cargo run --release --bin verification_benchmark+` +* *Help text*: `+--help+` with usage, options, exit codes, and examples +* *Version flag*: `+--version+` displays version information +* *Security warning system*: Three-level warning system (Info, Warning, +Critical) +* *Symlink detection*: Detects symlinks and warns if they escape +repository bounds +* *Verification timestamps*: ISO 8601 UTC timestamp in output (TOCTOU +mitigation) +* *README.adoc support*: Accepts AsciiDoc README as alternative to +Markdown +* *18 integration tests*: Comprehensive test coverage for all CLI +features +* *ROADMAP.md*: Comprehensive roadmap from MVP to v10.0.0 +* *PRIORITIES.md*: MoSCoW prioritization document + +==== Changed + +* Consistent 16-check count regardless of .well-known directory +existence +* Critical symlink warnings now cause verification failure +* Updated SECURITY.md with accurate threat model +* Updated MAINTAINERS.md with actual maintainer information +* Codebase expanded from ~300 lines to ~810 lines (still zero +dependencies) + +==== Security + +* *Security Audit*: Conducted 2025-12-26, zero vulnerabilities found +* Removed false "`large files`" limitation from SECURITY.md (we don’t +read file contents) +* Added symlink escape detection to prevent directory traversal +* Exit code 2 reserved for security warnings + +==== Fixed + +* Self-verification now passes (was 76.9%, now 100%) +* Integration tests updated to match actual check count +* Removed unused code warnings + +=== [0.1.0] - 2025-11-22 + +==== Added + +* *Initial release* of Aletheia RSR compliance verification tool +* *Core verification engine* for RSR Bronze-level compliance +* *Documentation checks*: README.md, LICENSE.txt, SECURITY.md, +CONTRIBUTING.md, CODE_OF_CONDUCT.md, MAINTAINERS.md, CHANGELOG.md +* *Well-known directory checks*: `+.well-known/security.txt+`, +`+.well-known/ai.txt+`, `+.well-known/humans.txt+` +* *Build system checks*: Justfile, flake.nix, .gitlab-ci.yml +* *Source structure checks*: src/ directory, tests/ directory +* *Comprehensive test suite*: 5 unit tests with 100% pass rate +* *Zero dependencies*: Only uses Rust standard library +* *Offline-first*: No network calls, works completely air-gapped +* *Type safety*: Full Rust compile-time guarantees, zero unsafe blocks +* *Memory safety*: Rust ownership model, no manual memory management +* *Complete documentation*: +** README.md with quick start guide +** SECURITY.md with vulnerability disclosure policy +** CONTRIBUTING.md with contribution guidelines +** CODE_OF_CONDUCT.md with community standards +** MAINTAINERS.md with governance structure +** CHANGELOG.md (this file) +* *.well-known directory*: +** security.txt (RFC 9116 compliant) +** ai.txt (AI training policies) +** humans.txt (human attribution) +* *Build automation*: +** Justfile with 20+ recipes +** flake.nix for Nix reproducible builds +** .gitlab-ci.yml for CI/CD pipeline +* *Dual licensing*: MIT + Palimpsest v0.8 +* *TPCF Perimeter 3*: Community Sandbox - fully open contribution +* *RSR self-verification*: Aletheia verifies its own RSR compliance + +==== Design Decisions + +* *Single-file implementation*: All code in `+src/main.rs+` for easy +auditing (~300 lines) +* *Zero unsafe code*: No `+unsafe+` blocks anywhere in the codebase +* *Explicit error handling*: All errors handled with `+Result+` and +`+Option+` +* *Minimal attack surface*: No dependencies = no supply chain +vulnerabilities +* *Clear output*: Human-readable compliance report with emoji indicators + +==== Architecture + +.... aletheia/ ├── src/ │ └── main.rs # Single-file implementation @@ -107,77 +122,83 @@ aletheia/ ├── flake.nix # Nix reproducible builds ├── .gitlab-ci.yml # CI/CD pipeline └── docs/ # Documentation -[source,] ----- +.... -=== Known Limitations +==== Known Limitations -- **Bronze-level only**: Only checks Bronze-level compliance (Silver/Gold/Platinum planned) -- **No custom checks**: Cannot define custom verification rules (planned) -- **Single repository**: Cannot batch-analyze multiple repositories (planned) -- **No configuration file**: Settings must be passed as CLI arguments (planned) +* *Bronze-level only*: Only checks Bronze-level compliance +(Silver/Gold/Platinum planned) +* *No custom checks*: Cannot define custom verification rules (planned) +* *Single repository*: Cannot batch-analyze multiple repositories +(planned) +* *No configuration file*: Settings must be passed as CLI arguments +(planned) -== Version History +=== Version History -=== Version Numbering +==== Version Numbering -We follow [Semantic Versioning](https://semver.org/): +We follow https://semver.org/[Semantic Versioning]: -- **MAJOR**: Incompatible API changes -- **MINOR**: Backwards-compatible functionality additions -- **PATCH**: Backwards-compatible bug fixes +* *MAJOR*: Incompatible API changes +* *MINOR*: Backwards-compatible functionality additions +* *PATCH*: Backwards-compatible bug fixes -=== Release Cadence +==== Release Cadence -- **Patch releases**: As needed for bug fixes -- **Minor releases**: Monthly (if features are ready) -- **Major releases**: When breaking changes are necessary +* *Patch releases*: As needed for bug fixes +* *Minor releases*: Monthly (if features are ready) +* *Major releases*: When breaking changes are necessary -== Migration Guides +=== Migration Guides -=== From Pre-1.0 to 1.0 +==== From Pre-1.0 to 1.0 -*Not applicable - this is the initial release* +_Not applicable - this is the initial release_ -== Security Advisories +=== Security Advisories -Security issues are tracked separately. See [SECURITY.md](SECURITY.md) for the vulnerability disclosure process. +Security issues are tracked separately. See SECURITY.md for the +vulnerability disclosure process. -=== Security Fixes +==== Security Fixes -*None yet - this is the initial release* +_None yet - this is the initial release_ -== Deprecation Notices +=== Deprecation Notices -*None yet - this is the initial release* +_None yet - this is the initial release_ -== Contributors +=== Contributors Thank you to all contributors who made this release possible! -- Initial design and implementation by MAA Framework team +* Initial design and implementation by MAA Framework team -== [Definition of Done] +=== [Definition of Done] For a release to be considered complete, it must: -1. ✅ Pass all tests (`cargo test`) -2. ✅ Pass all lints (`cargo clippy`) -3. ✅ Be formatted (`cargo fmt`) -4. ✅ Self-verify RSR compliance (`cargo run`) -5. ✅ Update CHANGELOG.md -6. ✅ Update version in Cargo.toml -7. ✅ Tag release in Git -8. ✅ Build release binary (`cargo build --release`) - -== Links - -- **Repository**: https://gitlab.com/maa-framework/6-the-foundation/aletheia -- **Issues**: https://gitlab.com/maa-framework/6-the-foundation/aletheia/-/issues -- **Merge Requests**: https://gitlab.com/maa-framework/6-the-foundation/aletheia/-/merge_requests - ---- - -**Maintained by**: MAA Framework -**Contact**: maintainers@maa-framework.org -**License**: MIT OR Palimpsest-0.8 +[arabic] +. ✅ Pass all tests (`+cargo test+`) +. ✅ Pass all lints (`+cargo clippy+`) +. ✅ Be formatted (`+cargo fmt+`) +. ✅ Self-verify RSR compliance (`+cargo run+`) +. ✅ Update CHANGELOG.md +. ✅ Update version in Cargo.toml +. ✅ Tag release in Git +. ✅ Build release binary (`+cargo build --release+`) + +=== Links + +* *Repository*: +https://gitlab.com/maa-framework/6-the-foundation/aletheia +* *Issues*: +https://gitlab.com/maa-framework/6-the-foundation/aletheia/-/issues +* *Merge Requests*: +https://gitlab.com/maa-framework/6-the-foundation/aletheia/-/merge_requests + +''''' + +*Maintained by*: MAA Framework *Contact*: maintainers@maa-framework.org +*License*: MIT OR Palimpsest-0.8 diff --git a/aletheia/CHANGELOG.md b/aletheia/CHANGELOG.md deleted file mode 100644 index b1a806f..0000000 --- a/aletheia/CHANGELOG.md +++ /dev/null @@ -1,183 +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.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added - -- **JSON output format**: `--format json` for CI/CD integration -- **Quiet mode**: `-q` / `--quiet` - outputs only PASS/FAIL -- **Verbose mode**: `-v` / `--verbose` - detailed output with explanations -- **Distinct exit codes**: 0=success, 1=compliance failed, 2=security warning, 3=invalid path, 4=invalid args -- **GitHub Actions workflow**: `.github/workflows/aletheia.yml` template for GitHub users -- **Performance benchmarks**: `cargo run --release --bin verification_benchmark` -- **Help text**: `--help` with usage, options, exit codes, and examples -- **Version flag**: `--version` displays version information -- **Security warning system**: Three-level warning system (Info, Warning, Critical) -- **Symlink detection**: Detects symlinks and warns if they escape repository bounds -- **Verification timestamps**: ISO 8601 UTC timestamp in output (TOCTOU mitigation) -- **README.adoc support**: Accepts AsciiDoc README as alternative to Markdown -- **18 integration tests**: Comprehensive test coverage for all CLI features -- **ROADMAP.md**: Comprehensive roadmap from MVP to v10.0.0 -- **PRIORITIES.md**: MoSCoW prioritization document - -### Changed - -- Consistent 16-check count regardless of .well-known directory existence -- Critical symlink warnings now cause verification failure -- Updated SECURITY.md with accurate threat model -- Updated MAINTAINERS.md with actual maintainer information -- Codebase expanded from ~300 lines to ~810 lines (still zero dependencies) - -### Security - -- **Security Audit**: Conducted 2025-12-26, zero vulnerabilities found -- Removed false "large files" limitation from SECURITY.md (we don't read file contents) -- Added symlink escape detection to prevent directory traversal -- Exit code 2 reserved for security warnings - -### Fixed - -- Self-verification now passes (was 76.9%, now 100%) -- Integration tests updated to match actual check count -- Removed unused code warnings - -## [0.1.0] - 2025-11-22 - -### Added - -- **Initial release** of Aletheia RSR compliance verification tool -- **Core verification engine** for RSR Bronze-level compliance -- **Documentation checks**: README.md, LICENSE.txt, SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, MAINTAINERS.md, CHANGELOG.md -- **Well-known directory checks**: `.well-known/security.txt`, `.well-known/ai.txt`, `.well-known/humans.txt` -- **Build system checks**: Justfile, flake.nix, .gitlab-ci.yml -- **Source structure checks**: src/ directory, tests/ directory -- **Comprehensive test suite**: 5 unit tests with 100% pass rate -- **Zero dependencies**: Only uses Rust standard library -- **Offline-first**: No network calls, works completely air-gapped -- **Type safety**: Full Rust compile-time guarantees, zero unsafe blocks -- **Memory safety**: Rust ownership model, no manual memory management -- **Complete documentation**: - - README.md with quick start guide - - SECURITY.md with vulnerability disclosure policy - - CONTRIBUTING.md with contribution guidelines - - CODE_OF_CONDUCT.md with community standards - - MAINTAINERS.md with governance structure - - CHANGELOG.md (this file) -- **.well-known directory**: - - security.txt (RFC 9116 compliant) - - ai.txt (AI training policies) - - humans.txt (human attribution) -- **Build automation**: - - Justfile with 20+ recipes - - flake.nix for Nix reproducible builds - - .gitlab-ci.yml for CI/CD pipeline -- **Dual licensing**: MIT + Palimpsest v0.8 -- **TPCF Perimeter 3**: Community Sandbox - fully open contribution -- **RSR self-verification**: Aletheia verifies its own RSR compliance - -### Design Decisions - -- **Single-file implementation**: All code in `src/main.rs` for easy auditing (~300 lines) -- **Zero unsafe code**: No `unsafe` blocks anywhere in the codebase -- **Explicit error handling**: All errors handled with `Result` and `Option` -- **Minimal attack surface**: No dependencies = no supply chain vulnerabilities -- **Clear output**: Human-readable compliance report with emoji indicators - -### Architecture - -``` -aletheia/ -├── src/ -│ └── main.rs # Single-file implementation -├── tests/ # Integration tests (future) -├── .well-known/ # Security and metadata -│ ├── security.txt # RFC 9116 security contact -│ ├── ai.txt # AI training policies -│ └── humans.txt # Human attribution -├── Cargo.toml # Zero dependencies -├── Justfile # Build automation -├── flake.nix # Nix reproducible builds -├── .gitlab-ci.yml # CI/CD pipeline -└── docs/ # Documentation -``` - -### Known Limitations - -- **Bronze-level only**: Only checks Bronze-level compliance (Silver/Gold/Platinum planned) -- **No custom checks**: Cannot define custom verification rules (planned) -- **Single repository**: Cannot batch-analyze multiple repositories (planned) -- **No configuration file**: Settings must be passed as CLI arguments (planned) - -## Version History - -### Version Numbering - -We follow [Semantic Versioning](https://semver.org/): - -- **MAJOR**: Incompatible API changes -- **MINOR**: Backwards-compatible functionality additions -- **PATCH**: Backwards-compatible bug fixes - -### Release Cadence - -- **Patch releases**: As needed for bug fixes -- **Minor releases**: Monthly (if features are ready) -- **Major releases**: When breaking changes are necessary - -## Migration Guides - -### From Pre-1.0 to 1.0 - -*Not applicable - this is the initial release* - -## Security Advisories - -Security issues are tracked separately. See [SECURITY.md](SECURITY.md) for the vulnerability disclosure process. - -### Security Fixes - -*None yet - this is the initial release* - -## Deprecation Notices - -*None yet - this is the initial release* - -## Contributors - -Thank you to all contributors who made this release possible! - -- Initial design and implementation by MAA Framework team - -## [Definition of Done] - -For a release to be considered complete, it must: - -1. ✅ Pass all tests (`cargo test`) -2. ✅ Pass all lints (`cargo clippy`) -3. ✅ Be formatted (`cargo fmt`) -4. ✅ Self-verify RSR compliance (`cargo run`) -5. ✅ Update CHANGELOG.md -6. ✅ Update version in Cargo.toml -7. ✅ Tag release in Git -8. ✅ Build release binary (`cargo build --release`) - -## Links - -- **Repository**: https://gitlab.com/maa-framework/6-the-foundation/aletheia -- **Issues**: https://gitlab.com/maa-framework/6-the-foundation/aletheia/-/issues -- **Merge Requests**: https://gitlab.com/maa-framework/6-the-foundation/aletheia/-/merge_requests - ---- - -**Maintained by**: MAA Framework -**Contact**: maintainers@maa-framework.org -**License**: MIT OR Palimpsest-0.8 diff --git a/aletheia/CODE_OF_CONDUCT.adoc b/aletheia/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..48b237a --- /dev/null +++ b/aletheia/CODE_OF_CONDUCT.adoc @@ -0,0 +1,204 @@ +== Code of Conduct + +=== 🤝 Our Pledge + +We as members, contributors, and leaders pledge to make participation in +our community 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, color, 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. + +=== 🌟 Our Standards + +==== Positive Behavior + +Examples of behavior that contributes to a positive environment: + +* *Empathy and kindness* toward other people +* *Respect* for differing opinions, viewpoints, and experiences +* *Constructive feedback*, given and received gracefully +* *Accountability* for mistakes and learning from them +* *Focus* on what is best for the community +* *Collaboration* over competition + +==== Unacceptable Behavior + +Examples of unacceptable behavior include: + +* *Harassment*: Trolling, insulting/derogatory comments, personal or +political attacks +* *Privacy violations*: Publishing others’ private information without +explicit permission +* *Sexual attention*: Unwelcome sexual attention or advances +* *Professional misconduct*: Conduct inappropriate in a professional +setting +* *Dishonesty*: Plagiarism, misrepresentation, or intentional +misinformation + +=== 🛡️ Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our +standards of acceptable behavior and will take appropriate and fair +corrective action in response to any behavior that they deem +inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other +contributions that are not aligned with this Code of Conduct, and will +communicate reasons for moderation decisions when appropriate. + +=== 🌍 Scope + +This Code of Conduct applies within all community spaces, and also +applies when an individual is officially representing the community in +public spaces. Examples of representing our community include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an online or offline event +* Participating in project-related discussions + +=== 📋 Enforcement + +==== Reporting + +Instances of abusive, harassing, or otherwise unacceptable behavior may +be reported to the community leaders responsible for enforcement at: + +* *Email*: conduct@maa-framework.org +* *GitLab*: +https://gitlab.com/maa-framework/6-the-foundation/aletheia/-/issues/new?issue%5Bconfidential%5D=true[Confidential +Issue] + +All complaints will be reviewed and investigated promptly and fairly. + +==== Confidentiality + +All community leaders are obligated to respect the privacy and security +of the reporter of any incident. + +==== Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in +determining the consequences for any action they deem in violation of +this Code of Conduct: + +===== 1. Correction + +*Community Impact*: Use of inappropriate language or other behavior +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning from community leaders, +providing clarity around the nature of the violation and an explanation +of why the behavior was inappropriate. A public apology may be +requested. + +===== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period of +time. 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. + +===== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behavior. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. 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. + +===== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, 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. + +=== 💚 Emotional Safety Framework + +In addition to standard conduct guidelines, we recognize the importance +of *emotional safety* in open source: + +==== Psychological Safety + +* *Safe to experiment*: Contributors can try new ideas without fear of +humiliation +* *Safe to fail*: Mistakes are learning opportunities, not grounds for +punishment +* *Safe to dissent*: Disagreement is encouraged when done respectfully +* *Safe to be yourself*: Authentic expression is welcomed within +professional boundaries + +==== Reversibility Culture + +We embrace a culture where: + +* *Experiments are encouraged*: Git makes everything reversible +* *Early feedback is valued*: Share work-in-progress for collaborative +improvement +* *Iterations are normal*: First drafts are rarely perfect +* *Anxiety is reduced*: Knowing changes can be reverted reduces fear of +contribution + +==== Emotional Temperature Monitoring + +We encourage contributors to: + +* *Take breaks*: Step away when frustrated or overwhelmed +* *Ask for help*: Request support when stuck or uncertain +* *Set boundaries*: Decline work that exceeds capacity +* *Practice self-care*: Prioritize wellbeing over deadlines + +=== 🎯 TPCF Alignment + +This Code of Conduct aligns with the *Tri-Perimeter Contribution +Framework (TPCF)*: + +* *Perimeter 3 (Community Sandbox)*: Open contribution with quality +standards +* *Graduated Trust*: Build trust through consistent positive +contributions +* *Clear Boundaries*: Explicit guidelines for each perimeter level + +=== 📚 Attribution + +This Code of Conduct is adapted from the +https://www.contributor-covenant.org/[Contributor Covenant], version +2.1, with additions from the +https://gitlab.com/maa-framework[Comprehensive Contributor Code of +Practice (CCCP)] emphasizing emotional safety and psychological +wellbeing. + +=== 🔄 Updates + +This Code of Conduct may be updated periodically. Major changes will be +announced via: + +* GitLab announcements +* CHANGELOG.md entries +* Email to active contributors + +*Current Version*: 1.0 *Last Updated*: 2025-11-22 *Contact*: +conduct@maa-framework.org + +''''' + +_"`Be kind, for everyone you meet is fighting a hard battle.`" - Ian +Maclaren_ diff --git a/aletheia/CODE_OF_CONDUCT.md b/aletheia/CODE_OF_CONDUCT.md deleted file mode 100644 index 8366885..0000000 --- a/aletheia/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,149 +0,0 @@ - -# Code of Conduct - -## 🤝 Our Pledge - -We as members, contributors, and leaders pledge to make participation in our community 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, color, 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. - -## 🌟 Our Standards - -### Positive Behavior - -Examples of behavior that contributes to a positive environment: - -- **Empathy and kindness** toward other people -- **Respect** for differing opinions, viewpoints, and experiences -- **Constructive feedback**, given and received gracefully -- **Accountability** for mistakes and learning from them -- **Focus** on what is best for the community -- **Collaboration** over competition - -### Unacceptable Behavior - -Examples of unacceptable behavior include: - -- **Harassment**: Trolling, insulting/derogatory comments, personal or political attacks -- **Privacy violations**: Publishing others' private information without explicit permission -- **Sexual attention**: Unwelcome sexual attention or advances -- **Professional misconduct**: Conduct inappropriate in a professional setting -- **Dishonesty**: Plagiarism, misrepresentation, or intentional misinformation - -## 🛡️ Enforcement Responsibilities - -Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. - -Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned with this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. - -## 🌍 Scope - -This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an online or offline event -- Participating in project-related discussions - -## 📋 Enforcement - -### Reporting - -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at: - -- **Email**: conduct@maa-framework.org -- **GitLab**: [Confidential Issue](https://gitlab.com/maa-framework/6-the-foundation/aletheia/-/issues/new?issue[confidential]=true) - -All complaints will be reviewed and investigated promptly and fairly. - -### Confidentiality - -All community leaders are obligated to respect the privacy and security of the reporter of any incident. - -### Enforcement Guidelines - -Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: - -#### 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. - -#### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. 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. - -#### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. 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. - -#### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, 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. - -## 💚 Emotional Safety Framework - -In addition to standard conduct guidelines, we recognize the importance of **emotional safety** in open source: - -### Psychological Safety - -- **Safe to experiment**: Contributors can try new ideas without fear of humiliation -- **Safe to fail**: Mistakes are learning opportunities, not grounds for punishment -- **Safe to dissent**: Disagreement is encouraged when done respectfully -- **Safe to be yourself**: Authentic expression is welcomed within professional boundaries - -### Reversibility Culture - -We embrace a culture where: - -- **Experiments are encouraged**: Git makes everything reversible -- **Early feedback is valued**: Share work-in-progress for collaborative improvement -- **Iterations are normal**: First drafts are rarely perfect -- **Anxiety is reduced**: Knowing changes can be reverted reduces fear of contribution - -### Emotional Temperature Monitoring - -We encourage contributors to: - -- **Take breaks**: Step away when frustrated or overwhelmed -- **Ask for help**: Request support when stuck or uncertain -- **Set boundaries**: Decline work that exceeds capacity -- **Practice self-care**: Prioritize wellbeing over deadlines - -## 🎯 TPCF Alignment - -This Code of Conduct aligns with the **Tri-Perimeter Contribution Framework (TPCF)**: - -- **Perimeter 3 (Community Sandbox)**: Open contribution with quality standards -- **Graduated Trust**: Build trust through consistent positive contributions -- **Clear Boundaries**: Explicit guidelines for each perimeter level - -## 📚 Attribution - -This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1, with additions from the [Comprehensive Contributor Code of Practice (CCCP)](https://gitlab.com/maa-framework) emphasizing emotional safety and psychological wellbeing. - -## 🔄 Updates - -This Code of Conduct may be updated periodically. Major changes will be announced via: - -- GitLab announcements -- CHANGELOG.md entries -- Email to active contributors - -**Current Version**: 1.0 -**Last Updated**: 2025-11-22 -**Contact**: conduct@maa-framework.org - ---- - -*"Be kind, for everyone you meet is fighting a hard battle." - Ian Maclaren* diff --git a/aletheia/CONTRIBUTING.adoc b/aletheia/CONTRIBUTING.adoc index e9b1993..f726501 100644 --- a/aletheia/CONTRIBUTING.adoc +++ b/aletheia/CONTRIBUTING.adoc @@ -1,21 +1,60 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Contributing Guide +== Contributing to Aletheia -== Getting Started +Thank you for your interest in contributing to Aletheia! -1. Fork the repository -2. Create a feature branch from `main` -3. Sign off commits (`git commit -s`) -4. Submit a pull request +=== Getting Started -== Commit Guidelines +[arabic] +. Fork the repository on GitHub +. Clone your fork locally +. Create a feature branch from `+main+` +. Set up your development environment (see below) -* Conventional commits: `type(scope): description` -* Sign all commits (DCO required) -* Atomic, focused commits +=== Development Setup -== License +Aletheia requires only the Rust toolchain. No external dependencies. -Contributions licensed under project license. +[source,bash] +---- +# Clone and build +git clone https://github.com/hyperpolymath/aletheia.git +cd aletheia +cargo build +cargo test +---- +=== How to Contribute + +==== Reporting Issues + +Open an issue on GitHub with a clear description of the problem or +suggestion. + +==== Submitting Changes + +[arabic] +. Create a feature branch: `+git checkout -b feat/my-feature+` +. Make your changes following the code style below +. Run `+cargo test+` and `+cargo clippy -- -D warnings+` +. Sign off your commits: `+git commit -s+` +. Submit a pull request against `+main+` + +=== Pull Request Process + +* Keep PRs focused and atomic +* Include tests for new functionality +* Ensure all existing tests pass +* Follow conventional commit format: `+type(scope): description+` +* All PRs require review before merge + +=== Code Style + +* Zero external dependencies (use std library only) +* Zero unsafe code +* Run `+cargo fmt+` before committing +* All public items must have doc comments + +=== License + +Contributions are licensed under MPL-2.0. See CONTRIBUTING.adoc for full +details. diff --git a/aletheia/CONTRIBUTING.md b/aletheia/CONTRIBUTING.md deleted file mode 100644 index 202ae14..0000000 --- a/aletheia/CONTRIBUTING.md +++ /dev/null @@ -1,59 +0,0 @@ - -# Contributing to Aletheia - -Thank you for your interest in contributing to Aletheia! - -## Getting Started - -1. Fork the repository on GitHub -2. Clone your fork locally -3. Create a feature branch from `main` -4. Set up your development environment (see below) - -## Development Setup - -Aletheia requires only the Rust toolchain. No external dependencies. - -```bash -# Clone and build -git clone https://github.com/hyperpolymath/aletheia.git -cd aletheia -cargo build -cargo test -``` - -## How to Contribute - -### Reporting Issues - -Open an issue on GitHub with a clear description of the problem or suggestion. - -### Submitting Changes - -1. Create a feature branch: `git checkout -b feat/my-feature` -2. Make your changes following the code style below -3. Run `cargo test` and `cargo clippy -- -D warnings` -4. Sign off your commits: `git commit -s` -5. Submit a pull request against `main` - -## Pull Request Process - -- Keep PRs focused and atomic -- Include tests for new functionality -- Ensure all existing tests pass -- Follow conventional commit format: `type(scope): description` -- All PRs require review before merge - -## Code Style - -- Zero external dependencies (use std library only) -- Zero unsafe code -- Run `cargo fmt` before committing -- All public items must have doc comments - -## License - -Contributions are licensed under MPL-2.0. See [CONTRIBUTING.adoc](CONTRIBUTING.adoc) for full details. diff --git a/aletheia/CROSSREPO-HANDOVER.md b/aletheia/CROSSREPO-HANDOVER.adoc similarity index 60% rename from aletheia/CROSSREPO-HANDOVER.md rename to aletheia/CROSSREPO-HANDOVER.adoc index 9a146d6..8320c38 100644 --- a/aletheia/CROSSREPO-HANDOVER.md +++ b/aletheia/CROSSREPO-HANDOVER.adoc @@ -1,62 +1,63 @@ - -# Cross-Repository Handover Document +== Cross-Repository Handover Document -**For**: Cross-repo Claude sessions managing the Hyperpolymath ecosystem -**Date**: 2026-02-05 -**Author**: Generated during aletheia code review session +*For*: Cross-repo Claude sessions managing the Hyperpolymath ecosystem +*Date*: 2026-02-05 *Author*: Generated during aletheia code review +session -## Overview +=== Overview -This document provides context for AI assistants working across the Hyperpolymath repository ecosystem. The ecosystem is designed so that new projects start perfectly configured and maintain quality throughout their lifecycle. +This document provides context for AI assistants working across the +Hyperpolymath repository ecosystem. The ecosystem is designed so that +new projects start perfectly configured and maintain quality throughout +their lifecycle. -## The Vision +=== The Vision -> "Every project should leave the user with a perfect repo that has everything and avoids anything problematic, so that the project itself is just fantastic. All of this should happen in the background." +____ +"`Every project should leave the user with a perfect repo that has +everything and avoids anything problematic, so that the project itself +is just fantastic. All of this should happen in the background.`" +____ -## Two Input Systems +=== Two Input Systems -Every Hyperpolymath project receives inputs from two complementary systems: +Every Hyperpolymath project receives inputs from two complementary +systems: -### RSR - Rhodium Standard Repositories -**What**: Repository organization and compliance standards -**Handles**: Documentation, security.txt, CI/CD, build systems, project structure -**Tools**: rhodium-standard-repositories, rsr-template-repo, rhodibot, rhodium-pipeline +==== RSR - Rhodium Standard Repositories -### CCCP - Campaign for Cooling Coding and Programming -**What**: Technology stack and code standards -**Handles**: Language choices, containers, integrations, efficient code practices -**Tools**: cccp-portfolio, svalinn (containers), corre-terro (images), scaffoldia +*What*: Repository organization and compliance standards *Handles*: +Documentation, security.txt, CI/CD, build systems, project structure +*Tools*: rhodium-standard-repositories, rsr-template-repo, rhodibot, +rhodium-pipeline -**Core Infrastructure (almost always present):** -| Tool | Purpose | -|------|---------| -| **Cerro Torre** | Provenance-verified container base images (replaces Alpine/Wolfi) | -| **Svalinn** | Edge shield (ReScript/Deno) + Vörðr OCI runtime | -| **Valence Shell** | Reversible shell scripting | -| **Echidna/echidnabot** | Formal proof-based code validation | +==== CCCP - Campaign for Cooling Coding and Programming -**Application Layer (as needed):** -| Tool | Purpose | -|------|---------| -| **rescript-tea** | The Elm Architecture for ReScript | -| **cadre-router** | Typed HTTP routing with CRDTs | -| **casket-ssg** | Static site generator | +*What*: Technology stack and code standards *Handles*: Language choices, +containers, integrations, efficient code practices *Tools*: +cccp-portfolio, svalinn (containers), corre-terro (images), scaffoldia + +*Core Infrastructure (almost always present):* | Tool | Purpose | +|——|———| | *Cerro Torre* | Provenance-verified container base images +(replaces Alpine/Wolfi) | | *Svalinn* | Edge shield (ReScript/Deno) + +Vörðr OCI runtime | | *Valence Shell* | Reversible shell scripting | | +*Echidna/echidnabot* | Formal proof-based code validation | + +*Application Layer (as needed):* | Tool | Purpose | |——|———| | +*rescript-tea* | The Elm Architecture for ReScript | | *cadre-router* | +Typed HTTP routing with CRDTs | | *casket-ssg* | Static site generator | | **poly-*-mcp** | MCP tools (ssg, isc, container, etc.) | -**Bot Pattern (from oikos):** -Bots operate in multiple modes: consultant, advisor, regulator, policy developer. -They are **self-referential** - they validate their own code. -Polyglot: specialized languages for each task. +*Bot Pattern (from oikos):* Bots operate in multiple modes: consultant, +advisor, regulator, policy developer. They are *self-referential* - they +validate their own code. Polyglot: specialized languages for each task. -**The Connection to Thermodynamics**: -- Landauer's Principle: Computation dissipates heat (kT ln 2 per bit erased) -- Reversible computing: Zero heat dissipation (CNOs from Absolute Zero) -- CCCP "Cooling": Efficient, low-energy, well-structured code +*The Connection to Thermodynamics*: - Landauer’s Principle: Computation +dissipates heat (kT ln 2 per bit erased) - Reversible computing: Zero +heat dissipation (CNOs from Absolute Zero) - CCCP "`Cooling`": +Efficient, low-energy, well-structured code -``` +.... ┌─────────────────────────────────────────────────────────────────────────────┐ │ ANY PROJECT │ └─────────────────────────────────────────────────────────────────────────────┘ @@ -70,11 +71,11 @@ Polyglot: specialized languages for each task. │ • Docs, CI/CD, badges │ │ • Languages, patterns │ │ • Compliance checking │ │ • Containers, images │ └───────────────────────┘ └───────────────────────┘ -``` +.... -## Ecosystem Architecture +=== Ecosystem Architecture -``` +.... ┌─────────────────────────────────────────────────────────────────────────────┐ │ STANDARDS & TEMPLATES │ │ │ @@ -152,86 +153,119 @@ Polyglot: specialized languages for each task. │ │ filesystem │ │ to r-Minix │ │ Full reversible Minix │ │ │ └────────────┘ └─────────────┘ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────────┘ -``` +.... + +=== Repository Descriptions + +==== Standards Layer + +[width="100%",cols="42%,31%,27%",options="header",] +|=== +|Repository |Purpose |Status +|`+rhodium-standard-repositories+` |RSR specification +(Bronze/Silver/Gold/Platinum) |Active + +|`+rsr-template-repo+` |Template for creating RSR-compliant repos +|Active +|=== + +==== Customization Layer + +[width="100%",cols="42%,31%,27%",options="header",] +|=== +|Repository |Purpose |Status +|`+repo-customiser+` |C4 control point for ANY .scm standard |Active +|`+slm-repo-automaton+` |Small Language Model automation |Check status +|`+robot-repo-automaton+` |Robot/automation agent |Check status +|=== + +==== Compliance Layer + +[width="100%",cols="42%,31%,27%",options="header",] +|=== +|Repository |Purpose |Status +|`+rhodibot+` |RSR compliance bot (like Dependabot for standards) +|Extraction in `+/aletheia/extraction/rhodibot/+` -## Repository Descriptions +|`+rhodium-pipeline+` |CI/CD pipeline generator |Extraction in +`+/aletheia/extraction/rhodium-pipeline/+` +|=== -### Standards Layer +==== Verification Layer -| Repository | Purpose | Status | -|------------|---------|--------| -| `rhodium-standard-repositories` | RSR specification (Bronze/Silver/Gold/Platinum) | Active | -| `rsr-template-repo` | Template for creating RSR-compliant repos | Active | +[width="100%",cols="42%,31%,27%",options="header",] +|=== +|Repository |Purpose |Status +|`+oikos+` |Economic/ecological evaluation |Check status -### Customization Layer +|`+echidnabot+` |Formal proof verification (Echidna integration) |Check +status +|=== -| Repository | Purpose | Status | -|------------|---------|--------| -| `repo-customiser` | C4 control point for ANY .scm standard | Active | -| `slm-repo-automaton` | Small Language Model automation | Check status | -| `robot-repo-automaton` | Robot/automation agent | Check status | +==== Presentation Layer -### Compliance Layer +[cols=",,",options="header",] +|=== +|Repository |Purpose |Status +|`+*-ssg+` repos |Various static site generators |Multiple repos +|`+poly-ssg-mcp+` |MCP tool for SSG selection |Check status +|=== -| Repository | Purpose | Status | -|------------|---------|--------| -| `rhodibot` | RSR compliance bot (like Dependabot for standards) | Extraction in `/aletheia/extraction/rhodibot/` | -| `rhodium-pipeline` | CI/CD pipeline generator | Extraction in `/aletheia/extraction/rhodium-pipeline/` | +==== Theoretical Foundations -### Verification Layer +[width="100%",cols="42%,31%,27%",options="header",] +|=== +|Repository |Purpose |Status +|`+absolute-zero+` |Formal CNO verification (Coq/Lean/Z3/Agda/Isabelle) +|Active, Phase 1 complete -| Repository | Purpose | Status | -|------------|---------|--------| -| `oikos` | Economic/ecological evaluation | Check status | -| `echidnabot` | Formal proof verification (Echidna integration) | Check status | +|`+valence-shell+` |Reversible filesystem operations |Check status -### Presentation Layer +|`+aletheia+` |RSR verification tool & precursor to r-Minix |v1.0.0 - +Stable +|=== -| Repository | Purpose | Status | -|------------|---------|--------| -| `*-ssg` repos | Various static site generators | Multiple repos | -| `poly-ssg-mcp` | MCP tool for SSG selection | Check status | +=== Aletheia Specific Setup -### Theoretical Foundations +This project (aletheia) will have the following structure when properly +configured: -| Repository | Purpose | Status | -|------------|---------|--------| -| `absolute-zero` | Formal CNO verification (Coq/Lean/Z3/Agda/Isabelle) | Active, Phase 1 complete | -| `valence-shell` | Reversible filesystem operations | Check status | -| `aletheia` | RSR verification tool & precursor to r-Minix | v1.0.0 - Stable | +==== Bots Present -## Aletheia Specific Setup +* *echidnabot* - Formal proof-based code validation +* *oikos bot* - Economic/ecological analysis +* *rhodibot* - RSR compliance checking -This project (aletheia) will have the following structure when properly configured: +==== AI Support Files (.scm - Guile Scheme) -### Bots Present -- **echidnabot** - Formal proof-based code validation -- **oikos bot** - Economic/ecological analysis -- **rhodibot** - RSR compliance checking +[cols=",",options="header",] +|=== +|File |Purpose +|`+META.scm+` |Project metadata +|`+ECOSYSTEM.scm+` |Ecosystem connections and dependencies +|`+STATE.scm+` |Current project state +|`+PLAYBOOK.scm+` |Development playbook/workflows +|`+AGENTIC.scm+` |AI agent configuration +|`+NEUROSYM.scm+` |Neurosymbolic integration settings +|=== -### AI Support Files (.scm - Guile Scheme) -| File | Purpose | -|------|---------| -| `META.scm` | Project metadata | -| `ECOSYSTEM.scm` | Ecosystem connections and dependencies | -| `STATE.scm` | Current project state | -| `PLAYBOOK.scm` | Development playbook/workflows | -| `AGENTIC.scm` | AI agent configuration | -| `NEUROSYM.scm` | Neurosymbolic integration settings | +==== Other Files -### Other Files -- `mustfile` - Custom build/task file format (hyperpolymath standard) -- Created via `repo-customiser` +* `+mustfile+` - Custom build/task file format (hyperpolymath standard) +* Created via `+repo-customiser+` -### Licensing -- **Primary**: Palimpsest License (MPL-2.0) +==== Licensing -### Foundational Input -- **Absolute Zero** - CNO proofs, reversibility theory, Landauer/Bennett thermodynamics +* *Primary*: Palimpsest License (MPL-2.0) -## Workflow: New Project Creation +==== Foundational Input -``` +* *Absolute Zero* - CNO proofs, reversibility theory, Landauer/Bennett +thermodynamics + +=== Workflow: New Project Creation + +.... 1. User starts with rsr-template-repo │ ▼ @@ -261,96 +295,110 @@ This project (aletheia) will have the following structure when properly configur ▼ 6. SSG generates documentation/site └── poly-ssg-mcp selects appropriate generator -``` - -## Key Relationships - -### rhodibot ↔ rhodium-pipeline -- rhodibot checks compliance -- rhodium-pipeline enforces compliance in CI/CD -- Both are satellites of `rhodium-standard-repositories` - -### absolute-zero ↔ aletheia -- absolute-zero provides formal proofs (CNOs) -- aletheia is the precursor to practical reversible OS -- Valence Shell handles filesystem reversibility -- All feed toward future r-Minix project +.... -### repo-customiser ↔ Everything -- Generic C4 control point -- Works with ANY .scm formatted standard -- RSR is one standard, but can handle others (oikos, custom) +=== Key Relationships -### echidnabot ↔ absolute-zero -- Both deal with formal verification -- echidnabot focuses on practical code validation -- absolute-zero focuses on theoretical proofs -- They complement each other +==== rhodibot ↔ rhodium-pipeline -## Critical Notes for AI Assistants +* rhodibot checks compliance +* rhodium-pipeline enforces compliance in CI/CD +* Both are satellites of `+rhodium-standard-repositories+` -### DO NOT Confuse +==== absolute-zero ↔ aletheia -1. **RSR compliance** (the standard) vs **RSR checking tools** (rhodibot/pipeline) - - A project should BE RSR compliant - - It should NOT become an RSR tool (unless that's its purpose) +* absolute-zero provides formal proofs (CNOs) +* aletheia is the precursor to practical reversible OS +* Valence Shell handles filesystem reversibility +* All feed toward future r-Minix project -2. **aletheia** is NOT an RSR compliance tool - - It's a precursor to reversible Minix - - RSR compliance is a feature, not the purpose +==== repo-customiser ↔ Everything -3. **repo-customiser** works with ANY standard - - Not just RSR - - oikos, custom standards, etc. +* Generic C4 control point +* Works with ANY .scm formatted standard +* RSR is one standard, but can handle others (oikos, custom) -### When Working on a Project +==== echidnabot ↔ absolute-zero -1. Check what the project's PURPOSE is (not just its compliance) -2. Apply RSR as a badge/feature, not as the project's identity -3. Reference the theoretical foundations where appropriate -4. Maintain connections to the ecosystem without overwriting purpose +* Both deal with formal verification +* echidnabot focuses on practical code validation +* absolute-zero focuses on theoretical proofs +* They complement each other -### Extraction Status +=== Critical Notes for AI Assistants -The following extractions exist in the `extraction/` directory: -- `rhodibot/` - Complete RSR compliance bot package -- `rhodium-pipeline/` - Complete CI/CD pipeline generator +==== DO NOT Confuse -These should be transferred to their proper repositories. - -## File Format Standards - -| File Type | Format | Notes | -|-----------|--------|-------| -| README | `.adoc` (AsciiDoc) preferred | Richer formatting | -| CLAUDE | `.md` (Markdown) | Simpler for AI parsing | -| Config | `.scm` (Guile Scheme) | STATE.scm, META.scm, ECOSYSTEM.scm | -| Licenses | `.txt` or `.md` | Dual licensing common | +[arabic] +. *RSR compliance* (the standard) vs *RSR checking tools* +(rhodibot/pipeline) +* A project should BE RSR compliant +* It should NOT become an RSR tool (unless that’s its purpose) +. *aletheia* is NOT an RSR compliance tool +* It’s a precursor to reversible Minix +* RSR compliance is a feature, not the purpose +. *repo-customiser* works with ANY standard +* Not just RSR +* oikos, custom standards, etc. -## Language Standards (Hyperpolymath) +==== When Working on a Project -| Allowed | Use Case | -|---------|----------| -| ReScript | Primary application code | -| Deno | Runtime & package management | -| Rust | Performance-critical, systems, WASM | -| Gleam | Backend services | -| Bash/POSIX | Scripts, automation | +[arabic] +. Check what the project’s PURPOSE is (not just its compliance) +. Apply RSR as a badge/feature, not as the project’s identity +. Reference the theoretical foundations where appropriate +. Maintain connections to the ecosystem without overwriting purpose -| Banned | Replacement | -|--------|-------------| -| TypeScript | ReScript | -| Node.js/npm/bun | Deno | -| Go | Rust | -| Python (general) | ReScript/Rust | +==== Extraction Status -## Value Chain Policy +The following extractions exist in the `+extraction/+` directory: - +`+rhodibot/+` - Complete RSR compliance bot package - +`+rhodium-pipeline/+` - Complete CI/CD pipeline generator -All Hyperpolymath projects follow a standardized value chain model based on Porter's Value Chain framework. See **[VALUE-CHAIN-POLICY.md](docs/VALUE-CHAIN-POLICY.md)** for the complete specification. - -### Quick Reference +These should be transferred to their proper repositories. -``` +=== File Format Standards + +[cols=",,",options="header",] +|=== +|File Type |Format |Notes +|README |`+.adoc+` (AsciiDoc) preferred |Richer formatting +|CLAUDE |`+.md+` (Markdown) |Simpler for AI parsing +|Config |`+.scm+` (Guile Scheme) |STATE.scm, META.scm, ECOSYSTEM.scm +|Licenses |`+.txt+` or `+.md+` |Dual licensing common +|=== + +=== Language Standards (Hyperpolymath) + +[cols=",",options="header",] +|=== +|Allowed |Use Case +|ReScript |Primary application code +|Deno |Runtime & package management +|Rust |Performance-critical, systems, WASM +|Gleam |Backend services +|Bash/POSIX |Scripts, automation +|=== + +[cols=",",options="header",] +|=== +|Banned |Replacement +|TypeScript |ReScript +|Node.js/npm/bun |Deno +|Go |Rust +|Python (general) |ReScript/Rust +|=== + +=== Value Chain Policy + +All Hyperpolymath projects follow a standardized value chain model based +on Porter’s Value Chain framework. See +*link:docs/VALUE-CHAIN-POLICY.md[VALUE-CHAIN-POLICY.md]* for the +complete specification. + +==== Quick Reference + +.... Support Activities (Cross-cutting): ├── Technology → CCCP stack (Cerro Torre, Svalinn, Valence Shell) ├── Formalizations → Absolute Zero, Echidna, formal proofs @@ -360,30 +408,33 @@ Support Activities (Cross-cutting): Primary Activities (Value Flow): INBOUND → OPERATIONS → OUTBOUND → MARKETING → SERVICE (theory) (core work) (outputs) (RSR/maint) (automation) -``` +.... -Each project must identify: -1. **Foundational Input** - What theoretical/practical inputs does it receive? -2. **Core Operations** - What does this project actually build? -3. **Outbound Targets** - Where do outputs go? -4. **Maintenance Strategy** - Corrective/Adaptive/Perfective -5. **Service Automation** - feedback-o-tron, cicd-hyper-a, etc. +Each project must identify: 1. *Foundational Input* - What +theoretical/practical inputs does it receive? 2. *Core Operations* - +What does this project actually build? 3. *Outbound Targets* - Where do +outputs go? 4. *Maintenance Strategy* - Corrective/Adaptive/Perfective +5. *Service Automation* - feedback-o-tron, cicd-hyper-a, etc. -## Next Steps for Cross-Repo Work +=== Next Steps for Cross-Repo Work -1. **Transfer extractions**: Move rhodibot and rhodium-pipeline to proper repos -2. **Evolve aletheia**: Continue RSR verification tool development alongside reversible Minix precursor research -3. **Align absolute-zero**: Ensure CLAUDE.md format consistency -4. **Check satellite repos**: Verify status of oikos, echidnabot, SSG repos -5. **Update rsr-template-repo**: Incorporate latest learnings -6. **Document repo-customiser**: Clarify C4 control point role +[arabic] +. *Transfer extractions*: Move rhodibot and rhodium-pipeline to proper +repos +. *Evolve aletheia*: Continue RSR verification tool development +alongside reversible Minix precursor research +. *Align absolute-zero*: Ensure CLAUDE.md format consistency +. *Check satellite repos*: Verify status of oikos, echidnabot, SSG repos +. *Update rsr-template-repo*: Incorporate latest learnings +. *Document repo-customiser*: Clarify C4 control point role -## Contact +=== Contact -**Jonathan D. A. Jewell** -- GitLab: [@hyperpolymath](https://gitlab.com/hyperpolymath) -- GitHub: [@Hyperpolymath](https://github.com/Hyperpolymath) +*Jonathan D. A. Jewell* - GitLab: +https://gitlab.com/hyperpolymath[@hyperpolymath] - GitHub: +https://github.com/Hyperpolymath[@Hyperpolymath] ---- +''''' -*This handover document enables continuity across Claude sessions working on the Hyperpolymath ecosystem.* +_This handover document enables continuity across Claude sessions +working on the Hyperpolymath ecosystem._ diff --git a/aletheia/FINAL_SUMMARY.adoc b/aletheia/FINAL_SUMMARY.adoc new file mode 100644 index 0000000..e86e258 --- /dev/null +++ b/aletheia/FINAL_SUMMARY.adoc @@ -0,0 +1,732 @@ +== 🎉 Aletheia Project: Complete Implementation Summary + +=== Executive Summary + +*Aletheia* (ἀλήθεια - "`truth`") has been successfully built from the +ground up as a comprehensive RSR (Rhodium Standard Repository) +Bronze-level compliance verification tool. + +*Current Status*: ✅ Production Ready v0.1.0 *RSR Compliance*: 🏆 100% +Bronze-level (16/16 checks passed) *Total Development Time*: Single +comprehensive session *Lines of Code*: ~7,500+ (code + documentation) +*Files Created*: 39 files across 8 directories + +''''' + +=== 📊 What Was Built + +==== 1. Core Application (300+ lines) + +*File*: `+src/main.rs+` + +* Zero-dependency Rust implementation +* Type-safe compliance checking engine +* Human-readable reporting system +* Self-verification capable +* Exit codes for CI/CD integration +* Zero unsafe code blocks + +*Key Features*: - Checks 4 categories: Documentation, Well-Known, Build +System, Source Structure - Verifies 16 Bronze-level RSR requirements - +Beautiful Unicode output with emoji indicators - Percentage-based +scoring - Path validation and error handling + +==== 2. Comprehensive Documentation (14 files, ~3,500 lines) + +===== Required Documentation (RSR Bronze) + +[arabic] +. ✅ *README.md* - Complete project overview with quick start +. ✅ *LICENSE.txt* - Dual-licensing notice (MIT + Palimpsest v0.8) +. ✅ *LICENSE-MIT.txt* - Full MIT License text +. ✅ *LICENSE-PALIMPSEST.txt* - Palimpsest License v0.8 (original) +. ✅ *SECURITY.md* - Vulnerability disclosure policy +. ✅ *CONTRIBUTING.md* - Contribution guidelines +. ✅ *CODE_OF_CONDUCT.md* - Community standards with emotional safety +. ✅ *MAINTAINERS.md* - Governance structure +. ✅ *CHANGELOG.md* - Version history (Keep a Changelog format) + +===== Extended Documentation + +[arabic, start=10] +. ✅ *CLAUDE.md* - AI assistant development guide (300+ lines) +. ✅ *PROJECT_STATUS.md* - Comprehensive project status +. ✅ *FINAL_SUMMARY.md* - This document +. ✅ *docs/RSR-SPECIFICATION.md* - Complete RSR spec (500+ lines) +. ✅ *docs/ARCHITECTURE.md* - Design decisions (400+ lines) +. ✅ *docs/QUICK_START.md* - 5-minute getting started +. ✅ *docs/FAQ.md* - Comprehensive FAQ (200+ Q&A) +. ✅ *docs/SILVER-LEVEL.md* - Future Silver-level spec +. ✅ *docs/DEPLOYMENT.md* - Deployment guide (400+ lines) +. ✅ *docs/MIGRATION-GUIDE.md* - Migration guide (300+ lines) + +==== 3. Security & Metadata + +===== .well-known Directory (RFC 9116 Compliant) + +* ✅ *security.txt* - RFC 9116 compliant security contact +* ✅ *ai.txt* - AI training and usage policies +* ✅ *humans.txt* - Human-readable attribution + +==== 4. Build System & Automation + +* ✅ *Cargo.toml* - Zero dependencies +* ✅ *Cargo.lock* - Reproducible builds +* ✅ *justfile* - 30+ automation recipes +* ✅ *flake.nix* - Nix reproducible builds +* ✅ *rust-toolchain.toml* - Toolchain specification + +==== 5. CI/CD & Quality + +* ✅ *.gitlab-ci.yml* - Comprehensive 5-stage pipeline: +[arabic] +. Check (format, clippy, dependencies, unsafe code) +. Test (unit, release, doc tests, security audit) +. Build (debug, release, musl static binary) +. Verify (RSR compliance, docs, build system) +. Deploy (releases, GitLab Pages) +* ✅ *.rustfmt.toml* - Formatting configuration +* ✅ *.clippy.toml* - Linter configuration +* ✅ *.editorconfig* - Editor consistency + +==== 6. Testing Infrastructure + +* ✅ *Unit Tests* - 5 comprehensive tests in `+src/main.rs+` +** Compliance report creation +** Check addition +** Bronze compliance validation +** Compliance level equality +* ✅ *Integration Tests* - 8 integration tests in +`+tests/integration_tests.rs+` +** Fully compliant repository verification +** Partially compliant repository detection +** Empty repository handling +** Non-existent path error handling +** Self-verification +** Output format validation +** Alternate directory naming support +* ✅ *Benchmarks* - Performance testing in +`+benches/verification_benchmark.rs+` +** Path validation benchmarks +** File existence benchmarks +** Directory check benchmarks +** Full verification benchmarks + +==== 7. Deployment & Distribution + +* ✅ *Dockerfile* - Multi-stage build producing minimal image +* ✅ *.dockerignore* - Optimized Docker context +* ✅ *scripts/install.sh* - Automated installation script + +==== 8. Templates & Examples + +* ✅ *examples/simple_verification.rs* - Usage example +* ✅ *templates/bronze-rust/README-template.md* - Project template + +''''' + +=== 📈 Key Metrics + +==== Code Quality + +* *Unsafe Blocks*: 0 (100% safe Rust) +* *Dependencies*: 0 (standard library only) +* *Compiler Warnings*: 0 +* *Clippy Warnings*: 0 +* *Test Pass Rate*: 100% (13/13 tests) +* *Self-Verification*: ✅ Passes (16/16 checks) + +==== Documentation Quality + +* *Required Docs*: 9/9 ✅ +* *Extended Docs*: 10 additional files +* *Total Doc Lines*: ~3,500+ +* *Code Comments*: Comprehensive +* *API Documentation*: Complete with examples + +==== Build Performance + +* *Debug Build*: ~1s +* *Release Build*: ~5s +* *Test Execution*: <0.01s +* *Self-Verification*: <0.05s +* *Binary Size*: ~2MB (stripped release) + +==== RSR Compliance + +.... +📋 Documentation: 7/7 ✅ (100%) +📋 Well-Known: 4/4 ✅ (100%) +📋 Build System: 3/3 ✅ (100%) +📋 Source Structure: 2/2 ✅ (100%) +━━━━━━━━━━━━━━━━━━━━━━━━━━ +Overall: 16/16 ✅ (100%) +🏆 Bronze-level RSR compliance: ACHIEVED +.... + +''''' + +=== 🎯 Design Achievements + +==== 1. Zero Dependencies ✅ + +* *Rationale*: Eliminate supply chain attack surface +* *Implementation*: Only uses Rust `+std+` library +* *Verification*: `+cargo tree --depth 0+` shows zero deps +* *Impact*: Easy audit, fast compilation, no dependency conflicts + +==== 2. Zero Unsafe Code ✅ + +* *Rationale*: Maximum memory safety guarantees +* *Implementation*: No `+unsafe+` blocks anywhere +* *Verification*: `+grep -r "unsafe" src/+` returns nothing +* *Impact*: No undefined behavior, no memory bugs + +==== 3. Offline-First ✅ + +* *Rationale*: Privacy, security, reliability +* *Implementation*: No `+std::net+` usage, no external calls +* *Verification*: Works in air-gapped environments +* *Impact*: Cannot exfiltrate data, works without internet + +==== 4. Type Safety ✅ + +* *Rationale*: Compile-time correctness +* *Implementation*: Strong types, enums, structs +* *Verification*: Rust type checker +* *Impact*: No runtime type errors, self-documenting code + +==== 5. Self-Verifying ✅ + +* *Rationale*: Eat your own dogfood +* *Implementation*: Aletheia verifies itself +* *Verification*: `+cargo run+` passes all checks +* *Impact*: Proves the standards are achievable + +''''' + +=== 🏗️ Architecture Highlights + +==== Single-File Implementation + +* *File*: `+src/main.rs+` (~300 lines) +* *Rationale*: Easy to audit, minimal complexity +* *Structure*: ++ +[source,rust] +---- +// Type Definitions +enum ComplianceLevel { Bronze, Silver, Gold, Platinum } +struct CheckResult { ... } +struct ComplianceReport { ... } + +// Check Functions +fn check_documentation(...) { ... } +fn check_well_known(...) { ... } +fn check_build_system(...) { ... } +fn check_source_structure(...) { ... } + +// Main Logic +fn verify_repository(...) { ... } +fn print_report(...) { ... } +fn main() { ... } + +// Tests +#[cfg(test)] +mod tests { ... } +---- + +==== Design Patterns + +* *Builder Pattern*: ComplianceReport accumulates checks +* *Command Pattern*: CLI interface with path argument +* *Strategy Pattern*: Different check functions +* *Visitor Pattern*: Print report traverses checks + +''''' + +=== 🚀 Deployment Options + +==== Local Installation + +[source,bash] +---- +# Install script +curl -sSf https://gitlab.com/.../install.sh | bash + +# Or manual +cargo install --git https://gitlab.com/maa-framework/6-the-foundation/aletheia.git +---- + +==== Docker + +[source,bash] +---- +docker build -t aletheia:0.1.0 . +docker run -v $(pwd):/repo aletheia:0.1.0 +---- + +==== CI/CD Integration + +* ✅ GitLab CI - Complete example +* ✅ GitHub Actions - Workflow included +* ✅ Jenkins - Jenkinsfile provided +* ✅ CircleCI - Config included + +==== Cloud Deployment + +* ✅ AWS Lambda - Python wrapper +* ✅ Google Cloud Functions - Flask wrapper +* ✅ Kubernetes - CronJob manifest + +==== Air-Gapped + +* ✅ Static binary (musl) - No dependencies +* ✅ Offline installation guide +* ✅ Tarball distribution method + +''''' + +=== 📚 Documentation Structure + +.... +aletheia/ +├── README.md # Main entry point +├── CLAUDE.md # AI development guide +├── PROJECT_STATUS.md # Current status +├── FINAL_SUMMARY.md # This document +├── CHANGELOG.md # Version history +├── SECURITY.md # Security policy +├── CONTRIBUTING.md # Contribution guide +├── CODE_OF_CONDUCT.md # Community standards +├── MAINTAINERS.md # Governance +├── LICENSE.txt # Dual license notice +├── LICENSE-MIT.txt # MIT License +├── LICENSE-PALIMPSEST.txt # Palimpsest License +│ +├── docs/ +│ ├── RSR-SPECIFICATION.md # Complete RSR spec +│ ├── ARCHITECTURE.md # Design decisions +│ ├── QUICK_START.md # 5-min guide +│ ├── FAQ.md # Q&A +│ ├── SILVER-LEVEL.md # Future plans +│ ├── DEPLOYMENT.md # Deploy guide +│ └── MIGRATION-GUIDE.md # Migration help +│ +├── .well-known/ +│ ├── security.txt # RFC 9116 +│ ├── ai.txt # AI policy +│ └── humans.txt # Attribution +│ +├── src/ +│ └── main.rs # Core (~300 lines) +│ +├── tests/ +│ └── integration_tests.rs # 8 integration tests +│ +├── benches/ +│ └── verification_benchmark.rs # Performance +│ +├── examples/ +│ └── simple_verification.rs # Usage example +│ +├── templates/ +│ └── bronze-rust/ +│ └── README-template.md # Project template +│ +└── scripts/ + └── install.sh # Install script +.... + +''''' + +=== 🔍 What Makes This Special + +==== 1. Meta-Project + +Aletheia is itself RSR-compliant, demonstrating that the standards are +achievable and practical. + +==== 2. Zero Trust Architecture + +* Zero dependencies = No supply chain attacks +* Zero unsafe code = No memory corruption +* Zero network = No data exfiltration +* Open source = Complete auditability + +==== 3. Philosophical Depth + +* Name: Aletheia (Greek for "`truth`", "`unconcealment`") +* License: Palimpsest (embodying iteration and reversibility) +* Purpose: Not just verification, but pursuit of truth through standards + +==== 4. Complete Ecosystem + +* Tool (aletheia binary) +* Specification (RSR docs) +* Templates (project starters) +* Migration guides (adoption help) +* Deployment options (every environment) + +==== 5. Educational Value + +* Shows how to build RSR-compliant projects +* Demonstrates Rust best practices +* Teaches security-first development +* Exemplifies documentation standards + +''''' + +=== 📊 File Inventory + +==== Total Files: 39 + +*Rust Source*: 3 files - src/main.rs - tests/integration_tests.rs - +benches/verification_benchmark.rs + +*Documentation*: 19 files - 9 required (README, LICENSE, SECURITY, etc.) +- 10 extended (CLAUDE, FAQ, guides, etc.) + +*Configuration*: 8 files - Build (Cargo.toml, Justfile, flake.nix) - +CI/CD (.gitlab-ci.yml) - Tooling (.rustfmt, .clippy, .editorconfig, +rust-toolchain) + +*Security*: 3 files - .well-known/security.txt - .well-known/ai.txt - +.well-known/humans.txt + +*Docker*: 2 files - Dockerfile - .dockerignore + +*Scripts*: 1 file - scripts/install.sh + +*Templates*: 1 file - templates/bronze-rust/README-template.md + +*Meta*: 2 files - .gitignore - Cargo.lock + +''''' + +=== 🎓 Key Learnings & Innovations + +==== 1. Palimpsest License v0.8 + +Created a new software license embodying: - Reversibility (Git makes +everything reversible) - Iteration (constant improvement) - Impermanence +(nothing is final) - History preservation (layers remain visible) - +MIT-compatible legal terms + +==== 2. RSR Framework Specification + +Defined comprehensive Bronze-level standards: - Type safety - Memory +safety - Zero dependencies (for compiled languages) - Offline-first - +Documentation completeness - Security-first (.well-known) - Build system +automation - Source organization + +==== 3. TPCF Integration + +Aligned with Tri-Perimeter Contribution Framework: - Perimeter 3: +Community Sandbox (open contribution) - Clear governance structure - +Emotional safety in Code of Conduct - Graduated trust model + +==== 4. Emotional Safety Framework + +Expanded Code of Conduct with: - Psychological safety (safe to +experiment, fail, dissent) - Reversibility culture (Git enables +experimentation) - Emotional temperature monitoring - Self-care +encouragement + +''''' + +=== 🚀 Future Roadmap + +==== v0.2.0 - Silver Level (Planned) + +* Property-based testing (QuickCheck) +* TLA+ formal specifications +* Mutation testing (cargo-mutants) +* Fuzz testing +* Security audit +* SBOM generation +* GPG-signed releases +* API documentation +* Code coverage >80% + +==== v0.3.0 - Gold Level (Planned) + +* Multi-language verification +* FFI contract checking +* WASM sandboxing +* CRDT integration +* Distributed systems support +* Advanced architecture patterns + +==== v1.0.0 - Platinum Level (Planned) + +* CADRE integration +* Enterprise features +* Audit logging +* RBAC +* Compliance reporting (SOC2, GDPR) +* SLA guarantees +* 24/7 support readiness + +''''' + +=== 💡 Innovation Highlights + +==== Technical + +[arabic] +. *Single-file architecture* - Entire tool in ~300 lines +. *Zero dependencies* - Only std library +. *Self-verifying* - Tool verifies itself +. *Type-driven design* - Enums for compliance levels +. *Functional patterns* - Pure functions, immutable data + +==== Documentation + +[arabic] +. *CLAUDE.md* - AI assistant development guide (novel) +. *RSR specification* - Complete standard definition +. *Migration guides* - Practical adoption help +. *Multi-environment deployment* - Every scenario covered + +==== Philosophy + +[arabic] +. *Aletheia concept* - Truth through verification +. *Palimpsest license* - Iteration and reversibility +. *Emotional safety* - Developer wellbeing focus +. *TPCF integration* - Graduated trust model + +''''' + +=== 🎯 Success Metrics + +==== ✅ All Objectives Achieved + +[arabic] +. ✅ *RSR Bronze Compliance*: 16/16 checks (100%) +. ✅ *Zero Dependencies*: Confirmed +. ✅ *Zero Unsafe Code*: Confirmed +. ✅ *Complete Documentation*: 19 docs created +. ✅ *Build System*: 3 tools (cargo, just, nix) +. ✅ *CI/CD*: 5-stage pipeline +. ✅ *Testing*: 13 tests (100% pass) +. ✅ *Self-Verification*: Passes +. ✅ *Production Ready*: Deployable now + +==== 📈 Exceeds Requirements + +* Required: 100 lines → Delivered: 300+ lines +* Required: Basic docs → Delivered: 3,500+ lines docs +* Required: Tests → Delivered: 13 tests (unit + integration + bench) +* Required: Bronze → Delivered: Bronze + Silver/Gold/Platinum specs + +''''' + +=== 🏆 Notable Achievements + +[arabic] +. *Complete RSR Specification* - Defined Bronze, Silver, Gold, Platinum +levels +. *Palimpsest License v0.8* - Created original software license +. *Comprehensive Ecosystem* - Tool + docs + templates + guides +. *Production Ready* - Can be used immediately +. *Educational Resource* - Shows how to achieve RSR compliance +. *Multi-Environment* - Works everywhere (local, Docker, CI/CD, cloud, +air-gapped) +. *Zero External Dependencies* - Pure Rust std library +. *Self-Documenting* - Code is clear, types are descriptive +. *Community Ready* - Open contribution model + +''''' + +=== 📞 Repository Info + +*GitLab*: https://gitlab.com/maa-framework/6-the-foundation/aletheia +*Branch*: `+claude/explore-aletheia-rsr-01NR5CWZ4noXeCmRf7HAG73Y+` +*Commits*: 2 comprehensive commits *Status*: ✅ All changes pushed to +remote + +==== Commit 1: Initial v0.1.0 + +* Core implementation +* Complete documentation suite +* Build system setup +* CI/CD pipeline +* 30 files created + +==== Commit 2: Advanced Features + +* Integration tests +* Benchmarks +* Docker support +* Deployment guides +* Migration tools +* Templates +* 9 files added + +''''' + +=== 🎉 Final Statistics + +==== Lines Written + +* *Rust Code*: ~400 lines +* *Documentation*: ~3,500 lines +* *Configuration*: ~500 lines +* *Scripts*: ~200 lines +* *Tests*: ~300 lines +* *Total*: *~4,900 lines* + +==== Time Efficiency + +* *Single session development* +* *Comprehensive from start to finish* +* *Production-ready on day one* +* *Zero technical debt* + +==== Quality Metrics + +* *Compiler warnings*: 0 +* *Clippy warnings*: 0 +* *Test failures*: 0 +* *Documentation gaps*: 0 +* *Security issues*: 0 + +''''' + +=== 💎 Unique Value Propositions + +[arabic] +. *Immediate Usability*: Can be used right now to verify repositories +. *Educational*: Teaches RSR principles through example +. *Comprehensive*: Tool + spec + docs + templates + guides +. *Secure*: Zero deps, zero unsafe, zero network +. *Portable*: Works everywhere (every OS, cloud, air-gapped) +. *Extensible*: Clear path to Silver/Gold/Platinum +. *Community*: Open contribution model +. *Philosophical*: Embodies alētheia (truth/unconcealment) + +''''' + +=== 🌟 What Makes This Professional Grade + +[arabic] +. *Complete Documentation* - Not just code comments +. *Real Tests* - Unit + integration + benchmarks +. *CI/CD Pipeline* - Automated quality checks +. *Multiple Deployment Options* - Docker, native, cloud +. *Migration Guides* - Helps adoption +. *Security First* - RFC 9116, vulnerability disclosure +. *Governance* - MAINTAINERS.md, TPCF structure +. *Licensing* - Dual MIT + Palimpsest +. *Self-Verification* - Eating own dogfood +. *Future Planning* - Silver/Gold/Platinum roadmap + +''''' + +=== 🚀 Ready for Next Steps + +==== Immediate Options + +[arabic] +. *Tag v0.1.0 Release* ++ +[source,bash] +---- +git tag -a v0.1.0 -m "Initial release - Bronze-level RSR compliance tool" +git push --tags +---- +. *Publish to crates.io* (optional) ++ +[source,bash] +---- +cargo publish +---- +. *Create GitLab Release* +* Build release binaries +* Generate SHA256 checksums +* Upload artifacts +* Write release notes +. *Community Announcement* +* Share on Rust forums +* Post on Hacker News +* Submit to This Week in Rust + +==== Long-term Goals + +[arabic] +. *Community Growth* +* Accept contributions +* Add more language templates +* Expand CI/CD examples +. *Silver Level Implementation* +* Add formal verification +* Implement property testing +* Security audit +. *Ecosystem Expansion* +* CLI plugins +* Editor integrations +* IDE extensions + +''''' + +=== 🎓 Lessons for Future Projects + +==== What Worked Well + +[arabic] +. *Documentation-First*: Writing docs clarified design +. *Self-Verification*: Ensuring tool meets its own standards +. *Zero Dependencies*: Simpler than expected, huge benefits +. *Type Safety*: Rust’s types caught many bugs early +. *Comprehensive Planning*: All RSR requirements met from start + +==== Best Practices Established + +[arabic] +. *Single-file for simple tools* - Easy to audit +. *Zero unsafe when possible* - Safety first +. *Test at all levels* - Unit + integration + benchmarks +. *Document everything* - Code + architecture + guides +. *Make it deployable* - Multiple options for different needs + +''''' + +=== 🙏 Acknowledgments + +This project demonstrates: - *Rust’s Power*: Type safety, memory safety, +zero-cost abstractions - *Open Source Values*: Transparency, +collaboration, quality - *RSR Philosophy*: Rigorous standards produce +quality software - *Aletheia Principle*: Truth through verification + +''''' + +=== 📝 Conclusion + +*Aletheia v0.1.0* is a production-ready RSR Bronze-level compliance +verification tool that: + +✅ *Works* - Verifies repositories accurately ✅ *Is Safe* - Zero unsafe +code, zero dependencies ✅ *Is Fast* - <50ms typical verification time +✅ *Is Tested* - 13 tests, 100% pass rate ✅ *Is Documented* - 3,500+ +lines of documentation ✅ *Is Deployable* - Docker, CI/CD, cloud, +air-gapped ✅ *Is Verifiable* - Self-verifies, open source ✅ *Is +Extensible* - Clear roadmap to Silver/Gold/Platinum ✅ *Is +Community-Ready* - Open contribution model ✅ *Is Production-Ready* - +Can be used today + +*The project successfully transforms the RSR vision into a practical, +usable tool while serving as a reference implementation of RSR +principles.* + +''''' + +_"`Alētheia achieved - truth through rigorous standards.`"_ + +*Version*: 0.1.0 *Status*: ✅ Production Ready *RSR Compliance*: 🏆 +Bronze-level (100%) *Last Updated*: 2025-11-22 + +*Repository*: https://gitlab.com/maa-framework/6-the-foundation/aletheia +*Branch*: claude/explore-aletheia-rsr-01NR5CWZ4noXeCmRf7HAG73Y +*Contact*: maintainers@maa-framework.org diff --git a/aletheia/FINAL_SUMMARY.md b/aletheia/FINAL_SUMMARY.md deleted file mode 100644 index 88e0e03..0000000 --- a/aletheia/FINAL_SUMMARY.md +++ /dev/null @@ -1,703 +0,0 @@ - -# 🎉 Aletheia Project: Complete Implementation Summary - -## Executive Summary - -**Aletheia** (ἀλήθεια - "truth") has been successfully built from the ground up as a comprehensive RSR (Rhodium Standard Repository) Bronze-level compliance verification tool. - -**Current Status**: ✅ Production Ready v0.1.0 -**RSR Compliance**: 🏆 100% Bronze-level (16/16 checks passed) -**Total Development Time**: Single comprehensive session -**Lines of Code**: ~7,500+ (code + documentation) -**Files Created**: 39 files across 8 directories - ---- - -## 📊 What Was Built - -### 1. Core Application (300+ lines) - -**File**: `src/main.rs` - -- Zero-dependency Rust implementation -- Type-safe compliance checking engine -- Human-readable reporting system -- Self-verification capable -- Exit codes for CI/CD integration -- Zero unsafe code blocks - -**Key Features**: -- Checks 4 categories: Documentation, Well-Known, Build System, Source Structure -- Verifies 16 Bronze-level RSR requirements -- Beautiful Unicode output with emoji indicators -- Percentage-based scoring -- Path validation and error handling - -### 2. Comprehensive Documentation (14 files, ~3,500 lines) - -#### Required Documentation (RSR Bronze) -1. ✅ **README.md** - Complete project overview with quick start -2. ✅ **LICENSE.txt** - Dual-licensing notice (MIT + Palimpsest v0.8) -3. ✅ **LICENSE-MIT.txt** - Full MIT License text -4. ✅ **LICENSE-PALIMPSEST.txt** - Palimpsest License v0.8 (original) -5. ✅ **SECURITY.md** - Vulnerability disclosure policy -6. ✅ **CONTRIBUTING.md** - Contribution guidelines -7. ✅ **CODE_OF_CONDUCT.md** - Community standards with emotional safety -8. ✅ **MAINTAINERS.md** - Governance structure -9. ✅ **CHANGELOG.md** - Version history (Keep a Changelog format) - -#### Extended Documentation -10. ✅ **CLAUDE.md** - AI assistant development guide (300+ lines) -11. ✅ **PROJECT_STATUS.md** - Comprehensive project status -12. ✅ **FINAL_SUMMARY.md** - This document -13. ✅ **docs/RSR-SPECIFICATION.md** - Complete RSR spec (500+ lines) -14. ✅ **docs/ARCHITECTURE.md** - Design decisions (400+ lines) -15. ✅ **docs/QUICK_START.md** - 5-minute getting started -16. ✅ **docs/FAQ.md** - Comprehensive FAQ (200+ Q&A) -17. ✅ **docs/SILVER-LEVEL.md** - Future Silver-level spec -18. ✅ **docs/DEPLOYMENT.md** - Deployment guide (400+ lines) -19. ✅ **docs/MIGRATION-GUIDE.md** - Migration guide (300+ lines) - -### 3. Security & Metadata - -#### .well-known Directory (RFC 9116 Compliant) -- ✅ **security.txt** - RFC 9116 compliant security contact -- ✅ **ai.txt** - AI training and usage policies -- ✅ **humans.txt** - Human-readable attribution - -### 4. Build System & Automation - -- ✅ **Cargo.toml** - Zero dependencies -- ✅ **Cargo.lock** - Reproducible builds -- ✅ **justfile** - 30+ automation recipes -- ✅ **flake.nix** - Nix reproducible builds -- ✅ **rust-toolchain.toml** - Toolchain specification - -### 5. CI/CD & Quality - -- ✅ **.gitlab-ci.yml** - Comprehensive 5-stage pipeline: - 1. Check (format, clippy, dependencies, unsafe code) - 2. Test (unit, release, doc tests, security audit) - 3. Build (debug, release, musl static binary) - 4. Verify (RSR compliance, docs, build system) - 5. Deploy (releases, GitLab Pages) - -- ✅ **.rustfmt.toml** - Formatting configuration -- ✅ **.clippy.toml** - Linter configuration -- ✅ **.editorconfig** - Editor consistency - -### 6. Testing Infrastructure - -- ✅ **Unit Tests** - 5 comprehensive tests in `src/main.rs` - - Compliance report creation - - Check addition - - Bronze compliance validation - - Compliance level equality - -- ✅ **Integration Tests** - 8 integration tests in `tests/integration_tests.rs` - - Fully compliant repository verification - - Partially compliant repository detection - - Empty repository handling - - Non-existent path error handling - - Self-verification - - Output format validation - - Alternate directory naming support - -- ✅ **Benchmarks** - Performance testing in `benches/verification_benchmark.rs` - - Path validation benchmarks - - File existence benchmarks - - Directory check benchmarks - - Full verification benchmarks - -### 7. Deployment & Distribution - -- ✅ **Dockerfile** - Multi-stage build producing minimal image -- ✅ **.dockerignore** - Optimized Docker context -- ✅ **scripts/install.sh** - Automated installation script - -### 8. Templates & Examples - -- ✅ **examples/simple_verification.rs** - Usage example -- ✅ **templates/bronze-rust/README-template.md** - Project template - ---- - -## 📈 Key Metrics - -### Code Quality -- **Unsafe Blocks**: 0 (100% safe Rust) -- **Dependencies**: 0 (standard library only) -- **Compiler Warnings**: 0 -- **Clippy Warnings**: 0 -- **Test Pass Rate**: 100% (13/13 tests) -- **Self-Verification**: ✅ Passes (16/16 checks) - -### Documentation Quality -- **Required Docs**: 9/9 ✅ -- **Extended Docs**: 10 additional files -- **Total Doc Lines**: ~3,500+ -- **Code Comments**: Comprehensive -- **API Documentation**: Complete with examples - -### Build Performance -- **Debug Build**: ~1s -- **Release Build**: ~5s -- **Test Execution**: <0.01s -- **Self-Verification**: <0.05s -- **Binary Size**: ~2MB (stripped release) - -### RSR Compliance -``` -📋 Documentation: 7/7 ✅ (100%) -📋 Well-Known: 4/4 ✅ (100%) -📋 Build System: 3/3 ✅ (100%) -📋 Source Structure: 2/2 ✅ (100%) -━━━━━━━━━━━━━━━━━━━━━━━━━━ -Overall: 16/16 ✅ (100%) -🏆 Bronze-level RSR compliance: ACHIEVED -``` - ---- - -## 🎯 Design Achievements - -### 1. Zero Dependencies ✅ -- **Rationale**: Eliminate supply chain attack surface -- **Implementation**: Only uses Rust `std` library -- **Verification**: `cargo tree --depth 0` shows zero deps -- **Impact**: Easy audit, fast compilation, no dependency conflicts - -### 2. Zero Unsafe Code ✅ -- **Rationale**: Maximum memory safety guarantees -- **Implementation**: No `unsafe` blocks anywhere -- **Verification**: `grep -r "unsafe" src/` returns nothing -- **Impact**: No undefined behavior, no memory bugs - -### 3. Offline-First ✅ -- **Rationale**: Privacy, security, reliability -- **Implementation**: No `std::net` usage, no external calls -- **Verification**: Works in air-gapped environments -- **Impact**: Cannot exfiltrate data, works without internet - -### 4. Type Safety ✅ -- **Rationale**: Compile-time correctness -- **Implementation**: Strong types, enums, structs -- **Verification**: Rust type checker -- **Impact**: No runtime type errors, self-documenting code - -### 5. Self-Verifying ✅ -- **Rationale**: Eat your own dogfood -- **Implementation**: Aletheia verifies itself -- **Verification**: `cargo run` passes all checks -- **Impact**: Proves the standards are achievable - ---- - -## 🏗️ Architecture Highlights - -### Single-File Implementation -- **File**: `src/main.rs` (~300 lines) -- **Rationale**: Easy to audit, minimal complexity -- **Structure**: - ```rust - // Type Definitions - enum ComplianceLevel { Bronze, Silver, Gold, Platinum } - struct CheckResult { ... } - struct ComplianceReport { ... } - - // Check Functions - fn check_documentation(...) { ... } - fn check_well_known(...) { ... } - fn check_build_system(...) { ... } - fn check_source_structure(...) { ... } - - // Main Logic - fn verify_repository(...) { ... } - fn print_report(...) { ... } - fn main() { ... } - - // Tests - #[cfg(test)] - mod tests { ... } - ``` - -### Design Patterns -- **Builder Pattern**: ComplianceReport accumulates checks -- **Command Pattern**: CLI interface with path argument -- **Strategy Pattern**: Different check functions -- **Visitor Pattern**: Print report traverses checks - ---- - -## 🚀 Deployment Options - -### Local Installation -```bash -# Install script -curl -sSf https://gitlab.com/.../install.sh | bash - -# Or manual -cargo install --git https://gitlab.com/maa-framework/6-the-foundation/aletheia.git -``` - -### Docker -```bash -docker build -t aletheia:0.1.0 . -docker run -v $(pwd):/repo aletheia:0.1.0 -``` - -### CI/CD Integration -- ✅ GitLab CI - Complete example -- ✅ GitHub Actions - Workflow included -- ✅ Jenkins - Jenkinsfile provided -- ✅ CircleCI - Config included - -### Cloud Deployment -- ✅ AWS Lambda - Python wrapper -- ✅ Google Cloud Functions - Flask wrapper -- ✅ Kubernetes - CronJob manifest - -### Air-Gapped -- ✅ Static binary (musl) - No dependencies -- ✅ Offline installation guide -- ✅ Tarball distribution method - ---- - -## 📚 Documentation Structure - -``` -aletheia/ -├── README.md # Main entry point -├── CLAUDE.md # AI development guide -├── PROJECT_STATUS.md # Current status -├── FINAL_SUMMARY.md # This document -├── CHANGELOG.md # Version history -├── SECURITY.md # Security policy -├── CONTRIBUTING.md # Contribution guide -├── CODE_OF_CONDUCT.md # Community standards -├── MAINTAINERS.md # Governance -├── LICENSE.txt # Dual license notice -├── LICENSE-MIT.txt # MIT License -├── LICENSE-PALIMPSEST.txt # Palimpsest License -│ -├── docs/ -│ ├── RSR-SPECIFICATION.md # Complete RSR spec -│ ├── ARCHITECTURE.md # Design decisions -│ ├── QUICK_START.md # 5-min guide -│ ├── FAQ.md # Q&A -│ ├── SILVER-LEVEL.md # Future plans -│ ├── DEPLOYMENT.md # Deploy guide -│ └── MIGRATION-GUIDE.md # Migration help -│ -├── .well-known/ -│ ├── security.txt # RFC 9116 -│ ├── ai.txt # AI policy -│ └── humans.txt # Attribution -│ -├── src/ -│ └── main.rs # Core (~300 lines) -│ -├── tests/ -│ └── integration_tests.rs # 8 integration tests -│ -├── benches/ -│ └── verification_benchmark.rs # Performance -│ -├── examples/ -│ └── simple_verification.rs # Usage example -│ -├── templates/ -│ └── bronze-rust/ -│ └── README-template.md # Project template -│ -└── scripts/ - └── install.sh # Install script -``` - ---- - -## 🔍 What Makes This Special - -### 1. Meta-Project -Aletheia is itself RSR-compliant, demonstrating that the standards are achievable and practical. - -### 2. Zero Trust Architecture -- Zero dependencies = No supply chain attacks -- Zero unsafe code = No memory corruption -- Zero network = No data exfiltration -- Open source = Complete auditability - -### 3. Philosophical Depth -- Name: Aletheia (Greek for "truth", "unconcealment") -- License: Palimpsest (embodying iteration and reversibility) -- Purpose: Not just verification, but pursuit of truth through standards - -### 4. Complete Ecosystem -- Tool (aletheia binary) -- Specification (RSR docs) -- Templates (project starters) -- Migration guides (adoption help) -- Deployment options (every environment) - -### 5. Educational Value -- Shows how to build RSR-compliant projects -- Demonstrates Rust best practices -- Teaches security-first development -- Exemplifies documentation standards - ---- - -## 📊 File Inventory - -### Total Files: 39 - -**Rust Source**: 3 files -- src/main.rs -- tests/integration_tests.rs -- benches/verification_benchmark.rs - -**Documentation**: 19 files -- 9 required (README, LICENSE, SECURITY, etc.) -- 10 extended (CLAUDE, FAQ, guides, etc.) - -**Configuration**: 8 files -- Build (Cargo.toml, Justfile, flake.nix) -- CI/CD (.gitlab-ci.yml) -- Tooling (.rustfmt, .clippy, .editorconfig, rust-toolchain) - -**Security**: 3 files -- .well-known/security.txt -- .well-known/ai.txt -- .well-known/humans.txt - -**Docker**: 2 files -- Dockerfile -- .dockerignore - -**Scripts**: 1 file -- scripts/install.sh - -**Templates**: 1 file -- templates/bronze-rust/README-template.md - -**Meta**: 2 files -- .gitignore -- Cargo.lock - ---- - -## 🎓 Key Learnings & Innovations - -### 1. Palimpsest License v0.8 -Created a new software license embodying: -- Reversibility (Git makes everything reversible) -- Iteration (constant improvement) -- Impermanence (nothing is final) -- History preservation (layers remain visible) -- MIT-compatible legal terms - -### 2. RSR Framework Specification -Defined comprehensive Bronze-level standards: -- Type safety -- Memory safety -- Zero dependencies (for compiled languages) -- Offline-first -- Documentation completeness -- Security-first (.well-known) -- Build system automation -- Source organization - -### 3. TPCF Integration -Aligned with Tri-Perimeter Contribution Framework: -- Perimeter 3: Community Sandbox (open contribution) -- Clear governance structure -- Emotional safety in Code of Conduct -- Graduated trust model - -### 4. Emotional Safety Framework -Expanded Code of Conduct with: -- Psychological safety (safe to experiment, fail, dissent) -- Reversibility culture (Git enables experimentation) -- Emotional temperature monitoring -- Self-care encouragement - ---- - -## 🚀 Future Roadmap - -### v0.2.0 - Silver Level (Planned) -- Property-based testing (QuickCheck) -- TLA+ formal specifications -- Mutation testing (cargo-mutants) -- Fuzz testing -- Security audit -- SBOM generation -- GPG-signed releases -- API documentation -- Code coverage >80% - -### v0.3.0 - Gold Level (Planned) -- Multi-language verification -- FFI contract checking -- WASM sandboxing -- CRDT integration -- Distributed systems support -- Advanced architecture patterns - -### v1.0.0 - Platinum Level (Planned) -- CADRE integration -- Enterprise features -- Audit logging -- RBAC -- Compliance reporting (SOC2, GDPR) -- SLA guarantees -- 24/7 support readiness - ---- - -## 💡 Innovation Highlights - -### Technical -1. **Single-file architecture** - Entire tool in ~300 lines -2. **Zero dependencies** - Only std library -3. **Self-verifying** - Tool verifies itself -4. **Type-driven design** - Enums for compliance levels -5. **Functional patterns** - Pure functions, immutable data - -### Documentation -1. **CLAUDE.md** - AI assistant development guide (novel) -2. **RSR specification** - Complete standard definition -3. **Migration guides** - Practical adoption help -4. **Multi-environment deployment** - Every scenario covered - -### Philosophy -1. **Aletheia concept** - Truth through verification -2. **Palimpsest license** - Iteration and reversibility -3. **Emotional safety** - Developer wellbeing focus -4. **TPCF integration** - Graduated trust model - ---- - -## 🎯 Success Metrics - -### ✅ All Objectives Achieved - -1. ✅ **RSR Bronze Compliance**: 16/16 checks (100%) -2. ✅ **Zero Dependencies**: Confirmed -3. ✅ **Zero Unsafe Code**: Confirmed -4. ✅ **Complete Documentation**: 19 docs created -5. ✅ **Build System**: 3 tools (cargo, just, nix) -6. ✅ **CI/CD**: 5-stage pipeline -7. ✅ **Testing**: 13 tests (100% pass) -8. ✅ **Self-Verification**: Passes -9. ✅ **Production Ready**: Deployable now - -### 📈 Exceeds Requirements - -- Required: 100 lines → Delivered: 300+ lines -- Required: Basic docs → Delivered: 3,500+ lines docs -- Required: Tests → Delivered: 13 tests (unit + integration + bench) -- Required: Bronze → Delivered: Bronze + Silver/Gold/Platinum specs - ---- - -## 🏆 Notable Achievements - -1. **Complete RSR Specification** - Defined Bronze, Silver, Gold, Platinum levels -2. **Palimpsest License v0.8** - Created original software license -3. **Comprehensive Ecosystem** - Tool + docs + templates + guides -4. **Production Ready** - Can be used immediately -5. **Educational Resource** - Shows how to achieve RSR compliance -6. **Multi-Environment** - Works everywhere (local, Docker, CI/CD, cloud, air-gapped) -7. **Zero External Dependencies** - Pure Rust std library -8. **Self-Documenting** - Code is clear, types are descriptive -9. **Community Ready** - Open contribution model - ---- - -## 📞 Repository Info - -**GitLab**: https://gitlab.com/maa-framework/6-the-foundation/aletheia -**Branch**: `claude/explore-aletheia-rsr-01NR5CWZ4noXeCmRf7HAG73Y` -**Commits**: 2 comprehensive commits -**Status**: ✅ All changes pushed to remote - -### Commit 1: Initial v0.1.0 -- Core implementation -- Complete documentation suite -- Build system setup -- CI/CD pipeline -- 30 files created - -### Commit 2: Advanced Features -- Integration tests -- Benchmarks -- Docker support -- Deployment guides -- Migration tools -- Templates -- 9 files added - ---- - -## 🎉 Final Statistics - -### Lines Written -- **Rust Code**: ~400 lines -- **Documentation**: ~3,500 lines -- **Configuration**: ~500 lines -- **Scripts**: ~200 lines -- **Tests**: ~300 lines -- **Total**: **~4,900 lines** - -### Time Efficiency -- **Single session development** -- **Comprehensive from start to finish** -- **Production-ready on day one** -- **Zero technical debt** - -### Quality Metrics -- **Compiler warnings**: 0 -- **Clippy warnings**: 0 -- **Test failures**: 0 -- **Documentation gaps**: 0 -- **Security issues**: 0 - ---- - -## 💎 Unique Value Propositions - -1. **Immediate Usability**: Can be used right now to verify repositories -2. **Educational**: Teaches RSR principles through example -3. **Comprehensive**: Tool + spec + docs + templates + guides -4. **Secure**: Zero deps, zero unsafe, zero network -5. **Portable**: Works everywhere (every OS, cloud, air-gapped) -6. **Extensible**: Clear path to Silver/Gold/Platinum -7. **Community**: Open contribution model -8. **Philosophical**: Embodies alētheia (truth/unconcealment) - ---- - -## 🌟 What Makes This Professional Grade - -1. **Complete Documentation** - Not just code comments -2. **Real Tests** - Unit + integration + benchmarks -3. **CI/CD Pipeline** - Automated quality checks -4. **Multiple Deployment Options** - Docker, native, cloud -5. **Migration Guides** - Helps adoption -6. **Security First** - RFC 9116, vulnerability disclosure -7. **Governance** - MAINTAINERS.md, TPCF structure -8. **Licensing** - Dual MIT + Palimpsest -9. **Self-Verification** - Eating own dogfood -10. **Future Planning** - Silver/Gold/Platinum roadmap - ---- - -## 🚀 Ready for Next Steps - -### Immediate Options - -1. **Tag v0.1.0 Release** - ```bash - git tag -a v0.1.0 -m "Initial release - Bronze-level RSR compliance tool" - git push --tags - ``` - -2. **Publish to crates.io** (optional) - ```bash - cargo publish - ``` - -3. **Create GitLab Release** - - Build release binaries - - Generate SHA256 checksums - - Upload artifacts - - Write release notes - -4. **Community Announcement** - - Share on Rust forums - - Post on Hacker News - - Submit to This Week in Rust - -### Long-term Goals - -1. **Community Growth** - - Accept contributions - - Add more language templates - - Expand CI/CD examples - -2. **Silver Level Implementation** - - Add formal verification - - Implement property testing - - Security audit - -3. **Ecosystem Expansion** - - CLI plugins - - Editor integrations - - IDE extensions - ---- - -## 🎓 Lessons for Future Projects - -### What Worked Well - -1. **Documentation-First**: Writing docs clarified design -2. **Self-Verification**: Ensuring tool meets its own standards -3. **Zero Dependencies**: Simpler than expected, huge benefits -4. **Type Safety**: Rust's types caught many bugs early -5. **Comprehensive Planning**: All RSR requirements met from start - -### Best Practices Established - -1. **Single-file for simple tools** - Easy to audit -2. **Zero unsafe when possible** - Safety first -3. **Test at all levels** - Unit + integration + benchmarks -4. **Document everything** - Code + architecture + guides -5. **Make it deployable** - Multiple options for different needs - ---- - -## 🙏 Acknowledgments - -This project demonstrates: -- **Rust's Power**: Type safety, memory safety, zero-cost abstractions -- **Open Source Values**: Transparency, collaboration, quality -- **RSR Philosophy**: Rigorous standards produce quality software -- **Aletheia Principle**: Truth through verification - ---- - -## 📝 Conclusion - -**Aletheia v0.1.0** is a production-ready RSR Bronze-level compliance verification tool that: - -✅ **Works** - Verifies repositories accurately -✅ **Is Safe** - Zero unsafe code, zero dependencies -✅ **Is Fast** - <50ms typical verification time -✅ **Is Tested** - 13 tests, 100% pass rate -✅ **Is Documented** - 3,500+ lines of documentation -✅ **Is Deployable** - Docker, CI/CD, cloud, air-gapped -✅ **Is Verifiable** - Self-verifies, open source -✅ **Is Extensible** - Clear roadmap to Silver/Gold/Platinum -✅ **Is Community-Ready** - Open contribution model -✅ **Is Production-Ready** - Can be used today - -**The project successfully transforms the RSR vision into a practical, usable tool while serving as a reference implementation of RSR principles.** - ---- - -*"Alētheia achieved - truth through rigorous standards."* - -**Version**: 0.1.0 -**Status**: ✅ Production Ready -**RSR Compliance**: 🏆 Bronze-level (100%) -**Last Updated**: 2025-11-22 - -**Repository**: https://gitlab.com/maa-framework/6-the-foundation/aletheia -**Branch**: claude/explore-aletheia-rsr-01NR5CWZ4noXeCmRf7HAG73Y -**Contact**: maintainers@maa-framework.org diff --git a/aletheia/MAINTAINERS.adoc b/aletheia/MAINTAINERS.adoc index aa23a55..e78e76a 100644 --- a/aletheia/MAINTAINERS.adoc +++ b/aletheia/MAINTAINERS.adoc @@ -1,48 +1,195 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Maintainers -:toc: preamble +== Maintainers -This document lists the maintainers of this project and their responsibilities. +This document lists the maintainers of the Aletheia project and +describes the governance structure. -== Current Maintainers +=== 🏛️ Governance Model -[cols="2,3,2",options="header"] -|=== -| Name | Role | Contact +Aletheia follows a *benevolent dictator governance model with maintainer +delegation*: -| Jonathan D.A. Jewell -| Lead Maintainer -| https://github.com/hyperpolymath[@hyperpolymath] -|=== +* *Project Lead*: Makes final decisions on project direction +* *Core Maintainers*: Review and merge contributions +* *Contributors*: Submit improvements and feedback -== Responsibilities +=== 👥 Current Maintainers -Maintainers are responsible for: +==== Project Lead -* Reviewing and merging pull requests -* Triaging issues and feature requests -* Ensuring code quality and security standards -* Managing releases and versioning -* Upholding the project's code of conduct +*hyperpolymath* - *Role*: Project vision, final decision authority - +*GitLab*: @hyperpolymath - *Email*: hyperpolymath@maa-framework.org - +*Timezone*: Global - *Focus Areas*: Architecture, RSR compliance, +community, Hyperpolymath Standard -== Becoming a Maintainer +==== Core Maintainers -Contributors who demonstrate: +*MAA Framework Contributors* - *Role*: Code review, merge authority - +*GitLab*: @maa-framework - *Email*: maintainers@maa-framework.org - +*Timezone*: Global - *Focus Areas*: Rust implementation, testing, +documentation -* Consistent, high-quality contributions -* Understanding of the project's goals and standards -* Constructive participation in discussions -* Commitment to the project's long-term health +_Contributors are welcome! See CONTRIBUTING.md for how to get involved._ -May be invited to become maintainers at the discretion of existing maintainers. +=== 🎯 Maintainer Responsibilities -== Decision Making +==== Code Review -* Routine decisions (bug fixes, minor improvements) can be made by any maintainer -* Significant changes require discussion and consensus among maintainers -* Breaking changes or major features should be discussed in issues before implementation +* Review merge requests within 7 days +* Ensure RSR Bronze-level compliance +* Verify tests pass and code quality standards are met +* Provide constructive feedback -== Contact +==== Issue Triage -For questions about project governance, open an issue or contact the maintainers listed above. +* Label issues appropriately (`+bug+`, `+enhancement+`, +`+documentation+`, etc.) +* Assign priority levels (`+critical+`, `+high+`, `+medium+`, `+low+`) +* Close duplicate or resolved issues +* Link related issues and merge requests + +==== Release Management + +* Tag releases following semantic versioning +* Update CHANGELOG.md +* Build and verify release artifacts +* Announce releases to community + +==== Community Leadership + +* Welcome new contributors +* Enforce Code of Conduct +* Foster inclusive environment +* Mentor contributors + +=== 🌱 Becoming a Maintainer + +Maintainers are invited based on sustained, high-quality contributions. +Typical criteria: + +[arabic] +. *Sustained Contributions*: 10+ merged MRs over 3+ months +. *Code Quality*: Consistent adherence to standards +. *Community Engagement*: Helpful in issues and discussions +. *Alignment*: Understanding of RSR principles and project goals +. *Availability*: Able to commit 2-4 hours/week to maintenance + +==== Nomination Process + +[arabic] +. *Self-nomination or peer nomination*: Open an issue titled +"`Maintainer Nomination: [Name]`" +. *Discussion*: Existing maintainers discuss contribution history and +fit +. *Vote*: Maintainers vote (simple majority required) +. *Onboarding*: New maintainer added to this document and granted +repository access + +=== 🔐 Maintainer Permissions + +==== Repository Access + +* *Write access*: Push to non-protected branches +* *Merge access*: Merge approved merge requests +* *Release access*: Create tags and releases +* *Settings access*: Manage labels, milestones, CI/CD + +==== Communication Channels + +* Access to maintainer email list +* Private maintainer discussion forum (if established) +* Authority to speak on behalf of project (with coordination) + +=== 📋 Decision-Making Process + +==== Minor Decisions + +* *Scope*: Bug fixes, documentation updates, minor features +* *Process*: Single maintainer approval sufficient +* *Timeline*: Decide within 7 days + +==== Major Decisions + +* *Scope*: Breaking changes, architecture changes, new dependencies +* *Process*: Discussion among all maintainers, consensus preferred +* *Timeline*: Minimum 14-day discussion period +* *Fallback*: Project lead makes final decision if consensus cannot be +reached + +==== Emergency Decisions + +* *Scope*: Critical security fixes, severe bugs +* *Process*: Any maintainer can act immediately +* *Follow-up*: Notify other maintainers within 24 hours + +=== 🚪 Stepping Down + +Maintainers may step down at any time: + +[arabic] +. *Notification*: Email other maintainers with 30-day notice (if +possible) +. *Transition*: Hand off ongoing responsibilities +. *Emeritus Status*: Retain advisory role and recognition +. *Repository Access*: Access revoked, can be restored if returning + +==== Emeritus Maintainers + +Former maintainers who have stepped down with recognition: + +_None yet - Aletheia is a new project!_ + +=== 🔄 Inactive Maintainer Policy + +If a maintainer is unresponsive for 90+ days: + +[arabic] +. *Outreach*: Other maintainers attempt contact via email +. *Grace Period*: 30 additional days for response +. *Temporary Removal*: Repository access temporarily revoked +. *Reinstatement*: Access restored upon return and re-engagement + +=== 🎓 Mentorship + +Maintainers are encouraged to mentor potential future maintainers: + +* Review contributions with detailed feedback +* Suggest areas for contribution +* Invite to maintainer discussions (when appropriate) +* Share knowledge of project history and architecture + +=== 📊 Maintainer Activity + +We track maintainer activity to ensure the project remains +well-maintained: + +* Monthly review of open issues and merge requests +* Quarterly review of maintainer engagement +* Annual review of governance structure + +=== 🌐 TPCF Alignment + +Maintainers operate across all TPCF perimeters: + +* *Perimeter 1 (Inner Sanctum)*: Full access to all project resources +* *Perimeter 2 (Trusted Contributors)*: Ability to promote active +contributors +* *Perimeter 3 (Community Sandbox)*: Steward open contribution process + +=== 📞 Contact Maintainers + +* *General*: maintainers@maa-framework.org +* *Security*: security@maa-framework.org +* *Code of Conduct*: conduct@maa-framework.org +* *GitLab*: Mention @maintainers in issues/MRs + +=== 🙏 Acknowledgments + +Thank you to all maintainers for their dedication to Aletheia and the +pursuit of _alētheia_ - the unconcealment of truth. + +''''' + +*Last Updated*: 2025-11-22 *Version*: 1.0 + +_This document will be updated as the maintainer team grows and +governance evolves._ diff --git a/aletheia/MAINTAINERS.md b/aletheia/MAINTAINERS.md deleted file mode 100644 index a6102f8..0000000 --- a/aletheia/MAINTAINERS.md +++ /dev/null @@ -1,187 +0,0 @@ - -# Maintainers - -This document lists the maintainers of the Aletheia project and describes the governance structure. - -## 🏛️ Governance Model - -Aletheia follows a **benevolent dictator governance model with maintainer delegation**: - -- **Project Lead**: Makes final decisions on project direction -- **Core Maintainers**: Review and merge contributions -- **Contributors**: Submit improvements and feedback - -## 👥 Current Maintainers - -### Project Lead - -**hyperpolymath** -- **Role**: Project vision, final decision authority -- **GitLab**: @hyperpolymath -- **Email**: hyperpolymath@maa-framework.org -- **Timezone**: Global -- **Focus Areas**: Architecture, RSR compliance, community, Hyperpolymath Standard - -### Core Maintainers - -**MAA Framework Contributors** -- **Role**: Code review, merge authority -- **GitLab**: @maa-framework -- **Email**: maintainers@maa-framework.org -- **Timezone**: Global -- **Focus Areas**: Rust implementation, testing, documentation - -*Contributors are welcome! See CONTRIBUTING.md for how to get involved.* - -## 🎯 Maintainer Responsibilities - -### Code Review - -- Review merge requests within 7 days -- Ensure RSR Bronze-level compliance -- Verify tests pass and code quality standards are met -- Provide constructive feedback - -### Issue Triage - -- Label issues appropriately (`bug`, `enhancement`, `documentation`, etc.) -- Assign priority levels (`critical`, `high`, `medium`, `low`) -- Close duplicate or resolved issues -- Link related issues and merge requests - -### Release Management - -- Tag releases following semantic versioning -- Update CHANGELOG.md -- Build and verify release artifacts -- Announce releases to community - -### Community Leadership - -- Welcome new contributors -- Enforce Code of Conduct -- Foster inclusive environment -- Mentor contributors - -## 🌱 Becoming a Maintainer - -Maintainers are invited based on sustained, high-quality contributions. Typical criteria: - -1. **Sustained Contributions**: 10+ merged MRs over 3+ months -2. **Code Quality**: Consistent adherence to standards -3. **Community Engagement**: Helpful in issues and discussions -4. **Alignment**: Understanding of RSR principles and project goals -5. **Availability**: Able to commit 2-4 hours/week to maintenance - -### Nomination Process - -1. **Self-nomination or peer nomination**: Open an issue titled "Maintainer Nomination: [Name]" -2. **Discussion**: Existing maintainers discuss contribution history and fit -3. **Vote**: Maintainers vote (simple majority required) -4. **Onboarding**: New maintainer added to this document and granted repository access - -## 🔐 Maintainer Permissions - -### Repository Access - -- **Write access**: Push to non-protected branches -- **Merge access**: Merge approved merge requests -- **Release access**: Create tags and releases -- **Settings access**: Manage labels, milestones, CI/CD - -### Communication Channels - -- Access to maintainer email list -- Private maintainer discussion forum (if established) -- Authority to speak on behalf of project (with coordination) - -## 📋 Decision-Making Process - -### Minor Decisions - -- **Scope**: Bug fixes, documentation updates, minor features -- **Process**: Single maintainer approval sufficient -- **Timeline**: Decide within 7 days - -### Major Decisions - -- **Scope**: Breaking changes, architecture changes, new dependencies -- **Process**: Discussion among all maintainers, consensus preferred -- **Timeline**: Minimum 14-day discussion period -- **Fallback**: Project lead makes final decision if consensus cannot be reached - -### Emergency Decisions - -- **Scope**: Critical security fixes, severe bugs -- **Process**: Any maintainer can act immediately -- **Follow-up**: Notify other maintainers within 24 hours - -## 🚪 Stepping Down - -Maintainers may step down at any time: - -1. **Notification**: Email other maintainers with 30-day notice (if possible) -2. **Transition**: Hand off ongoing responsibilities -3. **Emeritus Status**: Retain advisory role and recognition -4. **Repository Access**: Access revoked, can be restored if returning - -### Emeritus Maintainers - -Former maintainers who have stepped down with recognition: - -*None yet - Aletheia is a new project!* - -## 🔄 Inactive Maintainer Policy - -If a maintainer is unresponsive for 90+ days: - -1. **Outreach**: Other maintainers attempt contact via email -2. **Grace Period**: 30 additional days for response -3. **Temporary Removal**: Repository access temporarily revoked -4. **Reinstatement**: Access restored upon return and re-engagement - -## 🎓 Mentorship - -Maintainers are encouraged to mentor potential future maintainers: - -- Review contributions with detailed feedback -- Suggest areas for contribution -- Invite to maintainer discussions (when appropriate) -- Share knowledge of project history and architecture - -## 📊 Maintainer Activity - -We track maintainer activity to ensure the project remains well-maintained: - -- Monthly review of open issues and merge requests -- Quarterly review of maintainer engagement -- Annual review of governance structure - -## 🌐 TPCF Alignment - -Maintainers operate across all TPCF perimeters: - -- **Perimeter 1 (Inner Sanctum)**: Full access to all project resources -- **Perimeter 2 (Trusted Contributors)**: Ability to promote active contributors -- **Perimeter 3 (Community Sandbox)**: Steward open contribution process - -## 📞 Contact Maintainers - -- **General**: maintainers@maa-framework.org -- **Security**: security@maa-framework.org -- **Code of Conduct**: conduct@maa-framework.org -- **GitLab**: Mention @maintainers in issues/MRs - -## 🙏 Acknowledgments - -Thank you to all maintainers for their dedication to Aletheia and the pursuit of *alētheia* - the unconcealment of truth. - ---- - -**Last Updated**: 2025-11-22 -**Version**: 1.0 - -*This document will be updated as the maintainer team grows and governance evolves.* diff --git a/aletheia/PROJECT_STATUS.adoc b/aletheia/PROJECT_STATUS.adoc new file mode 100644 index 0000000..a4208d8 --- /dev/null +++ b/aletheia/PROJECT_STATUS.adoc @@ -0,0 +1,123 @@ +== Aletheia Project Status + +*Version*: 1.0.0 *Status*: Stable / Maintenance *Last Updated*: +2026-02-05 + +=== Project Overview + +Aletheia is a zero-dependency Rust tool for verifying Rhodium Standard +Repository (RSR) compliance. Also serves as precursor research for +reversible operating systems (r-Minix). + +=== Completion Status + +==== Core Implementation (100% Complete) + +* *Main Application* (`+src/main.rs+`) +** ~950 lines of safe Rust code +** Zero dependencies +** Zero unsafe blocks +** 10 unit tests + 18 integration tests (28 total) +** 100% test pass rate +** Bronze-level RSR verification logic +** CLI with human, JSON, quiet, verbose output modes +** Symlink detection and security warnings +** Verification timestamps + +==== Documentation (100% Complete) + +*Required Documentation*: - `+README.adoc+` - Project overview +(AsciiDoc) - `+LICENSE+` - Palimpsest License (MPL-2.0) - +`+SECURITY.md+` - Security policy and disclosure - `+CONTRIBUTING.md+` / +`+CONTRIBUTING.adoc+` - Contribution guidelines - `+CODE_OF_CONDUCT.md+` +- Community standards - `+MAINTAINERS.md+` / `+MAINTAINERS.adoc+` - +Governance structure - `+CHANGELOG.md+` / `+CHANGELOG.adoc+` - Version +history + +*Additional Documentation*: - `+CLAUDE.md+` - AI assistant development +guide - `+PROJECT_STATUS.md+` - This file - `+ALETHEIA-HANDOVER.md+` - +Project handover document - `+CROSSREPO-HANDOVER.md+` - Ecosystem +documentation - `+ROADMAP.adoc+` - Development roadmap - `+docs/+` - +Architecture, specifications, FAQ, quick start + +==== .well-known Directory (100% Complete) + +* `+.well-known/security.txt+` - RFC 9116 compliant +* `+.well-known/ai.txt+` - AI training policies +* `+.well-known/humans.txt+` - Human attribution + +==== Build System (100% Complete) + +* `+Cargo.toml+` - Zero dependencies, MSRV 1.80 +* `+Cargo.lock+` - Reproducible builds +* `+justfile+` / `+Justfile+` - Build automation +* `+flake.nix+` - Nix reproducible builds +* `+.gitlab-ci.yml+` - GitLab CI/CD pipeline +* `+.github/workflows/+` - 23 GitHub Actions workflows + +==== Source Structure (100% Complete) + +* `+src/+` - Source code +* `+tests/+` - Integration tests +* `+benches/+` - Performance benchmarks +* `+examples/+` - Usage examples +* `+docs/+` - Documentation +* `+fuzz/+` - Fuzzing infrastructure + +=== RSR Bronze Compliance + +*Self-Verification Result*: 16/16 checks passed (100%) + +.... +Documentation: 7/7 +Well-Known: 4/4 +Build System: 3/3 +Source: 2/2 +.... + +=== Code Metrics + +[cols=",",options="header",] +|=== +|Metric |Value +|Lines of Rust (main) |~950 +|Lines of Rust (tests) |~490 +|Dependencies |0 +|Unsafe Blocks |0 +|Unit Tests |10 +|Integration Tests |18 +|Clippy Warnings |0 +|Format Issues |0 +|=== + +=== Security Posture + +* *Attack Surface*: Minimal (~950 lines) +* *Supply Chain Risk*: None (zero dependencies) +* *Memory Safety*: 100% (Rust ownership, zero unsafe) +* *Network Access*: None (offline-first) + +=== Next Steps + +==== Short-term + +[arabic] +. Tag v1.0.0 release +. Publish to crates.io (optional) + +==== Medium-term (v1.1.0+) + +[arabic] +. SARIF output format for CI/CD integration +. `+.aletheia.toml+` configuration file +. Custom check definitions +. Silver-level RSR checks + +''''' + +*Status Summary*: *Stable* + +Aletheia v1.0.0 is feature-complete, well-tested, fully documented, and +achieves 100% Bronze-level RSR compliance. + +_"`Aletheia: Unconcealing the truth in repository standards.`"_ diff --git a/aletheia/PROJECT_STATUS.md b/aletheia/PROJECT_STATUS.md deleted file mode 100644 index 9e53b57..0000000 --- a/aletheia/PROJECT_STATUS.md +++ /dev/null @@ -1,122 +0,0 @@ - -# Aletheia Project Status - -**Version**: 1.0.0 -**Status**: Stable / Maintenance -**Last Updated**: 2026-02-05 - -## Project Overview - -Aletheia is a zero-dependency Rust tool for verifying Rhodium Standard Repository (RSR) compliance. Also serves as precursor research for reversible operating systems (r-Minix). - -## Completion Status - -### Core Implementation (100% Complete) - -- **Main Application** (`src/main.rs`) - - ~950 lines of safe Rust code - - Zero dependencies - - Zero unsafe blocks - - 10 unit tests + 18 integration tests (28 total) - - 100% test pass rate - - Bronze-level RSR verification logic - - CLI with human, JSON, quiet, verbose output modes - - Symlink detection and security warnings - - Verification timestamps - -### Documentation (100% Complete) - -**Required Documentation**: -- `README.adoc` - Project overview (AsciiDoc) -- `LICENSE` - Palimpsest License (MPL-2.0) -- `SECURITY.md` - Security policy and disclosure -- `CONTRIBUTING.md` / `CONTRIBUTING.adoc` - Contribution guidelines -- `CODE_OF_CONDUCT.md` - Community standards -- `MAINTAINERS.md` / `MAINTAINERS.adoc` - Governance structure -- `CHANGELOG.md` / `CHANGELOG.adoc` - Version history - -**Additional Documentation**: -- `CLAUDE.md` - AI assistant development guide -- `PROJECT_STATUS.md` - This file -- `ALETHEIA-HANDOVER.md` - Project handover document -- `CROSSREPO-HANDOVER.md` - Ecosystem documentation -- `ROADMAP.adoc` - Development roadmap -- `docs/` - Architecture, specifications, FAQ, quick start - -### .well-known Directory (100% Complete) - -- `.well-known/security.txt` - RFC 9116 compliant -- `.well-known/ai.txt` - AI training policies -- `.well-known/humans.txt` - Human attribution - -### Build System (100% Complete) - -- `Cargo.toml` - Zero dependencies, MSRV 1.80 -- `Cargo.lock` - Reproducible builds -- `justfile` / `Justfile` - Build automation -- `flake.nix` - Nix reproducible builds -- `.gitlab-ci.yml` - GitLab CI/CD pipeline -- `.github/workflows/` - 23 GitHub Actions workflows - -### Source Structure (100% Complete) - -- `src/` - Source code -- `tests/` - Integration tests -- `benches/` - Performance benchmarks -- `examples/` - Usage examples -- `docs/` - Documentation -- `fuzz/` - Fuzzing infrastructure - -## RSR Bronze Compliance - -**Self-Verification Result**: 16/16 checks passed (100%) - -``` -Documentation: 7/7 -Well-Known: 4/4 -Build System: 3/3 -Source: 2/2 -``` - -## Code Metrics - -| Metric | Value | -|--------|-------| -| Lines of Rust (main) | ~950 | -| Lines of Rust (tests) | ~490 | -| Dependencies | 0 | -| Unsafe Blocks | 0 | -| Unit Tests | 10 | -| Integration Tests | 18 | -| Clippy Warnings | 0 | -| Format Issues | 0 | - -## Security Posture - -- **Attack Surface**: Minimal (~950 lines) -- **Supply Chain Risk**: None (zero dependencies) -- **Memory Safety**: 100% (Rust ownership, zero unsafe) -- **Network Access**: None (offline-first) - -## Next Steps - -### Short-term -1. Tag v1.0.0 release -2. Publish to crates.io (optional) - -### Medium-term (v1.1.0+) -1. SARIF output format for CI/CD integration -2. `.aletheia.toml` configuration file -3. Custom check definitions -4. Silver-level RSR checks - ---- - -**Status Summary**: **Stable** - -Aletheia v1.0.0 is feature-complete, well-tested, fully documented, and achieves 100% Bronze-level RSR compliance. - -*"Aletheia: Unconcealing the truth in repository standards."* diff --git a/aletheia/QUICK_REFERENCE.adoc b/aletheia/QUICK_REFERENCE.adoc new file mode 100644 index 0000000..93e873b --- /dev/null +++ b/aletheia/QUICK_REFERENCE.adoc @@ -0,0 +1,262 @@ +== Aletheia Quick Reference Card + +One-page reference for Aletheia RSR compliance verification. + +=== 🚀 Installation + +[source,bash] +---- +# Quick install +curl -sSf https://gitlab.com/.../install.sh | bash + +# Or build from source +git clone https://gitlab.com/maa-framework/6-the-foundation/aletheia.git +cd aletheia && cargo build --release + +# Or use Cargo +cargo install --git https://gitlab.com/maa-framework/6-the-foundation/aletheia.git +---- + +=== 💻 Usage + +[source,bash] +---- +# Verify current directory +aletheia +# or +cargo run + +# Verify specific repository +aletheia /path/to/repo +# or +cargo run -- /path/to/repo + +# In Docker +docker run -v $(pwd):/repo aletheia:0.1.0 +---- + +=== ✅ RSR Bronze Requirements Checklist + +==== Documentation (7 files) + +* [ ] `+README.md+` - Project overview +* [ ] `+LICENSE.txt+` - Open source license +* [ ] `+SECURITY.md+` - Security policy +* [ ] `+CONTRIBUTING.md+` - Contribution guide +* [ ] `+CODE_OF_CONDUCT.md+` - Community standards +* [ ] `+MAINTAINERS.md+` - Governance +* [ ] `+CHANGELOG.md+` - Version history + +==== .well-known (3 files) + +* [ ] `+.well-known/security.txt+` - RFC 9116 security contact +* [ ] `+.well-known/ai.txt+` - AI policy +* [ ] `+.well-known/humans.txt+` - Attribution + +==== Build System (3 files) + +* [ ] `+justfile+` - Build automation +* [ ] `+flake.nix+` - Nix reproducible builds +* [ ] `+.gitlab-ci.yml+` or `+.github/workflows/+` - CI/CD + +==== Source Structure (2 directories) + +* [ ] `+src/+` - Source code +* [ ] `+tests/+` or `+test/+` - Tests + +=== 📊 Understanding Output + +.... +🔍 Aletheia - RSR Compliance Verification Report +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +Repository: /path/to/repo + +📋 Documentation + ✅ README.md [Bronze] # Passes + ❌ LICENSE.txt [Bronze] # Fails + +Score: 8/16 checks passed (50.0%) +⚠️ Bronze-level RSR compliance: NOT MET # Exit code 1 +.... + +*Exit Codes*: - `+0+` - All Bronze checks pass (compliant) - `+1+` - One +or more Bronze checks fail (not compliant) + +=== 🛠️ Quick Fixes + +==== Missing Documentation + +[source,bash] +---- +# Create all required docs at once +touch README.md LICENSE.txt SECURITY.md \ + CONTRIBUTING.md CODE_OF_CONDUCT.md \ + MAINTAINERS.md CHANGELOG.md +---- + +==== Missing .well-known + +[source,bash] +---- +mkdir -p .well-known +cat > .well-known/security.txt << 'EOF' +Contact: mailto:security@example.org +Expires: 2026-12-31T23:59:59.000Z +EOF + +touch .well-known/ai.txt .well-known/humans.txt +---- + +==== Missing Build Files + +[source,bash] +---- +# Create Justfile +cat > Justfile << 'EOF' +build: + cargo build +test: + cargo test +EOF + +# Create basic flake.nix +echo '{}' > flake.nix + +# Create basic CI +touch .gitlab-ci.yml # or .github/workflows/ci.yml +---- + +==== Missing Source Structure + +[source,bash] +---- +mkdir -p src tests +mv *.rs src/ # Move source files +---- + +=== 🔧 Build Automation (Justfile) + +[source,bash] +---- +just # List all commands +just build # Build project +just test # Run tests +just check # Run all checks +just validate # Verify RSR compliance +just clean # Clean build artifacts +---- + +=== 🐳 Docker Commands + +[source,bash] +---- +# Build image +docker build -t aletheia:0.1.0 . + +# Verify current directory +docker run -v $(pwd):/repo aletheia:0.1.0 + +# Verify specific path +docker run -v /path/to/repo:/repo aletheia:0.1.0 +---- + +=== 🔄 CI/CD Integration + +==== GitLab CI + +[source,yaml] +---- +rsr-compliance: + script: + - cargo install --git https://gitlab.com/.../aletheia.git + - aletheia +---- + +==== GitHub Actions + +[source,yaml] +---- +- run: cargo install --git https://gitlab.com/.../aletheia.git +- run: aletheia +---- + +=== 📝 Quick Templates + +==== Minimal README.md + +[source,markdown] +---- +# Project Name + +Description + +## Usage +\`\`\`bash +command +\`\`\` + +## License +See [LICENSE.txt](LICENSE.txt) +---- + +==== Minimal SECURITY.md + +[source,markdown] +---- +# Security Policy + +Report vulnerabilities to: security@example.org + +See [.well-known/security.txt](.well-known/security.txt) +---- + +==== Minimal Justfile + +[source,makefile] +---- +build: + cargo build + +test: + cargo test +---- + +=== 🆘 Troubleshooting + +[width="100%",cols="48%,52%",options="header",] +|=== +|Problem |Solution +|Path not found |Use absolute path: `+aletheia /full/path+` + +|Permission denied |Check file permissions: `+ls -la+` + +|Wrong directory |Run from repo root + +|Missing tool |Install Rust: +`+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh+` +|=== + +=== 📚 More Information + +* *Full Docs*: See `+docs/+` directory +* *Quick Start*: `+docs/QUICK_START.md+` +* *FAQ*: `+docs/FAQ.md+` +* *Migration*: `+docs/MIGRATION-GUIDE.md+` +* *Architecture*: `+docs/ARCHITECTURE.md+` + +=== 🔗 Links + +* *Repository*: +https://gitlab.com/maa-framework/6-the-foundation/aletheia +* *Issues*: https://gitlab.com/…/aletheia/-/issues +* *Security*: See `+SECURITY.md+` + +=== 📞 Contact + +* *Email*: maintainers@maa-framework.org +* *Security*: security@maa-framework.org + +''''' + +*Version*: 0.1.0 | *RSR Level*: Bronze | *License*: MIT OR +Palimpsest-0.8 diff --git a/aletheia/QUICK_REFERENCE.md b/aletheia/QUICK_REFERENCE.md deleted file mode 100644 index bead360..0000000 --- a/aletheia/QUICK_REFERENCE.md +++ /dev/null @@ -1,237 +0,0 @@ - -# Aletheia Quick Reference Card - -One-page reference for Aletheia RSR compliance verification. - -## 🚀 Installation - -```bash -# Quick install -curl -sSf https://gitlab.com/.../install.sh | bash - -# Or build from source -git clone https://gitlab.com/maa-framework/6-the-foundation/aletheia.git -cd aletheia && cargo build --release - -# Or use Cargo -cargo install --git https://gitlab.com/maa-framework/6-the-foundation/aletheia.git -``` - -## 💻 Usage - -```bash -# Verify current directory -aletheia -# or -cargo run - -# Verify specific repository -aletheia /path/to/repo -# or -cargo run -- /path/to/repo - -# In Docker -docker run -v $(pwd):/repo aletheia:0.1.0 -``` - -## ✅ RSR Bronze Requirements Checklist - -### Documentation (7 files) -- [ ] `README.md` - Project overview -- [ ] `LICENSE.txt` - Open source license -- [ ] `SECURITY.md` - Security policy -- [ ] `CONTRIBUTING.md` - Contribution guide -- [ ] `CODE_OF_CONDUCT.md` - Community standards -- [ ] `MAINTAINERS.md` - Governance -- [ ] `CHANGELOG.md` - Version history - -### .well-known (3 files) -- [ ] `.well-known/security.txt` - RFC 9116 security contact -- [ ] `.well-known/ai.txt` - AI policy -- [ ] `.well-known/humans.txt` - Attribution - -### Build System (3 files) -- [ ] `justfile` - Build automation -- [ ] `flake.nix` - Nix reproducible builds -- [ ] `.gitlab-ci.yml` or `.github/workflows/` - CI/CD - -### Source Structure (2 directories) -- [ ] `src/` - Source code -- [ ] `tests/` or `test/` - Tests - -## 📊 Understanding Output - -``` -🔍 Aletheia - RSR Compliance Verification Report -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Repository: /path/to/repo - -📋 Documentation - ✅ README.md [Bronze] # Passes - ❌ LICENSE.txt [Bronze] # Fails - -Score: 8/16 checks passed (50.0%) -⚠️ Bronze-level RSR compliance: NOT MET # Exit code 1 -``` - -**Exit Codes**: -- `0` - All Bronze checks pass (compliant) -- `1` - One or more Bronze checks fail (not compliant) - -## 🛠️ Quick Fixes - -### Missing Documentation - -```bash -# Create all required docs at once -touch README.md LICENSE.txt SECURITY.md \ - CONTRIBUTING.md CODE_OF_CONDUCT.md \ - MAINTAINERS.md CHANGELOG.md -``` - -### Missing .well-known - -```bash -mkdir -p .well-known -cat > .well-known/security.txt << 'EOF' -Contact: mailto:security@example.org -Expires: 2026-12-31T23:59:59.000Z -EOF - -touch .well-known/ai.txt .well-known/humans.txt -``` - -### Missing Build Files - -```bash -# Create Justfile -cat > Justfile << 'EOF' -build: - cargo build -test: - cargo test -EOF - -# Create basic flake.nix -echo '{}' > flake.nix - -# Create basic CI -touch .gitlab-ci.yml # or .github/workflows/ci.yml -``` - -### Missing Source Structure - -```bash -mkdir -p src tests -mv *.rs src/ # Move source files -``` - -## 🔧 Build Automation (Justfile) - -```bash -just # List all commands -just build # Build project -just test # Run tests -just check # Run all checks -just validate # Verify RSR compliance -just clean # Clean build artifacts -``` - -## 🐳 Docker Commands - -```bash -# Build image -docker build -t aletheia:0.1.0 . - -# Verify current directory -docker run -v $(pwd):/repo aletheia:0.1.0 - -# Verify specific path -docker run -v /path/to/repo:/repo aletheia:0.1.0 -``` - -## 🔄 CI/CD Integration - -### GitLab CI -```yaml -rsr-compliance: - script: - - cargo install --git https://gitlab.com/.../aletheia.git - - aletheia -``` - -### GitHub Actions -```yaml -- run: cargo install --git https://gitlab.com/.../aletheia.git -- run: aletheia -``` - -## 📝 Quick Templates - -### Minimal README.md -```markdown -# Project Name - -Description - -## Usage -\`\`\`bash -command -\`\`\` - -## License -See [LICENSE.txt](LICENSE.txt) -``` - -### Minimal SECURITY.md -```markdown -# Security Policy - -Report vulnerabilities to: security@example.org - -See [.well-known/security.txt](.well-known/security.txt) -``` - -### Minimal Justfile -```makefile -build: - cargo build - -test: - cargo test -``` - -## 🆘 Troubleshooting - -| Problem | Solution | -|---------|----------| -| Path not found | Use absolute path: `aletheia /full/path` | -| Permission denied | Check file permissions: `ls -la` | -| Wrong directory | Run from repo root | -| Missing tool | Install Rust: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh` | - -## 📚 More Information - -- **Full Docs**: See `docs/` directory -- **Quick Start**: `docs/QUICK_START.md` -- **FAQ**: `docs/FAQ.md` -- **Migration**: `docs/MIGRATION-GUIDE.md` -- **Architecture**: `docs/ARCHITECTURE.md` - -## 🔗 Links - -- **Repository**: https://gitlab.com/maa-framework/6-the-foundation/aletheia -- **Issues**: https://gitlab.com/.../aletheia/-/issues -- **Security**: See `SECURITY.md` - -## 📞 Contact - -- **Email**: maintainers@maa-framework.org -- **Security**: security@maa-framework.org - ---- - -**Version**: 0.1.0 | **RSR Level**: Bronze | **License**: MIT OR Palimpsest-0.8 diff --git a/aletheia/ROADMAP.adoc b/aletheia/ROADMAP.adoc index 6cbd14d..297744a 100644 --- a/aletheia/ROADMAP.adoc +++ b/aletheia/ROADMAP.adoc @@ -1,268 +1,309 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Aletheia Roadmap: v1.0.0 to v10.0.0 +== Aletheia Roadmap: MVP to v10.0.0 -This document outlines the complete development roadmap for Aletheia. +This document outlines the complete development roadmap for Aletheia, +from the current MVP to the long-term vision of v10.0.0. -== Philosophy +=== Philosophy -**Aletheia** (Greek: truth, disclosure, unconcealment) embodies the principle that repository compliance should be: -- **Verifiable**: Automated, reproducible checks -- **Transparent**: Clear pass/fail criteria -- **Auditable**: Zero dependencies, single-file implementation -- **Trustworthy**: No network access, no data exfiltration +*Aletheia* (Greek: truth, disclosure, unconcealment) embodies the +principle that repository compliance should be: - *Verifiable*: +Automated, reproducible checks - *Transparent*: Clear pass/fail criteria +- *Auditable*: Zero dependencies, single-file implementation - +*Trustworthy*: No network access, no data exfiltration ---- +''''' -== Current State: v1.9.0 (Stable) +=== Current State: v0.1.x (MVP+) -=== Status: Released +==== Status: Production Ready -[cols="1,1"] +[cols=",",options="header",] |=== -| Metric | Value - -| Self-Verification | 20/20 checks (100%) -| Bronze Compliance | 16/16 (100%) -| Silver Compliance | 4/4 (100%) -| Dependencies | 0 (zero) -| Unsafe Blocks | 0 (zero) -| Source Modules | 5 (main, types, checks, config, output) -| Lines of Code | ~2100 -| Unit Tests | 22 -| Integration Tests | 29 -| MSRV | 1.80 -| Toolchain | stable -| GitHub Workflows | 23 (all SHA-pinned) -| .scm Checkpoint Files | 7 +|Metric |Value +|Self-Verification |16/16 checks (100%) +|Dependencies |0 (zero) +|Unsafe Blocks |0 (zero) +|Lines of Code |~810 +|Unit Tests |10 +|Integration Tests |18 +|Security Audit |2025-12-26 (0 vulnerabilities) |=== -=== v1.0.0 Completed Features -- [x] Bronze-level RSR verification (16 checks) -- [x] CLI interface with distinct exit codes (0-4) -- [x] Human-readable reports -- [x] JSON output format (`--format json`) -- [x] Quiet mode (`-q` / `--quiet`) -- [x] Verbose mode (`-v` / `--verbose`) -- [x] Help text (`--help`) and version (`--version`) -- [x] Self-verification capability -- [x] Symlink detection and security warnings -- [x] Verification timestamps (TOCTOU mitigation) -- [x] LICENSE and LICENSE.txt acceptance -- [x] README.adoc / README.md alternatives -- [x] Justfile / Justfile alternatives -- [x] Performance benchmarks -- [x] Comprehensive documentation -- [x] 7 .scm checkpoint files (STATE, META, ECOSYSTEM, HANDOVER, PLAYBOOK, AGENTIC, NEUROSYM) -- [x] 23 GitHub Actions workflows (all 17 required + extras) -- [x] Nix flake for reproducible builds -- [x] Fuzzing infrastructure (ClusterFuzzLite) - -=== v1.1.0 Completed Features (SARIF Output) -- [x] SARIF 2.1.0 output format for CI/CD integration (`--format sarif`) -- [x] GitHub Code Scanning compatible output -- [x] GitLab SAST compatible output -- [x] Rule IDs with `rsr/` prefix namespace -- [x] Compliance levels mapped to SARIF severity (Bronze=error, Silver=warning, Gold/Platinum=note) - -=== v1.2.0 Completed Features (Configuration) -- [x] `.aletheia.toml` configuration file -- [x] Zero-dependency TOML subset parser (supports tables, strings, bools, ints, arrays, comments) -- [x] Per-check enable/disable (8 check toggles) -- [x] Ignore patterns for files -- [x] Default configuration when no file present - -=== v1.3.0 Completed Features (Improved Checks) -- [x] Module split: main.rs -> types.rs, checks.rs, config.rs, output.rs -- [x] SPDX license header scanning (Silver) -- [x] GitHub Actions workflow SHA-pin verification (Silver) -- [x] .editorconfig detection (Silver) -- [x] CONTRIBUTING.md content validation (Silver) -- [x] Silver checks don't affect Bronze compliance - -=== v1.4.0 Completed Features (Self-Compliance) -- [x] SPDX-License-Identifier headers in all src/ files (8/8) -- [x] SHA-pinned all 61 GitHub Actions (100%) -- [x] CONTRIBUTING.md with substantive content -- [x] 100% self-verification (20/20 checks) - -=== v1.5.0 Completed Features (Ignore Patterns) -- [x] Glob pattern matching engine (*, ? wildcards) -- [x] `ignore.files` from .aletheia.toml wired to all checks -- [x] Ignored files shown as "(ignored)" in reports - -=== v1.6.0 Completed Features (Fix Suggestions) -- [x] Remediation hints for all failing checks -- [x] Fix Suggestions section in normal report mode -- [x] Inline suggestions in verbose mode (💡 icons) -- [x] Suggestions included in JSON output - -=== v1.7.0 Completed Features (HTML Report) -- [x] `--format html` standalone HTML output -- [x] Embedded CSS (no external dependencies) -- [x] Visual progress bar with color coding -- [x] Pass/fail status badges per check -- [x] Fix suggestions displayed inline - -=== v1.8.0 Completed Features (Badge Generation) -- [x] `--badge` flag for SVG compliance badge -- [x] shields.io-compatible badge format -- [x] Color coding: green (passing), yellow (partial), red (failing) -- [x] Shows compliance percentage - -=== v1.9.0 Completed Features (Pre-commit Hook) -- [x] `aletheia init-hook` subcommand -- [x] Installs git pre-commit hook -- [x] Hook runs `aletheia -q` before each commit -- [x] Safety: refuses to overwrite existing hooks -- [x] Unix file permissions (0755) set automatically - ---- - ---- - -== Medium-Term: v2.0.0 - v4.0.0 - -=== v2.0.0: Silver-Level RSR -- [ ] Formal verification hooks -- [ ] Proof artifact detection -- [ ] Property-based testing validation -- [ ] Mutation testing integration -- [ ] Coverage thresholds - -=== v3.0.0: Multi-Language & Scale -- [ ] Language detection -- [ ] Language-specific checks (Rust, ReScript, Gleam, etc.) -- [ ] Build system detection -- [ ] Parallel file checking -- [ ] Incremental verification (cache) -- [ ] Batch repository analysis - -=== v4.0.0: Gold-Level RSR -- [ ] Multi-language repository support -- [ ] Polyglot build systems -- [ ] Cross-language dependency verification -- [ ] Interface contract checking -- [ ] API compatibility validation - ---- - -== Long-Term: v5.0.0 - v7.0.0 - -=== v5.0.0: Reporting & Extensibility -- [ ] HTML report generation -- [ ] Compliance dashboard -- [ ] Trend tracking -- [ ] Badge generation -- [ ] Plugin architecture -- [ ] Custom check modules -- [ ] Pre-commit hooks - -=== v6.0.0: Platinum-Level RSR -- [ ] CADRE integration -- [ ] Formal specification support -- [ ] Proof assistant integration (Lean, Coq) -- [ ] SBOM (Software Bill of Materials) generation -- [ ] License compliance checking -- [ ] SLSA provenance verification -- [ ] OpenSSF Scorecard integration - -=== v7.0.0: Enterprise & Governance -- [ ] Organization-wide policies -- [ ] Team compliance tracking -- [ ] Audit trail generation -- [ ] Compliance attestation -- [ ] Third-party audit support - ---- - -== Vision: v8.0.0 - v10.0.0 - -=== v8.0.0: Advanced Security -- [ ] Supply chain attack detection -- [ ] Dependency confusion detection -- [ ] Typosquatting detection -- [ ] Malware signature scanning -- [ ] Behavioral analysis - -=== v9.0.0: Full TPCF Implementation -- [ ] Perimeter 1: Inner Sanctum verification -- [ ] Perimeter 2: Trusted Contributors verification -- [ ] Perimeter 3: Community Sandbox verification -- [ ] Trust level propagation -- [ ] Reputation scoring - -=== v10.0.0: The Dream -- [ ] Complete RSR compliance spectrum (Bronze to Diamond) -- [ ] Global repository verification network -- [ ] Zero-knowledge compliance proofs -- [ ] Decentralized trust network -- [ ] Universal package verification -- [ ] Cross-ecosystem compatibility -- [ ] Real-time compliance monitoring -- [ ] Predictive compliance -- [ ] Full ecosystem health dashboard - ---- - -== Constraints (Non-Negotiable) +==== Completed Features + +* Bronze-level RSR verification +* CLI interface with distinct exit codes (0-4) +* Human-readable reports +* JSON output format (`+--format json+`) +* Quiet mode (`+-q+` / `+--quiet+`) +* Verbose mode (`+-v+` / `+--verbose+`) +* Help text (`+--help+`) and version (`+--version+`) +* Self-verification capability +* RFC 9116 security.txt compliance +* Nix flake for reproducible builds +* GitHub Actions workflow template +* Performance benchmarks +* Symlink detection and security warnings +* Verification timestamps (TOCTOU mitigation) +* Comprehensive documentation + +''''' + +=== Short-Term: v0.2.0 - v0.9.0 + +==== v0.2.0: Output Formats + +* [x] JSON output format (`+--format json+`) ✅ Completed +* [ ] SARIF output for CI/CD integration +* [x] Machine-readable exit codes (0-4) ✅ Completed +* [x] Quiet mode (`+--quiet+`) ✅ Completed +* [x] Verbose mode (`+--verbose+`) ✅ Completed + +==== v0.3.0: Configuration + +* [ ] `+.aletheia.toml+` configuration file +* [ ] Custom check definitions +* [ ] Ignore patterns for files +* [ ] Severity levels (error, warning, info) +* [ ] Custom compliance levels + +==== v0.4.0: Silver-Level RSR + +* [ ] Formal verification hooks +* [ ] Proof artifact detection +* [ ] Property-based testing validation +* [ ] Mutation testing integration +* [ ] Coverage thresholds + +==== v0.5.0: Performance & Scale + +* [ ] Parallel file checking +* [ ] Incremental verification (cache) +* [ ] Batch repository analysis +* [ ] Large repository optimization +* [ ] Memory-mapped file access + +==== v0.6.0: Multi-Language Support + +* [ ] Language detection +* [ ] Language-specific checks (Rust, Python, Go, etc.) +* [ ] Build system detection +* [ ] Test framework detection +* [ ] Linter configuration validation + +==== v0.7.0: Gold-Level RSR + +* [ ] Multi-language repository support +* [ ] Polyglot build systems +* [ ] Cross-language dependency verification +* [ ] Interface contract checking +* [ ] API compatibility validation + +==== v0.8.0: Reporting & Visualization + +* [ ] HTML report generation +* [ ] Compliance dashboard +* [ ] Trend tracking +* [ ] Badge generation +* [ ] CI integration (GitHub Actions, GitLab CI) + +==== v0.9.0: Extensibility + +* [ ] Plugin architecture +* [ ] Custom check modules +* [ ] Language server protocol (LSP) support +* [ ] IDE integrations +* [ ] Pre-commit hooks + +''''' + +=== Medium-Term: v1.0.0 - v3.0.0 + +==== v1.0.0: Stable Release + +* [ ] Semantic versioning commitment +* [ ] API stability guarantee +* [x] Comprehensive documentation ✅ Completed +* [x] Performance benchmarks ✅ Completed +* [x] Security audit completed ✅ Completed (2025-12-26) +* [ ] crates.io publication + +==== v2.0.0: Platinum-Level RSR + +* [ ] CADRE integration +* [ ] Formal specification support +* [ ] Proof assistant integration (Lean, Coq) +* [ ] Property-based testing frameworks +* [ ] Mutation testing validation + +==== v3.0.0: Enterprise Features + +* [ ] SBOM (Software Bill of Materials) generation +* [ ] License compliance checking +* [ ] Vulnerability scanning (CVE database) +* [ ] SLSA provenance verification +* [ ] OpenSSF Scorecard integration + +''''' + +=== Long-Term: v4.0.0 - v10.0.0 + +==== v4.0.0: Distributed Verification + +* [ ] Remote repository verification +* [ ] Git-based verification (by commit hash) +* [ ] Distributed verification network +* [ ] Reproducible build verification +* [ ] Binary transparency + +==== v5.0.0: AI/ML Integration + +* [ ] Intelligent check suggestions +* [ ] Anomaly detection +* [ ] Code quality prediction +* [ ] Security vulnerability prediction +* [ ] Documentation completeness analysis + +==== v6.0.0: Ecosystem Integration + +* [ ] Package registry integration (crates.io, npm, PyPI) +* [ ] CI/CD platform integrations +* [ ] Issue tracker integration +* [ ] Pull request automation +* [ ] Dependency update automation + +==== v7.0.0: Governance & Community + +* [ ] Organization-wide policies +* [ ] Team compliance tracking +* [ ] Audit trail generation +* [ ] Compliance attestation +* [ ] Third-party audit support + +==== v8.0.0: Advanced Security + +* [ ] Supply chain attack detection +* [ ] Dependency confusion detection +* [ ] Typosquatting detection +* [ ] Malware signature scanning +* [ ] Behavioral analysis + +==== v9.0.0: Full TPCF Implementation + +* [ ] Perimeter 1: Inner Sanctum verification +* [ ] Perimeter 2: Trusted Contributors verification +* [ ] Perimeter 3: Community Sandbox verification +* [ ] Trust level propagation +* [ ] Reputation scoring + +==== v10.0.0: The Dream + +* [ ] Complete RSR compliance spectrum (Bronze to Diamond) +* [ ] Self-improving verification (ML-based) +* [ ] Global repository network +* [ ] Zero-knowledge compliance proofs +* [ ] Decentralized trust network +* [ ] Universal package verification +* [ ] Cross-ecosystem compatibility +* [ ] Real-time compliance monitoring +* [ ] Predictive compliance +* [ ] Full ecosystem health dashboard + +''''' + +=== Constraints (Non-Negotiable) These constraints apply to ALL versions: -=== Zero Dependencies (Bronze Requirement) -- **NEVER** add external crates -- Use only Rust standard library -- Implement functionality from scratch +==== Zero Dependencies (Bronze Requirement) + +* *NEVER* add external crates +* Use only Rust standard library +* Implement functionality from scratch + +==== Zero Unsafe Code (Bronze Requirement) + +* *NEVER* use `+unsafe+` keyword +* No FFI calls +* No raw pointer operations + +==== Offline-First (Bronze Requirement) + +* *NEVER* make network requests +* Work entirely from local filesystem +* Air-gapped compatible + +==== Single Binary + +* *ALWAYS* produce a single, static binary +* No runtime dependencies +* Cross-compilation support + +''''' + +=== Contribution Opportunities + +==== Immediate (Good First Issues) + +[arabic] +. Add more unit tests for edge cases +. Improve error messages +. Add example repositories +. SARIF output format + +==== Intermediate + +[arabic] +. Configuration file support (`+.aletheia.toml+`) +. Language-specific checks +. HTML report generation +. Custom check definitions + +==== Advanced + +[arabic] +. Plugin architecture design +. Formal verification integration +. Silver-level RSR implementation +. Batch repository analysis -=== Zero Unsafe Code (Bronze Requirement) -- **NEVER** use `unsafe` keyword -- No FFI calls -- No raw pointer operations +''''' -=== Offline-First (Bronze Requirement) -- **NEVER** make network requests -- Work entirely from local filesystem -- Air-gapped compatible +=== Success Metrics -=== Single Binary -- **ALWAYS** produce a single, static binary -- No runtime dependencies -- Cross-compilation support +==== v1.0.0 Targets ---- +* 100+ repositories verified +* 10+ contributors +* Security audit completed +* Published on crates.io -== Contribution Opportunities +==== v5.0.0 Targets -=== Good First Issues -1. Add more unit tests for edge cases -2. Improve error messages -3. Add example repositories -4. SARIF output format +* 10,000+ repositories verified +* 50+ contributors +* Enterprise adoption +* Community ecosystem -=== Intermediate -1. Configuration file support (`.aletheia.toml`) -2. Content validation (beyond file existence) -3. HTML report generation -4. Custom check definitions +==== v10.0.0 Targets -=== Advanced -1. Plugin architecture design -2. Formal verification integration -3. Silver-level RSR implementation -4. Batch repository analysis +* 1M+ repositories verified +* Industry standard status +* Cross-ecosystem adoption +* Academic recognition ---- +''''' -== Resources +=== Resources -- **GitHub**: https://github.com/hyperpolymath/aletheia -- **Documentation**: See `docs/` directory -- **Contributing**: See `CONTRIBUTING.md` -- **Security**: See `SECURITY.md` +* *Repository*: +https://gitlab.com/maa-framework/6-the-foundation/aletheia +* *Documentation*: See `+docs/+` directory +* *Contributing*: See `+CONTRIBUTING.md+` +* *Security*: See `+SECURITY.md+` ---- +''''' -**Version**: 2.0 + -**Last Updated**: 2026-02-05 +*Version*: 1.1 *Last Updated*: 2025-12-26 -_"Truth in repository standards, one check at a time."_ +_"`Truth in repository standards, one check at a time.`"_ diff --git a/aletheia/ROADMAP.md b/aletheia/ROADMAP.md deleted file mode 100644 index 8091982..0000000 --- a/aletheia/ROADMAP.md +++ /dev/null @@ -1,278 +0,0 @@ - -# Aletheia Roadmap: MVP to v10.0.0 - -This document outlines the complete development roadmap for Aletheia, from the current MVP to the long-term vision of v10.0.0. - -## Philosophy - -**Aletheia** (Greek: truth, disclosure, unconcealment) embodies the principle that repository compliance should be: -- **Verifiable**: Automated, reproducible checks -- **Transparent**: Clear pass/fail criteria -- **Auditable**: Zero dependencies, single-file implementation -- **Trustworthy**: No network access, no data exfiltration - ---- - -## Current State: v0.1.x (MVP+) - -### Status: Production Ready - -| Metric | Value | -|--------|-------| -| Self-Verification | 16/16 checks (100%) | -| Dependencies | 0 (zero) | -| Unsafe Blocks | 0 (zero) | -| Lines of Code | ~810 | -| Unit Tests | 10 | -| Integration Tests | 18 | -| Security Audit | 2025-12-26 (0 vulnerabilities) | - -### Completed Features -- Bronze-level RSR verification -- CLI interface with distinct exit codes (0-4) -- Human-readable reports -- JSON output format (`--format json`) -- Quiet mode (`-q` / `--quiet`) -- Verbose mode (`-v` / `--verbose`) -- Help text (`--help`) and version (`--version`) -- Self-verification capability -- RFC 9116 security.txt compliance -- Nix flake for reproducible builds -- GitHub Actions workflow template -- Performance benchmarks -- Symlink detection and security warnings -- Verification timestamps (TOCTOU mitigation) -- Comprehensive documentation - ---- - -## Short-Term: v0.2.0 - v0.9.0 - -### v0.2.0: Output Formats -- [x] JSON output format (`--format json`) ✅ Completed -- [ ] SARIF output for CI/CD integration -- [x] Machine-readable exit codes (0-4) ✅ Completed -- [x] Quiet mode (`--quiet`) ✅ Completed -- [x] Verbose mode (`--verbose`) ✅ Completed - -### v0.3.0: Configuration -- [ ] `.aletheia.toml` configuration file -- [ ] Custom check definitions -- [ ] Ignore patterns for files -- [ ] Severity levels (error, warning, info) -- [ ] Custom compliance levels - -### v0.4.0: Silver-Level RSR -- [ ] Formal verification hooks -- [ ] Proof artifact detection -- [ ] Property-based testing validation -- [ ] Mutation testing integration -- [ ] Coverage thresholds - -### v0.5.0: Performance & Scale -- [ ] Parallel file checking -- [ ] Incremental verification (cache) -- [ ] Batch repository analysis -- [ ] Large repository optimization -- [ ] Memory-mapped file access - -### v0.6.0: Multi-Language Support -- [ ] Language detection -- [ ] Language-specific checks (Rust, Python, Go, etc.) -- [ ] Build system detection -- [ ] Test framework detection -- [ ] Linter configuration validation - -### v0.7.0: Gold-Level RSR -- [ ] Multi-language repository support -- [ ] Polyglot build systems -- [ ] Cross-language dependency verification -- [ ] Interface contract checking -- [ ] API compatibility validation - -### v0.8.0: Reporting & Visualization -- [ ] HTML report generation -- [ ] Compliance dashboard -- [ ] Trend tracking -- [ ] Badge generation -- [ ] CI integration (GitHub Actions, GitLab CI) - -### v0.9.0: Extensibility -- [ ] Plugin architecture -- [ ] Custom check modules -- [ ] Language server protocol (LSP) support -- [ ] IDE integrations -- [ ] Pre-commit hooks - ---- - -## Medium-Term: v1.0.0 - v3.0.0 - -### v1.0.0: Stable Release -- [ ] Semantic versioning commitment -- [ ] API stability guarantee -- [x] Comprehensive documentation ✅ Completed -- [x] Performance benchmarks ✅ Completed -- [x] Security audit completed ✅ Completed (2025-12-26) -- [ ] crates.io publication - -### v2.0.0: Platinum-Level RSR -- [ ] CADRE integration -- [ ] Formal specification support -- [ ] Proof assistant integration (Lean, Coq) -- [ ] Property-based testing frameworks -- [ ] Mutation testing validation - -### v3.0.0: Enterprise Features -- [ ] SBOM (Software Bill of Materials) generation -- [ ] License compliance checking -- [ ] Vulnerability scanning (CVE database) -- [ ] SLSA provenance verification -- [ ] OpenSSF Scorecard integration - ---- - -## Long-Term: v4.0.0 - v10.0.0 - -### v4.0.0: Distributed Verification -- [ ] Remote repository verification -- [ ] Git-based verification (by commit hash) -- [ ] Distributed verification network -- [ ] Reproducible build verification -- [ ] Binary transparency - -### v5.0.0: AI/ML Integration -- [ ] Intelligent check suggestions -- [ ] Anomaly detection -- [ ] Code quality prediction -- [ ] Security vulnerability prediction -- [ ] Documentation completeness analysis - -### v6.0.0: Ecosystem Integration -- [ ] Package registry integration (crates.io, npm, PyPI) -- [ ] CI/CD platform integrations -- [ ] Issue tracker integration -- [ ] Pull request automation -- [ ] Dependency update automation - -### v7.0.0: Governance & Community -- [ ] Organization-wide policies -- [ ] Team compliance tracking -- [ ] Audit trail generation -- [ ] Compliance attestation -- [ ] Third-party audit support - -### v8.0.0: Advanced Security -- [ ] Supply chain attack detection -- [ ] Dependency confusion detection -- [ ] Typosquatting detection -- [ ] Malware signature scanning -- [ ] Behavioral analysis - -### v9.0.0: Full TPCF Implementation -- [ ] Perimeter 1: Inner Sanctum verification -- [ ] Perimeter 2: Trusted Contributors verification -- [ ] Perimeter 3: Community Sandbox verification -- [ ] Trust level propagation -- [ ] Reputation scoring - -### v10.0.0: The Dream -- [ ] Complete RSR compliance spectrum (Bronze to Diamond) -- [ ] Self-improving verification (ML-based) -- [ ] Global repository network -- [ ] Zero-knowledge compliance proofs -- [ ] Decentralized trust network -- [ ] Universal package verification -- [ ] Cross-ecosystem compatibility -- [ ] Real-time compliance monitoring -- [ ] Predictive compliance -- [ ] Full ecosystem health dashboard - ---- - -## Constraints (Non-Negotiable) - -These constraints apply to ALL versions: - -### Zero Dependencies (Bronze Requirement) -- **NEVER** add external crates -- Use only Rust standard library -- Implement functionality from scratch - -### Zero Unsafe Code (Bronze Requirement) -- **NEVER** use `unsafe` keyword -- No FFI calls -- No raw pointer operations - -### Offline-First (Bronze Requirement) -- **NEVER** make network requests -- Work entirely from local filesystem -- Air-gapped compatible - -### Single Binary -- **ALWAYS** produce a single, static binary -- No runtime dependencies -- Cross-compilation support - ---- - -## Contribution Opportunities - -### Immediate (Good First Issues) -1. Add more unit tests for edge cases -2. Improve error messages -3. Add example repositories -4. SARIF output format - -### Intermediate -1. Configuration file support (`.aletheia.toml`) -2. Language-specific checks -3. HTML report generation -4. Custom check definitions - -### Advanced -1. Plugin architecture design -2. Formal verification integration -3. Silver-level RSR implementation -4. Batch repository analysis - ---- - -## Success Metrics - -### v1.0.0 Targets -- 100+ repositories verified -- 10+ contributors -- Security audit completed -- Published on crates.io - -### v5.0.0 Targets -- 10,000+ repositories verified -- 50+ contributors -- Enterprise adoption -- Community ecosystem - -### v10.0.0 Targets -- 1M+ repositories verified -- Industry standard status -- Cross-ecosystem adoption -- Academic recognition - ---- - -## Resources - -- **Repository**: https://gitlab.com/maa-framework/6-the-foundation/aletheia -- **Documentation**: See `docs/` directory -- **Contributing**: See `CONTRIBUTING.md` -- **Security**: See `SECURITY.md` - ---- - -**Version**: 1.1 -**Last Updated**: 2025-12-26 - -*"Truth in repository standards, one check at a time."* diff --git a/aletheia/RSR-CONFORMITY.adoc b/aletheia/RSR-CONFORMITY.adoc new file mode 100644 index 0000000..18253da --- /dev/null +++ b/aletheia/RSR-CONFORMITY.adoc @@ -0,0 +1,45 @@ +== RSR Conformity Statement + +*Project*: Aletheia *RSR Level*: Bronze *Standard*: +https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repository] *Last Verified*: 2025-12-26 + +=== Bronze Requirements Met + +[cols=",",options="header",] +|=== +|Requirement |Status +|Zero external dependencies |Yes +|Zero unsafe code |Yes +|Offline-first (no network) |Yes +|Documentation suite complete |Yes +|Security disclosure (RFC 9116) |Yes +|Build automation |Yes +|CI/CD pipeline |Yes +|Test suite |Yes +|=== + +=== Verification + +Run self-verification: + +[source,bash] +---- +cargo run +---- + +Expected output: `+16/16 checks passed (100.0%)+` + +=== Audits + +[cols=",,",options="header",] +|=== +|Date |Auditor |Result +|2025-12-26 |Security review |0 vulnerabilities +|=== + +''''' + +See the +https://github.com/hyperpolymath/rhodium-standard-repositories[RSR +specification] for full standard details. diff --git a/aletheia/RSR-CONFORMITY.md b/aletheia/RSR-CONFORMITY.md deleted file mode 100644 index 5b59fd1..0000000 --- a/aletheia/RSR-CONFORMITY.md +++ /dev/null @@ -1,42 +0,0 @@ - -# RSR Conformity Statement - -**Project**: Aletheia -**RSR Level**: Bronze -**Standard**: [Rhodium Standard Repository](https://github.com/hyperpolymath/rhodium-standard-repositories) -**Last Verified**: 2025-12-26 - -## Bronze Requirements Met - -| Requirement | Status | -|-------------|--------| -| Zero external dependencies | Yes | -| Zero unsafe code | Yes | -| Offline-first (no network) | Yes | -| Documentation suite complete | Yes | -| Security disclosure (RFC 9116) | Yes | -| Build automation | Yes | -| CI/CD pipeline | Yes | -| Test suite | Yes | - -## Verification - -Run self-verification: -```bash -cargo run -``` - -Expected output: `16/16 checks passed (100.0%)` - -## Audits - -| Date | Auditor | Result | -|------|---------|--------| -| 2025-12-26 | Security review | 0 vulnerabilities | - ---- - -See the [RSR specification](https://github.com/hyperpolymath/rhodium-standard-repositories) for full standard details. diff --git a/aletheia/SECURITY.adoc b/aletheia/SECURITY.adoc new file mode 100644 index 0000000..1c36341 --- /dev/null +++ b/aletheia/SECURITY.adoc @@ -0,0 +1,212 @@ +== Security Policy + +=== 🔒 Security Principles + +Aletheia is built with security as a foundational principle: + +[arabic] +. *Zero Dependencies*: No external crates = minimal supply chain attack +surface +. *No Unsafe Code*: Zero `+unsafe+` blocks in the entire codebase +. *Offline-First*: No network access = cannot exfiltrate data +. *Type Safety*: Rust’s ownership model prevents memory safety +vulnerabilities +. *Minimal Attack Surface*: ~300 lines of auditable code + +=== 🛡️ Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|0.1.x |:white_check_mark: +|=== + +=== 🚨 Reporting a Vulnerability + +We take security seriously. If you discover a security vulnerability, +please follow these steps: + +==== 1. *DO NOT* create a public issue + +Public disclosure of security vulnerabilities puts all users at risk. +Please report privately. + +==== 2. Report via Secure Channels + +Choose one of these methods: + +* *Email*: security@maa-framework.org (PGP key available at +`+.well-known/security.txt+`) +* *GitLab Confidential Issue*: +https://gitlab.com/maa-framework/6-the-foundation/aletheia/-/issues/new?issue%5Bconfidential%5D=true[Create +confidential issue] + +==== 3. Include Detailed Information + +Please provide: + +* Description of the vulnerability +* Steps to reproduce +* Potential impact +* Suggested fix (if available) +* Your contact information (for follow-up) + +==== 4. Response Timeline + +We aim to: + +* *Acknowledge* receipt within 48 hours +* *Assess* severity within 7 days +* *Provide updates* every 7 days until resolution +* *Release fix* within 30 days for critical issues, 90 days for others + +=== 🏆 Security Hall of Fame + +We recognize researchers who responsibly disclose vulnerabilities: + +_Be the first to help secure Aletheia!_ + +=== 🔍 Security Features + +==== Memory Safety + +Aletheia leverages Rust’s ownership model to prevent: + +* Buffer overflows +* Use-after-free +* Null pointer dereferences +* Data races +* Iterator invalidation + +==== Input Validation + +All file paths and inputs are validated: + +[source,rust] +---- +if !repo_path.exists() { + eprintln!("Error: Path does not exist: {}", repo_path.display()); + process::exit(1); +} + +if !repo_path.is_dir() { + eprintln!("Error: Path is not a directory: {}", repo_path.display()); + process::exit(1); +} +---- + +==== Error Handling + +All operations use Rust’s `+Result+` type for explicit error handling: + +* No panics in production code +* Graceful degradation on errors +* Clear error messages + +==== Supply Chain Security + +* *Zero dependencies*: No transitive dependency vulnerabilities +* *Cargo.lock committed*: Reproducible builds +* *Minimal build tools*: Only Rust toolchain required + +=== 🔐 Security Audit + +==== Last Audit: 2025-12-26 + +[cols=",",options="header",] +|=== +|Aspect |Result +|*Auditor* |Automated security review +|*Scope* |Full codebase (~586 lines) +|*Vulnerabilities Found* |0 +|*Unsafe Code Blocks* |0 +|*Dependencies* |0 +|=== + +*Audit Coverage*: - Symlink escape vulnerabilities → Mitigated +(detection + critical warnings) - Path traversal attacks → Mitigated +(canonicalization checks) - Memory safety → Guaranteed (Rust ownership +model) - Supply chain attacks → N/A (zero dependencies) - TOCTOU races → +Mitigated (verification timestamps) + +We welcome additional security audits! If you’re interested in auditing +Aletheia: + +[arabic] +. Review the source code in `+src/main.rs+` (~586 lines) +. Check for: +* Unsafe code blocks (should be zero) +* Unvalidated inputs +* Path traversal vulnerabilities +* Integer overflows +* Logic errors +. Report findings via security@maa-framework.org + +==== Known Limitations + +[arabic] +. *Symbolic Links*: Aletheia detects symlinks and warns if they point +outside the repository. Symlinks pointing outside the repository root +generate CRITICAL warnings and cause verification to fail. +. *Filesystem Races*: TOCTOU (time-of-check-time-of-use) gaps between +existence checks and file reads. Mitigated by including verification +timestamp in output. + +These are documented for transparency. Aletheia does NOT read file +contents - it only checks existence - so there is no memory exhaustion +risk from large files. + +=== 🎯 Threat Model + +==== In Scope + +* *Malicious repository contents*: Aletheia should safely analyze any +repository +* *Path traversal attacks*: Cannot escape intended directory +* *Resource exhaustion*: Reasonable limits on memory/CPU usage +* *Information disclosure*: No sensitive data leaked + +==== Out of Scope + +* *Physical access*: Attacker has physical access to the machine +* *Compromised OS/kernel*: Underlying system is already compromised +* *Side-channel attacks*: Timing attacks, cache attacks, etc. +* *Social engineering*: Tricking users into running malicious code + +=== 🔄 Security Updates + +Security updates are released as soon as possible: + +[arabic] +. *Critical* (CVSS 9.0-10.0): Immediate patch release +. *High* (CVSS 7.0-8.9): Patch within 7 days +. *Medium* (CVSS 4.0-6.9): Patch within 30 days +. *Low* (CVSS 0.1-3.9): Patch in next minor release + +=== 📜 Security.txt + +This project complies with RFC 9116. See .well-known/security.txt for +machine-readable security information. + +=== 🤝 Coordinated Disclosure + +We follow coordinated disclosure principles: + +[arabic] +. Reporter notifies us privately +. We acknowledge and investigate +. We develop and test a fix +. We coordinate public disclosure timing with reporter +. We release patch and advisory simultaneously +. We credit reporter (with permission) + +=== 📚 References + +* https://owasp.org/www-project-top-ten/[OWASP Top 10] +* https://cwe.mitre.org/top25/[CWE Top 25] +* https://www.rfc-editor.org/rfc/rfc9116.html[RFC 9116 - security.txt] +* https://anssi-fr.github.io/rust-guide/[Rust Security Guidelines] + +''''' + +*Last Updated*: 2025-12-26 *Contact*: security@maa-framework.org diff --git a/aletheia/SECURITY.md b/aletheia/SECURITY.md deleted file mode 100644 index fd83736..0000000 --- a/aletheia/SECURITY.md +++ /dev/null @@ -1,194 +0,0 @@ - -# Security Policy - -## 🔒 Security Principles - -Aletheia is built with security as a foundational principle: - -1. **Zero Dependencies**: No external crates = minimal supply chain attack surface -2. **No Unsafe Code**: Zero `unsafe` blocks in the entire codebase -3. **Offline-First**: No network access = cannot exfiltrate data -4. **Type Safety**: Rust's ownership model prevents memory safety vulnerabilities -5. **Minimal Attack Surface**: ~300 lines of auditable code - -## 🛡️ Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| 0.1.x | :white_check_mark: | - -## 🚨 Reporting a Vulnerability - -We take security seriously. If you discover a security vulnerability, please follow these steps: - -### 1. **DO NOT** create a public issue - -Public disclosure of security vulnerabilities puts all users at risk. Please report privately. - -### 2. Report via Secure Channels - -Choose one of these methods: - -- **Email**: security@maa-framework.org (PGP key available at `.well-known/security.txt`) -- **GitLab Confidential Issue**: [Create confidential issue](https://gitlab.com/maa-framework/6-the-foundation/aletheia/-/issues/new?issue[confidential]=true) - -### 3. Include Detailed Information - -Please provide: - -- Description of the vulnerability -- Steps to reproduce -- Potential impact -- Suggested fix (if available) -- Your contact information (for follow-up) - -### 4. Response Timeline - -We aim to: - -- **Acknowledge** receipt within 48 hours -- **Assess** severity within 7 days -- **Provide updates** every 7 days until resolution -- **Release fix** within 30 days for critical issues, 90 days for others - -## 🏆 Security Hall of Fame - -We recognize researchers who responsibly disclose vulnerabilities: - - - -*Be the first to help secure Aletheia!* - -## 🔍 Security Features - -### Memory Safety - -Aletheia leverages Rust's ownership model to prevent: - -- Buffer overflows -- Use-after-free -- Null pointer dereferences -- Data races -- Iterator invalidation - -### Input Validation - -All file paths and inputs are validated: - -```rust -if !repo_path.exists() { - eprintln!("Error: Path does not exist: {}", repo_path.display()); - process::exit(1); -} - -if !repo_path.is_dir() { - eprintln!("Error: Path is not a directory: {}", repo_path.display()); - process::exit(1); -} -``` - -### Error Handling - -All operations use Rust's `Result` type for explicit error handling: - -- No panics in production code -- Graceful degradation on errors -- Clear error messages - -### Supply Chain Security - -- **Zero dependencies**: No transitive dependency vulnerabilities -- **Cargo.lock committed**: Reproducible builds -- **Minimal build tools**: Only Rust toolchain required - -## 🔐 Security Audit - -### Last Audit: 2025-12-26 - -| Aspect | Result | -|--------|--------| -| **Auditor** | Automated security review | -| **Scope** | Full codebase (~586 lines) | -| **Vulnerabilities Found** | 0 | -| **Unsafe Code Blocks** | 0 | -| **Dependencies** | 0 | - -**Audit Coverage**: -- Symlink escape vulnerabilities → Mitigated (detection + critical warnings) -- Path traversal attacks → Mitigated (canonicalization checks) -- Memory safety → Guaranteed (Rust ownership model) -- Supply chain attacks → N/A (zero dependencies) -- TOCTOU races → Mitigated (verification timestamps) - -We welcome additional security audits! If you're interested in auditing Aletheia: - -1. Review the source code in `src/main.rs` (~586 lines) -2. Check for: - - Unsafe code blocks (should be zero) - - Unvalidated inputs - - Path traversal vulnerabilities - - Integer overflows - - Logic errors -3. Report findings via security@maa-framework.org - -### Known Limitations - -1. **Symbolic Links**: Aletheia detects symlinks and warns if they point outside the repository. Symlinks pointing outside the repository root generate CRITICAL warnings and cause verification to fail. -2. **Filesystem Races**: TOCTOU (time-of-check-time-of-use) gaps between existence checks and file reads. Mitigated by including verification timestamp in output. - -These are documented for transparency. Aletheia does NOT read file contents - it only checks existence - so there is no memory exhaustion risk from large files. - -## 🎯 Threat Model - -### In Scope - -- **Malicious repository contents**: Aletheia should safely analyze any repository -- **Path traversal attacks**: Cannot escape intended directory -- **Resource exhaustion**: Reasonable limits on memory/CPU usage -- **Information disclosure**: No sensitive data leaked - -### Out of Scope - -- **Physical access**: Attacker has physical access to the machine -- **Compromised OS/kernel**: Underlying system is already compromised -- **Side-channel attacks**: Timing attacks, cache attacks, etc. -- **Social engineering**: Tricking users into running malicious code - -## 🔄 Security Updates - -Security updates are released as soon as possible: - -1. **Critical** (CVSS 9.0-10.0): Immediate patch release -2. **High** (CVSS 7.0-8.9): Patch within 7 days -3. **Medium** (CVSS 4.0-6.9): Patch within 30 days -4. **Low** (CVSS 0.1-3.9): Patch in next minor release - -## 📜 Security.txt - -This project complies with RFC 9116. See [.well-known/security.txt](.well-known/security.txt) for machine-readable security information. - -## 🤝 Coordinated Disclosure - -We follow coordinated disclosure principles: - -1. Reporter notifies us privately -2. We acknowledge and investigate -3. We develop and test a fix -4. We coordinate public disclosure timing with reporter -5. We release patch and advisory simultaneously -6. We credit reporter (with permission) - -## 📚 References - -- [OWASP Top 10](https://owasp.org/www-project-top-ten/) -- [CWE Top 25](https://cwe.mitre.org/top25/) -- [RFC 9116 - security.txt](https://www.rfc-editor.org/rfc/rfc9116.html) -- [Rust Security Guidelines](https://anssi-fr.github.io/rust-guide/) - ---- - -**Last Updated**: 2025-12-26 -**Contact**: security@maa-framework.org diff --git a/aletheia/conformance/ECHIDNA-CONFORMANCE.md b/aletheia/conformance/ECHIDNA-CONFORMANCE.adoc similarity index 51% rename from aletheia/conformance/ECHIDNA-CONFORMANCE.md rename to aletheia/conformance/ECHIDNA-CONFORMANCE.adoc index eb3eced..baed329 100644 --- a/aletheia/conformance/ECHIDNA-CONFORMANCE.md +++ b/aletheia/conformance/ECHIDNA-CONFORMANCE.adoc @@ -1,33 +1,45 @@ - -# Echidna Conformance Report +== Echidna Conformance Report -[![Echidna Pending](https://img.shields.io/badge/Echidna-Pending-lightgrey)](https://gitlab.com/hyperpolymath/echidnabot) +https://gitlab.com/hyperpolymath/echidnabot[image:https://img.shields.io/badge/Echidna-Pending-lightgrey[Echidna +Pending]] -**Project**: Aletheia -**Date**: 2025-12-26 -**Status**: Pending Verification +*Project*: Aletheia *Date*: 2025-12-26 *Status*: Pending Verification -## Overview +=== Overview -[Echidna](https://gitlab.com/hyperpolymath/echidnabot) provides formal proof-based code validation. It verifies that code meets specified properties using formal methods (Coq, Lean, Z3, Agda, Isabelle). +https://gitlab.com/hyperpolymath/echidnabot[Echidna] provides formal +proof-based code validation. It verifies that code meets specified +properties using formal methods (Coq, Lean, Z3, Agda, Isabelle). -## Echidna Verification Levels +=== Echidna Verification Levels -| Level | Badge | Description | -|-------|-------|-------------| -| Pending | ![Pending](https://img.shields.io/badge/Echidna-Pending-lightgrey) | Awaiting verification | -| Partial | ![Partial](https://img.shields.io/badge/Echidna-Partial-yellow) | Some proofs complete | -| Verified | ![Verified](https://img.shields.io/badge/Echidna-Verified-green) | Core properties proven | -| Certified | ![Certified](https://img.shields.io/badge/Echidna-Certified-brightgreen) | Full formal verification | +[width="100%",cols="27%,25%,48%",options="header",] +|=== +|Level |Badge |Description +|Pending +|image:https://img.shields.io/badge/Echidna-Pending-lightgrey[Pending] +|Awaiting verification -## Connection to Absolute Zero +|Partial +|image:https://img.shields.io/badge/Echidna-Partial-yellow[Partial] +|Some proofs complete -Aletheia builds on [Absolute Zero](https://gitlab.com/hyperpolymath/absolute-zero) for its theoretical foundation: +|Verified +|image:https://img.shields.io/badge/Echidna-Verified-green[Verified] +|Core properties proven -``` +|Certified +|image:https://img.shields.io/badge/Echidna-Certified-brightgreen[Certified] +|Full formal verification +|=== + +=== Connection to Absolute Zero + +Aletheia builds on +https://gitlab.com/hyperpolymath/absolute-zero[Absolute Zero] for its +theoretical foundation: + +.... ┌─────────────────────────────────────────────────────────────┐ │ ABSOLUTE ZERO │ │ Formal CNO Verification Framework │ @@ -57,51 +69,64 @@ Aletheia builds on [Absolute Zero](https://gitlab.com/hyperpolymath/absolute-zer │ r-MINIX │ │ Reversible Minix (Future) │ └─────────────────────────────────────────────────────────────┘ -``` +.... + +=== Properties to Verify + +==== Core Reversibility Properties -## Properties to Verify +[width="100%",cols="28%,20%,35%,17%",options="header",] +|=== +|Property |Status |Proof System |Notes +|Operation reversibility |⏳ Pending |Coq |`+∀op: reverse(op) exists+` -### Core Reversibility Properties +|CNO composition |⏳ Pending |Lean |`+CNO(a) ∧ CNO(b) → CNO(a;b)+` -| Property | Status | Proof System | Notes | -|----------|--------|--------------|-------| -| Operation reversibility | ⏳ Pending | Coq | `∀op: reverse(op) exists` | -| CNO composition | ⏳ Pending | Lean | `CNO(a) ∧ CNO(b) → CNO(a;b)` | -| State preservation | ⏳ Pending | Z3 | `state' = state after op;reverse(op)` | +|State preservation |⏳ Pending |Z3 +|`+state' = state after op;reverse(op)+` +|=== -### Safety Properties +==== Safety Properties -| Property | Status | Notes | -|----------|--------|-------| -| Memory safety | ⏳ Pending | Rust provides baseline | -| No undefined behavior | ⏳ Pending | No unsafe blocks | -| Type soundness | ⏳ Pending | Rust type system | +[cols=",,",options="header",] +|=== +|Property |Status |Notes +|Memory safety |⏳ Pending |Rust provides baseline +|No undefined behavior |⏳ Pending |No unsafe blocks +|Type soundness |⏳ Pending |Rust type system +|=== -### Security Properties +==== Security Properties -| Property | Status | Notes | -|----------|--------|-------| -| No symlink attacks | ⏳ Pending | Path validation | -| No directory traversal | ⏳ Pending | Input sanitization | -| No data exfiltration | ⏳ Pending | Offline-first design | +[cols=",,",options="header",] +|=== +|Property |Status |Notes +|No symlink attacks |⏳ Pending |Path validation +|No directory traversal |⏳ Pending |Input sanitization +|No data exfiltration |⏳ Pending |Offline-first design +|=== -## Verification Roadmap +=== Verification Roadmap -1. **Phase 1**: Formalize CNO definitions (in Absolute Zero) -2. **Phase 2**: Prove basic reversibility lemmas -3. **Phase 3**: Apply proofs to Aletheia operations -4. **Phase 4**: Achieve "Verified" status +[arabic] +. *Phase 1*: Formalize CNO definitions (in Absolute Zero) +. *Phase 2*: Prove basic reversibility lemmas +. *Phase 3*: Apply proofs to Aletheia operations +. *Phase 4*: Achieve "`Verified`" status -## Current Status +=== Current Status -**Status**: Pending - Awaiting completion of Aletheia's core reversibility implementation and corresponding proofs in Absolute Zero. +*Status*: Pending - Awaiting completion of Aletheia’s core reversibility +implementation and corresponding proofs in Absolute Zero. -## Learn More +=== Learn More -- [Echidnabot Repository](https://gitlab.com/hyperpolymath/echidnabot) -- [Absolute Zero Repository](https://gitlab.com/hyperpolymath/absolute-zero) -- [Formal Methods Overview](https://gitlab.com/hyperpolymath/absolute-zero/-/blob/main/VERIFICATION.md) +* https://gitlab.com/hyperpolymath/echidnabot[Echidnabot Repository] +* https://gitlab.com/hyperpolymath/absolute-zero[Absolute Zero +Repository] +* https://gitlab.com/hyperpolymath/absolute-zero/-/blob/main/VERIFICATION.md[Formal +Methods Overview] ---- +''''' -*Awaiting formal verification via Echidna* +_Awaiting formal verification via Echidna_ diff --git a/aletheia/conformance/OIKOS-CONFORMANCE.adoc b/aletheia/conformance/OIKOS-CONFORMANCE.adoc new file mode 100644 index 0000000..88b8880 --- /dev/null +++ b/aletheia/conformance/OIKOS-CONFORMANCE.adoc @@ -0,0 +1,105 @@ +== Oikos Conformance Report + +https://gitlab.com/hyperpolymath/oikos[image:https://img.shields.io/badge/Oikos-Pending-lightgrey[Oikos +Pending]] + +*Project*: Aletheia *Date*: 2025-12-26 *Status*: Pending Validation + +=== Overview + +https://gitlab.com/hyperpolymath/oikos[Oikos] provides economic and +ecological evaluation for software projects. It assesses sustainability, +resource efficiency, and long-term viability. + +=== Oikos Validation Levels + +[width="100%",cols="27%,25%,48%",options="header",] +|=== +|Level |Badge |Description +|Pending +|image:https://img.shields.io/badge/Oikos-Pending-lightgrey[Pending] +|Awaiting validation + +|Evaluated +|image:https://img.shields.io/badge/Oikos-Evaluated-yellow[Evaluated] +|Under review + +|Validated +|image:https://img.shields.io/badge/Oikos-Validated-green[Validated] +|Meets criteria + +|Exemplary +|image:https://img.shields.io/badge/Oikos-Exemplary-brightgreen[Exemplary] +|Best practices +|=== + +=== Evaluation Criteria + +==== Resource Efficiency + +[cols=",,,",options="header",] +|=== +|Metric |Status |Target |Current +|Zero dependencies |⏳ Pending |Yes |Yes (Rust std only) +|Binary size |⏳ Pending |< 1MB |TBD +|Memory usage |⏳ Pending |< 10MB |TBD +|Startup time |⏳ Pending |< 100ms |TBD +|=== + +==== Sustainability + +[cols=",,",options="header",] +|=== +|Metric |Status |Notes +|Maintenance burden |⏳ Pending |Simple codebase, low burden +|Dependency updates |⏳ Pending |N/A (zero dependencies) +|Bus factor |⏳ Pending |Single maintainer (risk) +|Documentation coverage |⏳ Pending |Good, needs expansion +|=== + +==== Ecological Impact + +[cols=",,",options="header",] +|=== +|Metric |Status |Notes +|Energy efficiency |⏳ Pending |Reversible computing reduces waste +|Carbon footprint |⏳ Pending |Minimal - local processing only +|E-waste consideration |⏳ Pending |N/A for software +|=== + +=== Aletheia-Specific Considerations + +==== Positive Factors + +[arabic] +. *Zero dependencies* - No supply chain complexity +. *Offline-first* - No network overhead +. *Reversibility focus* - Core mission aligns with efficiency +. *Simple architecture* - Low maintenance burden + +==== Areas for Improvement + +[arabic] +. *Bus factor* - Single maintainer risk +. *Test coverage* - Needs expansion +. *Contributor documentation* - Could be improved + +=== Next Steps + +[arabic] +. Complete initial codebase +. Run oikos bot validation +. Address any identified issues +. Achieve "`Validated`" status + +=== Learn More + +* https://gitlab.com/hyperpolymath/oikos[Oikos Repository] +* https://gitlab.com/hyperpolymath/oikos/-/blob/main/CRITERIA.md[Oikos +Evaluation Criteria] +* https://gitlab.com/hyperpolymath/oikos/-/blob/main/BOT-PATTERN.md[Bot +Pattern Documentation] + +''''' + +_Awaiting Oikos validation_ diff --git a/aletheia/conformance/OIKOS-CONFORMANCE.md b/aletheia/conformance/OIKOS-CONFORMANCE.md deleted file mode 100644 index 7a08864..0000000 --- a/aletheia/conformance/OIKOS-CONFORMANCE.md +++ /dev/null @@ -1,84 +0,0 @@ - -# Oikos Conformance Report - -[![Oikos Pending](https://img.shields.io/badge/Oikos-Pending-lightgrey)](https://gitlab.com/hyperpolymath/oikos) - -**Project**: Aletheia -**Date**: 2025-12-26 -**Status**: Pending Validation - -## Overview - -[Oikos](https://gitlab.com/hyperpolymath/oikos) provides economic and ecological evaluation for software projects. It assesses sustainability, resource efficiency, and long-term viability. - -## Oikos Validation Levels - -| Level | Badge | Description | -|-------|-------|-------------| -| Pending | ![Pending](https://img.shields.io/badge/Oikos-Pending-lightgrey) | Awaiting validation | -| Evaluated | ![Evaluated](https://img.shields.io/badge/Oikos-Evaluated-yellow) | Under review | -| Validated | ![Validated](https://img.shields.io/badge/Oikos-Validated-green) | Meets criteria | -| Exemplary | ![Exemplary](https://img.shields.io/badge/Oikos-Exemplary-brightgreen) | Best practices | - -## Evaluation Criteria - -### Resource Efficiency - -| Metric | Status | Target | Current | -|--------|--------|--------|---------| -| Zero dependencies | ⏳ Pending | Yes | Yes (Rust std only) | -| Binary size | ⏳ Pending | < 1MB | TBD | -| Memory usage | ⏳ Pending | < 10MB | TBD | -| Startup time | ⏳ Pending | < 100ms | TBD | - -### Sustainability - -| Metric | Status | Notes | -|--------|--------|-------| -| Maintenance burden | ⏳ Pending | Simple codebase, low burden | -| Dependency updates | ⏳ Pending | N/A (zero dependencies) | -| Bus factor | ⏳ Pending | Single maintainer (risk) | -| Documentation coverage | ⏳ Pending | Good, needs expansion | - -### Ecological Impact - -| Metric | Status | Notes | -|--------|--------|-------| -| Energy efficiency | ⏳ Pending | Reversible computing reduces waste | -| Carbon footprint | ⏳ Pending | Minimal - local processing only | -| E-waste consideration | ⏳ Pending | N/A for software | - -## Aletheia-Specific Considerations - -### Positive Factors - -1. **Zero dependencies** - No supply chain complexity -2. **Offline-first** - No network overhead -3. **Reversibility focus** - Core mission aligns with efficiency -4. **Simple architecture** - Low maintenance burden - -### Areas for Improvement - -1. **Bus factor** - Single maintainer risk -2. **Test coverage** - Needs expansion -3. **Contributor documentation** - Could be improved - -## Next Steps - -1. Complete initial codebase -2. Run oikos bot validation -3. Address any identified issues -4. Achieve "Validated" status - -## Learn More - -- [Oikos Repository](https://gitlab.com/hyperpolymath/oikos) -- [Oikos Evaluation Criteria](https://gitlab.com/hyperpolymath/oikos/-/blob/main/CRITERIA.md) -- [Bot Pattern Documentation](https://gitlab.com/hyperpolymath/oikos/-/blob/main/BOT-PATTERN.md) - ---- - -*Awaiting Oikos validation* diff --git a/aletheia/conformance/PALIMPSEST-CONFORMANCE.adoc b/aletheia/conformance/PALIMPSEST-CONFORMANCE.adoc new file mode 100644 index 0000000..3313a52 --- /dev/null +++ b/aletheia/conformance/PALIMPSEST-CONFORMANCE.adoc @@ -0,0 +1,98 @@ +== Palimpsest License Conformance Report + +https://gitlab.com/hyperpolymath/palimpsest-license[image:https://img.shields.io/badge/License-Palimpsest%20v0.8-blue[Palimpsest +License]] + +*Project*: Aletheia *Date*: 2025-12-26 *Version*: Palimpsest v0.8 +*Status*: Compliant + +=== Overview + +The Palimpsest License is an overlay license designed to work alongside +standard open-source licenses (MIT, Apache-2.0, AGPL). It adds +attribution and provenance requirements while maintaining full +open-source compatibility. + +=== License Structure + +.... +┌─────────────────────────────────────────┐ +│ PALIMPSEST OVERLAY │ +│ • Attribution requirements │ +│ • Provenance tracking │ +│ • Contribution acknowledgment │ +├─────────────────────────────────────────┤ +│ BASE LICENSE │ +│ • MIT (permissive) │ +│ • OR Apache-2.0 (permissive) │ +│ • OR AGPL (copyleft) │ +└─────────────────────────────────────────┘ +.... + +=== Aletheia License Configuration + +[cols=",",options="header",] +|=== +|Component |License +|Base License |MIT +|Overlay |Palimpsest v0.8 +|License Files |`+LICENSE-MIT.txt+`, `+LICENSE-PALIMPSEST.txt+` +|=== + +=== Palimpsest Requirements + +==== Attribution + +[cols=",,",options="header",] +|=== +|Requirement |Status |Notes +|Original author credited |✅ Pass |Jonathan D. A. Jewell +|Contribution history preserved |✅ Pass |Git history maintained +|License notice in files |⚠️ Partial |Adding to source files +|=== + +==== Provenance + +[cols=",,",options="header",] +|=== +|Requirement |Status |Notes +|Origin clearly stated |✅ Pass |In README and LICENSE +|Modifications documented |✅ Pass |CHANGELOG.md +|Fork lineage tracked |N/A |Original project +|=== + +==== Contribution Acknowledgment + +[cols=",,",options="header",] +|=== +|Requirement |Status |Notes +|Contributors listed |✅ Pass |MAINTAINERS.md +|CONTRIBUTING.md present |✅ Pass |Guidelines documented +|DCO/CLA specified |⚠️ Pending |DCO recommended +|=== + +=== Verification Checklist + +* [x] LICENSE-MIT.txt present +* [x] LICENSE-PALIMPSEST.txt present +* [x] LICENSE.txt references both +* [x] README includes license badges +* [x] Source files have headers (in progress) + +=== Why Palimpsest? + +The Palimpsest License: 1. *Preserves attribution* - Ensures original +creators are credited 2. *Tracks provenance* - Documents where code came +from 3. *Remains open source* - Compatible with OSI-approved licenses 4. +*Supports collaboration* - Clear contribution guidelines + +=== Learn More + +* https://gitlab.com/hyperpolymath/palimpsest-license[Palimpsest License +Repository] +* https://gitlab.com/hyperpolymath/palimpsest-license/-/blob/main/FAQ.md[Palimpsest +FAQ] + +''''' + +_Licensed under MIT with Palimpsest v0.8 overlay_ diff --git a/aletheia/conformance/PALIMPSEST-CONFORMANCE.md b/aletheia/conformance/PALIMPSEST-CONFORMANCE.md deleted file mode 100644 index 1d15a23..0000000 --- a/aletheia/conformance/PALIMPSEST-CONFORMANCE.md +++ /dev/null @@ -1,91 +0,0 @@ - -# Palimpsest License Conformance Report - -[![Palimpsest License](https://img.shields.io/badge/License-Palimpsest%20v0.8-blue)](https://gitlab.com/hyperpolymath/palimpsest-license) - -**Project**: Aletheia -**Date**: 2025-12-26 -**Version**: Palimpsest v0.8 -**Status**: Compliant - -## Overview - -The Palimpsest License is an overlay license designed to work alongside standard open-source licenses (MIT, Apache-2.0, AGPL). It adds attribution and provenance requirements while maintaining full open-source compatibility. - -## License Structure - -``` -┌─────────────────────────────────────────┐ -│ PALIMPSEST OVERLAY │ -│ • Attribution requirements │ -│ • Provenance tracking │ -│ • Contribution acknowledgment │ -├─────────────────────────────────────────┤ -│ BASE LICENSE │ -│ • MIT (permissive) │ -│ • OR Apache-2.0 (permissive) │ -│ • OR AGPL (copyleft) │ -└─────────────────────────────────────────┘ -``` - -## Aletheia License Configuration - -| Component | License | -|-----------|---------| -| Base License | MIT | -| Overlay | Palimpsest v0.8 | -| License Files | `LICENSE-MIT.txt`, `LICENSE-PALIMPSEST.txt` | - -## Palimpsest Requirements - -### Attribution - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Original author credited | ✅ Pass | Jonathan D. A. Jewell | -| Contribution history preserved | ✅ Pass | Git history maintained | -| License notice in files | ⚠️ Partial | Adding to source files | - -### Provenance - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Origin clearly stated | ✅ Pass | In README and LICENSE | -| Modifications documented | ✅ Pass | CHANGELOG.md | -| Fork lineage tracked | N/A | Original project | - -### Contribution Acknowledgment - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Contributors listed | ✅ Pass | MAINTAINERS.md | -| CONTRIBUTING.md present | ✅ Pass | Guidelines documented | -| DCO/CLA specified | ⚠️ Pending | DCO recommended | - -## Verification Checklist - -- [x] LICENSE-MIT.txt present -- [x] LICENSE-PALIMPSEST.txt present -- [x] LICENSE.txt references both -- [x] README includes license badges -- [x] Source files have headers (in progress) - -## Why Palimpsest? - -The Palimpsest License: -1. **Preserves attribution** - Ensures original creators are credited -2. **Tracks provenance** - Documents where code came from -3. **Remains open source** - Compatible with OSI-approved licenses -4. **Supports collaboration** - Clear contribution guidelines - -## Learn More - -- [Palimpsest License Repository](https://gitlab.com/hyperpolymath/palimpsest-license) -- [Palimpsest FAQ](https://gitlab.com/hyperpolymath/palimpsest-license/-/blob/main/FAQ.md) - ---- - -*Licensed under MIT with Palimpsest v0.8 overlay* diff --git a/aletheia/conformance/README.adoc b/aletheia/conformance/README.adoc new file mode 100644 index 0000000..38a3f06 --- /dev/null +++ b/aletheia/conformance/README.adoc @@ -0,0 +1,88 @@ +== Conformance Reports + +This folder contains conformance reports for Aletheia’s compliance with +various standards and verification systems. + +=== Reports + +[width="100%",cols="29%,27%,44%",options="header",] +|=== +|Report |Status |Description +|RSR-CONFORMANCE.md +|image:https://img.shields.io/badge/RSR-Bronze-cd7f32[Bronze] |Rhodium +Standard Repository compliance +|=== + +image:https://img.shields.io/badge/License-MPL–2.0-blue.svg[License: +PMPL-1.0,link="`https://github.com/hyperpolymath/palimpsest-license`"] | +OIKOS-CONFORMANCE.md | +image:https://img.shields.io/badge/Oikos-Pending-lightgrey[Pending] | +Economic/ecological validation | | ECHIDNA-CONFORMANCE.md | +image:https://img.shields.io/badge/Echidna-Pending-lightgrey[Pending] | +Formal proof verification | + +=== Understanding Badges + +==== RSR (Rhodium Standard Repositories) + +Repository organization and documentation standards. + +[cols=",",options="header",] +|=== +|Level |Meaning +|Bronze |Basic compliance - documentation and structure +|Silver |Enhanced quality - testing and coverage +|Gold |Production ready - multi-platform builds +|Platinum |Enterprise grade - full formal verification +|=== + +==== Palimpsest License + +Overlay license for attribution and provenance. + +[cols=",",options="header",] +|=== +|Status |Meaning +|Active |License properly applied +|Partial |Some requirements pending +|=== + +==== Oikos + +Economic and ecological evaluation. + +[cols=",",options="header",] +|=== +|Level |Meaning +|Pending |Awaiting validation +|Evaluated |Under review +|Validated |Meets sustainability criteria +|Exemplary |Best practices +|=== + +==== Echidna + +Formal proof-based code validation. + +[cols=",",options="header",] +|=== +|Level |Meaning +|Pending |Awaiting verification +|Partial |Some proofs complete +|Verified |Core properties proven +|Certified |Full formal verification +|=== + +=== Learn More + +* link:../docs/VALUE-CHAIN-POLICY.md[Value Chain Policy] - How +conformance fits into project value chain +* link:../ALETHEIA-HANDOVER.md[ALETHEIA-HANDOVER.md] - Project handover +with all badges +* link:../CROSSREPO-HANDOVER.md[CROSSREPO-HANDOVER.md] - Full ecosystem +documentation + +''''' + +_Conformance is verified by automated bots: rhodibot, oikos bot, +echidnabot_ diff --git a/aletheia/conformance/README.md b/aletheia/conformance/README.md deleted file mode 100644 index 2d4aa8d..0000000 --- a/aletheia/conformance/README.md +++ /dev/null @@ -1,70 +0,0 @@ - -# Conformance Reports - -This folder contains conformance reports for Aletheia's compliance with various standards and verification systems. - -## Reports - -| Report | Status | Description | -|--------|--------|-------------| -| [RSR-CONFORMANCE.md](RSR-CONFORMANCE.md) | ![Bronze](https://img.shields.io/badge/RSR-Bronze-cd7f32) | Rhodium Standard Repository compliance | -image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"] -| [OIKOS-CONFORMANCE.md](OIKOS-CONFORMANCE.md) | ![Pending](https://img.shields.io/badge/Oikos-Pending-lightgrey) | Economic/ecological validation | -| [ECHIDNA-CONFORMANCE.md](ECHIDNA-CONFORMANCE.md) | ![Pending](https://img.shields.io/badge/Echidna-Pending-lightgrey) | Formal proof verification | - -## Understanding Badges - -### RSR (Rhodium Standard Repositories) - -Repository organization and documentation standards. - -| Level | Meaning | -|-------|---------| -| Bronze | Basic compliance - documentation and structure | -| Silver | Enhanced quality - testing and coverage | -| Gold | Production ready - multi-platform builds | -| Platinum | Enterprise grade - full formal verification | - -### Palimpsest License - -Overlay license for attribution and provenance. - -| Status | Meaning | -|--------|---------| -| Active | License properly applied | -| Partial | Some requirements pending | - -### Oikos - -Economic and ecological evaluation. - -| Level | Meaning | -|-------|---------| -| Pending | Awaiting validation | -| Evaluated | Under review | -| Validated | Meets sustainability criteria | -| Exemplary | Best practices | - -### Echidna - -Formal proof-based code validation. - -| Level | Meaning | -|-------|---------| -| Pending | Awaiting verification | -| Partial | Some proofs complete | -| Verified | Core properties proven | -| Certified | Full formal verification | - -## Learn More - -- [Value Chain Policy](../docs/VALUE-CHAIN-POLICY.md) - How conformance fits into project value chain -- [ALETHEIA-HANDOVER.md](../ALETHEIA-HANDOVER.md) - Project handover with all badges -- [CROSSREPO-HANDOVER.md](../CROSSREPO-HANDOVER.md) - Full ecosystem documentation - ---- - -*Conformance is verified by automated bots: rhodibot, oikos bot, echidnabot* diff --git a/aletheia/conformance/RSR-CONFORMANCE.adoc b/aletheia/conformance/RSR-CONFORMANCE.adoc new file mode 100644 index 0000000..062e473 --- /dev/null +++ b/aletheia/conformance/RSR-CONFORMANCE.adoc @@ -0,0 +1,107 @@ +== RSR Conformance Report + +https://github.com/hyperpolymath/rhodium-standard-repositories[image:https://img.shields.io/badge/RSR-Bronze-cd7f32[RSR +Bronze]] + +*Project*: Aletheia *Date*: 2025-12-26 *Level*: Bronze *Status*: +Compliant + +=== Overview + +This document records Aletheia’s conformance to the +https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories (RSR)] specification. + +=== RSR Levels + +[width="100%",cols="27%,25%,48%",options="header",] +|=== +|Level |Badge |Description +|Bronze |image:https://img.shields.io/badge/RSR-Bronze-cd7f32[Bronze] +|Basic compliance + +|Silver |image:https://img.shields.io/badge/RSR-Silver-c0c0c0[Silver] +|Enhanced quality + +|Gold |image:https://img.shields.io/badge/RSR-Gold-ffd700[Gold] +|Production ready + +|Platinum +|image:https://img.shields.io/badge/RSR-Platinum-e5e4e2[Platinum] +|Enterprise grade +|=== + +=== Bronze Requirements + +==== Documentation + +[cols=",,",options="header",] +|=== +|Requirement |Status |Notes +|README.md/README.adoc |✅ Pass |README.adoc present +|LICENSE.txt |✅ Pass |Dual MIT + Palimpsest +|SECURITY.md |✅ Pass |Security policy defined +|CONTRIBUTING.md |✅ Pass |Contribution guidelines +|CODE_OF_CONDUCT.md |✅ Pass |Community standards +|MAINTAINERS.md |✅ Pass |Governance documented +|CHANGELOG.md |✅ Pass |Version history +|=== + +==== .well-known Directory + +[cols=",,",options="header",] +|=== +|File |Status |Notes +|security.txt |✅ Pass |RFC 9116 compliant +|ai.txt |✅ Pass |AI training policies +|humans.txt |✅ Pass |Human attribution +|=== + +==== Build System + +[cols=",,",options="header",] +|=== +|Requirement |Status |Notes +|Justfile |✅ Pass |Task automation +|flake.nix |✅ Pass |Reproducible builds +|CI/CD config |✅ Pass |.gitlab-ci.yml +|=== + +==== Source Structure + +[cols=",,",options="header",] +|=== +|Requirement |Status |Notes +|src/ directory |✅ Pass |Source code present +|tests/ directory |⚠️ Pending |Tests to be added +|=== + +=== Silver Requirements (Future) + +[cols=",",options="header",] +|=== +|Requirement |Status +|Property-based tests |⏳ Not started +|Coverage threshold |⏳ Not started +|Mutation testing |⏳ Not started +|Formal verification hooks |⏳ Not started +|=== + +=== Verification + +This conformance was verified by: - *Tool*: rhodibot v0.1.0 - *Date*: +2025-12-26 - *Method*: Automated scan + +=== Learn More + +* https://github.com/hyperpolymath/rhodium-standard-repositories[RSR +Specification] +* link:../extraction/rhodibot/README.md[rhodibot Documentation] +* link:../extraction/rhodium-pipeline/README.md[rhodium-pipeline +Documentation] + +''''' + +_Part of the +https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard] ecosystem_ diff --git a/aletheia/conformance/RSR-CONFORMANCE.md b/aletheia/conformance/RSR-CONFORMANCE.md deleted file mode 100644 index 7a41966..0000000 --- a/aletheia/conformance/RSR-CONFORMANCE.md +++ /dev/null @@ -1,88 +0,0 @@ - -# RSR Conformance Report - -[![RSR Bronze](https://img.shields.io/badge/RSR-Bronze-cd7f32)](https://github.com/hyperpolymath/rhodium-standard-repositories) - -**Project**: Aletheia -**Date**: 2025-12-26 -**Level**: Bronze -**Status**: Compliant - -## Overview - -This document records Aletheia's conformance to the [Rhodium Standard Repositories (RSR)](https://github.com/hyperpolymath/rhodium-standard-repositories) specification. - -## RSR Levels - -| Level | Badge | Description | -|-------|-------|-------------| -| Bronze | ![Bronze](https://img.shields.io/badge/RSR-Bronze-cd7f32) | Basic compliance | -| Silver | ![Silver](https://img.shields.io/badge/RSR-Silver-c0c0c0) | Enhanced quality | -| Gold | ![Gold](https://img.shields.io/badge/RSR-Gold-ffd700) | Production ready | -| Platinum | ![Platinum](https://img.shields.io/badge/RSR-Platinum-e5e4e2) | Enterprise grade | - -## Bronze Requirements - -### Documentation - -| Requirement | Status | Notes | -|-------------|--------|-------| -| README.md/README.adoc | ✅ Pass | README.adoc present | -| LICENSE.txt | ✅ Pass | Dual MIT + Palimpsest | -| SECURITY.md | ✅ Pass | Security policy defined | -| CONTRIBUTING.md | ✅ Pass | Contribution guidelines | -| CODE_OF_CONDUCT.md | ✅ Pass | Community standards | -| MAINTAINERS.md | ✅ Pass | Governance documented | -| CHANGELOG.md | ✅ Pass | Version history | - -### .well-known Directory - -| File | Status | Notes | -|------|--------|-------| -| security.txt | ✅ Pass | RFC 9116 compliant | -| ai.txt | ✅ Pass | AI training policies | -| humans.txt | ✅ Pass | Human attribution | - -### Build System - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Justfile | ✅ Pass | Task automation | -| flake.nix | ✅ Pass | Reproducible builds | -| CI/CD config | ✅ Pass | .gitlab-ci.yml | - -### Source Structure - -| Requirement | Status | Notes | -|-------------|--------|-------| -| src/ directory | ✅ Pass | Source code present | -| tests/ directory | ⚠️ Pending | Tests to be added | - -## Silver Requirements (Future) - -| Requirement | Status | -|-------------|--------| -| Property-based tests | ⏳ Not started | -| Coverage threshold | ⏳ Not started | -| Mutation testing | ⏳ Not started | -| Formal verification hooks | ⏳ Not started | - -## Verification - -This conformance was verified by: -- **Tool**: rhodibot v0.1.0 -- **Date**: 2025-12-26 -- **Method**: Automated scan - -## Learn More - -- [RSR Specification](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [rhodibot Documentation](../extraction/rhodibot/README.md) -- [rhodium-pipeline Documentation](../extraction/rhodium-pipeline/README.md) - ---- - -*Part of the [Rhodium Standard](https://github.com/hyperpolymath/rhodium-standard-repositories) ecosystem* diff --git a/aletheia/docs/ARCHITECTURE.adoc b/aletheia/docs/ARCHITECTURE.adoc new file mode 100644 index 0000000..cd62465 --- /dev/null +++ b/aletheia/docs/ARCHITECTURE.adoc @@ -0,0 +1,410 @@ +== Aletheia Architecture + +=== Overview + +Aletheia is designed as a *simple, auditable, single-file tool* for RSR +compliance verification. This document explains the architectural +decisions and design principles. + +=== Design Principles + +==== 1. Simplicity Over Complexity + +*Decision*: Single-file implementation (~300 lines) + +*Rationale*: - Easy to audit - one file to review - Minimal cognitive +overhead - Clear code flow without jumping between modules - Reduces +attack surface + +*Trade-offs*: - Limited to ~1000 lines before needing modularization - +All code must be general-purpose (no domain-specific modules) + +==== 2. Zero Dependencies + +*Decision*: Only use Rust standard library + +*Rationale*: - No supply chain attacks - Easy security review - Faster +compilation - Long-term stability - Works offline + +*Trade-offs*: - Must implement features from scratch - Cannot use +ecosystem tools (clap, serde, etc.) - More code to maintain + +==== 3. Type Safety First + +*Decision*: Leverage Rust’s type system maximally + +*Rationale*: - Compile-time correctness guarantees - Self-documenting +code - Prevents entire classes of bugs - No runtime type errors + +*Implementation*: + +[source,rust] +---- +enum ComplianceLevel { + Bronze, + Silver, + Gold, + Platinum, +} + +struct CheckResult { + category: String, + item: String, + passed: bool, + required_for: ComplianceLevel, +} +---- + +==== 4. Offline-First + +*Decision*: No network access whatsoever + +*Rationale*: - Works air-gapped - Cannot exfiltrate data - No privacy +concerns - Faster execution - More reliable + +*Implementation*: - All checks are filesystem-based - No `+std::net+` +usage - No external API calls + +==== 5. Explicit Error Handling + +*Decision*: No panics, all errors handled explicitly + +*Rationale*: - Predictable behavior - Graceful degradation - Clear error +messages - No crashes on invalid input + +*Implementation*: + +[source,rust] +---- +let repo_path = if args.len() > 1 { + PathBuf::from(&args[1]) +} else { + std::env::current_dir().unwrap_or_else(|_| { + eprintln!("Error: Cannot determine current directory"); + process::exit(1); + }) +}; +---- + +=== Code Structure + +==== Module Organization + +.... +src/main.rs +├── Type Definitions +│ ├── ComplianceLevel (enum) +│ ├── CheckResult (struct) +│ └── ComplianceReport (struct) +│ +├── Core Verification Functions +│ ├── file_exists() +│ ├── dir_exists() +│ ├── check_documentation() +│ ├── check_well_known() +│ ├── check_build_system() +│ ├── check_source_structure() +│ └── verify_repository() +│ +├── Reporting +│ └── print_report() +│ +├── Entry Point +│ └── main() +│ +└── Tests + └── #[cfg(test)] mod tests +.... + +==== Data Flow + +.... +Command Line Args + ↓ + Parse Path + ↓ +Verify Repository + ↓ + ┌─────────────┐ + │ Create │ + │ Report │ + └─────────────┘ + ↓ + ┌─────────────┐ + │ Check │ + │ Documentation │ + └─────────────┘ + ↓ + ┌─────────────┐ + │ Check │ + │ Well-Known │ + └─────────────┘ + ↓ + ┌─────────────┐ + │ Check │ + │ Build System│ + └─────────────┘ + ↓ + ┌─────────────┐ + │ Check │ + │ Source │ + └─────────────┘ + ↓ + Print Report + ↓ + Exit Code +.... + +=== Key Components + +==== ComplianceReport + +*Purpose*: Accumulate all check results + +*Design*: + +[source,rust] +---- +struct ComplianceReport { + checks: Vec, + repository_path: PathBuf, +} +---- + +*Methods*: - `+new()+` - Create empty report - `+add_check()+` - Add a +check result - `+bronze_compliance()+` - Check if all Bronze +requirements pass - `+passed_count()+` - Count passing checks - +`+total_count()+` - Count total checks + +==== Check Functions + +*Pattern*: All check functions follow the same signature + +[source,rust] +---- +fn check_category(report: &mut ComplianceReport, repo_path: &Path) { + // Perform checks + // Add results to report +} +---- + +*Benefits*: - Consistent interface - Easy to add new checks - Clear +separation of concerns + +==== Verification Flow + +*Strategy*: Sequential checks with accumulation + +[arabic] +. Create empty report +. Run each check function +. Each function adds results to report +. Return completed report + +*Benefits*: - All checks run (don’t stop on first failure) - Complete +picture of compliance status - Easy to parallelize in future (if needed) + +=== Security Architecture + +==== Threat Model + +*In Scope*: - Malicious repository contents - Path traversal attacks - +Resource exhaustion - Information disclosure + +*Out of Scope*: - Physical access attacks - Compromised OS/kernel - +Side-channel attacks - Social engineering + +==== Security Measures + +[arabic] +. *Input Validation* ++ +[source,rust] +---- +if !repo_path.exists() { + eprintln!("Error: Path does not exist"); + process::exit(1); +} +---- +. *No Unsafe Code* +* Zero `+unsafe+` blocks +* All code memory-safe by construction +. *No Dependencies* +* No supply chain vulnerabilities +* No transitive dependencies +. *Offline Operation* +* Cannot exfiltrate data +* No network attack surface + +==== Known Limitations + +[arabic] +. *Symbolic Links*: Follows symlinks (potential path traversal) +. *Large Files*: Could consume excessive memory +. *TOCTOU*: Time-of-check-time-of-use races between existence checks and +reads + +=== Performance Characteristics + +==== Time Complexity + +* *File Checks*: O(n) where n = number of required files +* *Directory Checks*: O(1) per directory +* *Overall*: O(n) where n = total checks (~20 checks) + +==== Space Complexity + +* *Report Storage*: O(n) where n = number of checks +* *Stack Usage*: Minimal (no recursion) +* *Heap Usage*: Small (only storing check results) + +==== Typical Performance + +* *Small repos*: <10ms +* *Large repos*: <50ms +* *Bottleneck*: Filesystem I/O (stat calls) + +=== Extensibility + +==== Adding New Checks + +[arabic] +. Create check function: ++ +[source,rust] +---- +fn check_new_category(report: &mut ComplianceReport, repo_path: &Path) { + let passes = /* check logic */; + report.add_check("Category", "Item", passes, ComplianceLevel::Bronze); +} +---- +. Call from `+verify_repository()+`: ++ +[source,rust] +---- +check_new_category(&mut report, repo_path); +---- +. Add tests: ++ +[source,rust] +---- +#[test] +fn test_new_category_check() { /* ... */ } +---- + +==== Supporting New Compliance Levels + +Currently: Bronze only + +*To add Silver/Gold/Platinum*: + +[arabic] +. Add checks with appropriate `+ComplianceLevel+` enum value +. Add level-specific verification methods to `+ComplianceReport+` +. Update output to show multi-level status + +==== Future Modularization (>1000 lines) + +*Suggested structure*: + +.... +src/ +├── main.rs # Entry point +├── types.rs # Type definitions +├── checks/ +│ ├── mod.rs # Check functions +│ ├── docs.rs # Documentation checks +│ ├── security.rs # Security checks +│ └── build.rs # Build system checks +└── report.rs # Reporting +.... + +=== Testing Strategy + +==== Unit Tests + +Test individual functions: + +[source,rust] +---- +#[test] +fn test_file_exists() { + // Test file existence checking +} +---- + +==== Integration Tests (Future) + +Test complete workflows: + +[source,rust] +---- +#[test] +fn test_complete_verification() { + // Test end-to-end verification +} +---- + +==== Manual Testing + +Test on real repositories: - RSR-compliant repos (should pass) - +Non-compliant repos (should fail) - Edge cases (empty dirs, symlinks, +etc.) + +=== Build System + +==== Justfile + +*Purpose*: Common development tasks + +*Key Recipes*: - `+build+` - Compile project - `+test+` - Run tests - +`+check+` - Run all quality checks - `+validate+` - Self-verification + +==== Nix Flake + +*Purpose*: Reproducible builds + +*Benefits*: - Exact dependency versions - Cross-platform consistency - +Isolated build environment + +==== GitLab CI + +*Purpose*: Automated testing + +*Stages*: 1. Check (format, clippy, dependencies, unsafe code) 2. Test +(unit, release, doc tests) 3. Build (debug, release, musl) 4. Verify +(RSR compliance, docs, build system) 5. Deploy (releases, pages) + +=== Maintenance Philosophy + +==== Stability Over Features + +* Keep core simple +* Avoid feature creep +* Maintain zero dependencies +* Preserve auditability + +==== Backwards Compatibility + +* Follow semantic versioning +* Maintain API stability +* Document breaking changes + +==== Evolution Strategy + +[arabic] +. *Bronze* (current): Foundation +. *Silver*: Add verification without breaking Bronze +. *Gold*: Multi-language support +. *Platinum*: Enterprise features + +=== References + +* link:RSR-SPECIFICATION.md[RSR Specification] +* https://rust-lang.github.io/api-guidelines/[Rust API Guidelines] +* https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html[Clean +Architecture] + +''''' + +*Last Updated*: 2025-11-22 *Version*: 1.0 diff --git a/aletheia/docs/ARCHITECTURE.md b/aletheia/docs/ARCHITECTURE.md deleted file mode 100644 index f36f49f..0000000 --- a/aletheia/docs/ARCHITECTURE.md +++ /dev/null @@ -1,431 +0,0 @@ - -# Aletheia Architecture - -## Overview - -Aletheia is designed as a **simple, auditable, single-file tool** for RSR compliance verification. This document explains the architectural decisions and design principles. - -## Design Principles - -### 1. Simplicity Over Complexity - -**Decision**: Single-file implementation (~300 lines) - -**Rationale**: -- Easy to audit - one file to review -- Minimal cognitive overhead -- Clear code flow without jumping between modules -- Reduces attack surface - -**Trade-offs**: -- Limited to ~1000 lines before needing modularization -- All code must be general-purpose (no domain-specific modules) - -### 2. Zero Dependencies - -**Decision**: Only use Rust standard library - -**Rationale**: -- No supply chain attacks -- Easy security review -- Faster compilation -- Long-term stability -- Works offline - -**Trade-offs**: -- Must implement features from scratch -- Cannot use ecosystem tools (clap, serde, etc.) -- More code to maintain - -### 3. Type Safety First - -**Decision**: Leverage Rust's type system maximally - -**Rationale**: -- Compile-time correctness guarantees -- Self-documenting code -- Prevents entire classes of bugs -- No runtime type errors - -**Implementation**: -```rust -enum ComplianceLevel { - Bronze, - Silver, - Gold, - Platinum, -} - -struct CheckResult { - category: String, - item: String, - passed: bool, - required_for: ComplianceLevel, -} -``` - -### 4. Offline-First - -**Decision**: No network access whatsoever - -**Rationale**: -- Works air-gapped -- Cannot exfiltrate data -- No privacy concerns -- Faster execution -- More reliable - -**Implementation**: -- All checks are filesystem-based -- No `std::net` usage -- No external API calls - -### 5. Explicit Error Handling - -**Decision**: No panics, all errors handled explicitly - -**Rationale**: -- Predictable behavior -- Graceful degradation -- Clear error messages -- No crashes on invalid input - -**Implementation**: -```rust -let repo_path = if args.len() > 1 { - PathBuf::from(&args[1]) -} else { - std::env::current_dir().unwrap_or_else(|_| { - eprintln!("Error: Cannot determine current directory"); - process::exit(1); - }) -}; -``` - -## Code Structure - -### Module Organization - -``` -src/main.rs -├── Type Definitions -│ ├── ComplianceLevel (enum) -│ ├── CheckResult (struct) -│ └── ComplianceReport (struct) -│ -├── Core Verification Functions -│ ├── file_exists() -│ ├── dir_exists() -│ ├── check_documentation() -│ ├── check_well_known() -│ ├── check_build_system() -│ ├── check_source_structure() -│ └── verify_repository() -│ -├── Reporting -│ └── print_report() -│ -├── Entry Point -│ └── main() -│ -└── Tests - └── #[cfg(test)] mod tests -``` - -### Data Flow - -``` -Command Line Args - ↓ - Parse Path - ↓ -Verify Repository - ↓ - ┌─────────────┐ - │ Create │ - │ Report │ - └─────────────┘ - ↓ - ┌─────────────┐ - │ Check │ - │ Documentation │ - └─────────────┘ - ↓ - ┌─────────────┐ - │ Check │ - │ Well-Known │ - └─────────────┘ - ↓ - ┌─────────────┐ - │ Check │ - │ Build System│ - └─────────────┘ - ↓ - ┌─────────────┐ - │ Check │ - │ Source │ - └─────────────┘ - ↓ - Print Report - ↓ - Exit Code -``` - -## Key Components - -### ComplianceReport - -**Purpose**: Accumulate all check results - -**Design**: -```rust -struct ComplianceReport { - checks: Vec, - repository_path: PathBuf, -} -``` - -**Methods**: -- `new()` - Create empty report -- `add_check()` - Add a check result -- `bronze_compliance()` - Check if all Bronze requirements pass -- `passed_count()` - Count passing checks -- `total_count()` - Count total checks - -### Check Functions - -**Pattern**: All check functions follow the same signature -```rust -fn check_category(report: &mut ComplianceReport, repo_path: &Path) { - // Perform checks - // Add results to report -} -``` - -**Benefits**: -- Consistent interface -- Easy to add new checks -- Clear separation of concerns - -### Verification Flow - -**Strategy**: Sequential checks with accumulation - -1. Create empty report -2. Run each check function -3. Each function adds results to report -4. Return completed report - -**Benefits**: -- All checks run (don't stop on first failure) -- Complete picture of compliance status -- Easy to parallelize in future (if needed) - -## Security Architecture - -### Threat Model - -**In Scope**: -- Malicious repository contents -- Path traversal attacks -- Resource exhaustion -- Information disclosure - -**Out of Scope**: -- Physical access attacks -- Compromised OS/kernel -- Side-channel attacks -- Social engineering - -### Security Measures - -1. **Input Validation** - ```rust - if !repo_path.exists() { - eprintln!("Error: Path does not exist"); - process::exit(1); - } - ``` - -2. **No Unsafe Code** - - Zero `unsafe` blocks - - All code memory-safe by construction - -3. **No Dependencies** - - No supply chain vulnerabilities - - No transitive dependencies - -4. **Offline Operation** - - Cannot exfiltrate data - - No network attack surface - -### Known Limitations - -1. **Symbolic Links**: Follows symlinks (potential path traversal) -2. **Large Files**: Could consume excessive memory -3. **TOCTOU**: Time-of-check-time-of-use races between existence checks and reads - -## Performance Characteristics - -### Time Complexity - -- **File Checks**: O(n) where n = number of required files -- **Directory Checks**: O(1) per directory -- **Overall**: O(n) where n = total checks (~20 checks) - -### Space Complexity - -- **Report Storage**: O(n) where n = number of checks -- **Stack Usage**: Minimal (no recursion) -- **Heap Usage**: Small (only storing check results) - -### Typical Performance - -- **Small repos**: <10ms -- **Large repos**: <50ms -- **Bottleneck**: Filesystem I/O (stat calls) - -## Extensibility - -### Adding New Checks - -1. Create check function: - ```rust - fn check_new_category(report: &mut ComplianceReport, repo_path: &Path) { - let passes = /* check logic */; - report.add_check("Category", "Item", passes, ComplianceLevel::Bronze); - } - ``` - -2. Call from `verify_repository()`: - ```rust - check_new_category(&mut report, repo_path); - ``` - -3. Add tests: - ```rust - #[test] - fn test_new_category_check() { /* ... */ } - ``` - -### Supporting New Compliance Levels - -Currently: Bronze only - -**To add Silver/Gold/Platinum**: - -1. Add checks with appropriate `ComplianceLevel` enum value -2. Add level-specific verification methods to `ComplianceReport` -3. Update output to show multi-level status - -### Future Modularization (>1000 lines) - -**Suggested structure**: -``` -src/ -├── main.rs # Entry point -├── types.rs # Type definitions -├── checks/ -│ ├── mod.rs # Check functions -│ ├── docs.rs # Documentation checks -│ ├── security.rs # Security checks -│ └── build.rs # Build system checks -└── report.rs # Reporting -``` - -## Testing Strategy - -### Unit Tests - -Test individual functions: -```rust -#[test] -fn test_file_exists() { - // Test file existence checking -} -``` - -### Integration Tests (Future) - -Test complete workflows: -```rust -#[test] -fn test_complete_verification() { - // Test end-to-end verification -} -``` - -### Manual Testing - -Test on real repositories: -- RSR-compliant repos (should pass) -- Non-compliant repos (should fail) -- Edge cases (empty dirs, symlinks, etc.) - -## Build System - -### Justfile - -**Purpose**: Common development tasks - -**Key Recipes**: -- `build` - Compile project -- `test` - Run tests -- `check` - Run all quality checks -- `validate` - Self-verification - -### Nix Flake - -**Purpose**: Reproducible builds - -**Benefits**: -- Exact dependency versions -- Cross-platform consistency -- Isolated build environment - -### GitLab CI - -**Purpose**: Automated testing - -**Stages**: -1. Check (format, clippy, dependencies, unsafe code) -2. Test (unit, release, doc tests) -3. Build (debug, release, musl) -4. Verify (RSR compliance, docs, build system) -5. Deploy (releases, pages) - -## Maintenance Philosophy - -### Stability Over Features - -- Keep core simple -- Avoid feature creep -- Maintain zero dependencies -- Preserve auditability - -### Backwards Compatibility - -- Follow semantic versioning -- Maintain API stability -- Document breaking changes - -### Evolution Strategy - -1. **Bronze** (current): Foundation -2. **Silver**: Add verification without breaking Bronze -3. **Gold**: Multi-language support -4. **Platinum**: Enterprise features - -## References - -- [RSR Specification](RSR-SPECIFICATION.md) -- [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/) -- [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) - ---- - -**Last Updated**: 2025-11-22 -**Version**: 1.0 diff --git a/aletheia/docs/BADGES.md b/aletheia/docs/BADGES.adoc similarity index 50% rename from aletheia/docs/BADGES.md rename to aletheia/docs/BADGES.adoc index c833b6d..286f6b0 100644 --- a/aletheia/docs/BADGES.md +++ b/aletheia/docs/BADGES.adoc @@ -1,117 +1,140 @@ - -# RSR Compliance Badges +== RSR Compliance Badges Display your RSR compliance status with badges in your README. -## Available Badges +=== Available Badges -### Bronze Level +==== Bronze Level -**Achieved**: -```markdown -[![RSR Bronze](https://img.shields.io/badge/RSR-Bronze%20Compliant-green?style=flat-square&logo=rust)](https://gitlab.com/maa-framework/6-the-foundation/aletheia) -``` +*Achieved*: +[source,markdown] +---- [![RSR Bronze](https://img.shields.io/badge/RSR-Bronze%20Compliant-green?style=flat-square&logo=rust)](https://gitlab.com/maa-framework/6-the-foundation/aletheia) +---- -**In Progress**: -```markdown -[![RSR Bronze](https://img.shields.io/badge/RSR-Bronze%20In%20Progress-yellow?style=flat-square&logo=rust)](https://gitlab.com/maa-framework/6-the-foundation/aletheia) -``` +https://gitlab.com/maa-framework/6-the-foundation/aletheia[image:https://img.shields.io/badge/RSR-Bronze%20Compliant-green?style=flat-square&logo=rust[RSR +Bronze]] +*In Progress*: + +[source,markdown] +---- [![RSR Bronze](https://img.shields.io/badge/RSR-Bronze%20In%20Progress-yellow?style=flat-square&logo=rust)](https://gitlab.com/maa-framework/6-the-foundation/aletheia) +---- -**Not Compliant**: -```markdown -[![RSR Bronze](https://img.shields.io/badge/RSR-Not%20Compliant-red?style=flat-square&logo=rust)](https://gitlab.com/maa-framework/6-the-foundation/aletheia) -``` +https://gitlab.com/maa-framework/6-the-foundation/aletheia[image:https://img.shields.io/badge/RSR-Bronze%20In%20Progress-yellow?style=flat-square&logo=rust[RSR +Bronze]] +*Not Compliant*: + +[source,markdown] +---- [![RSR Bronze](https://img.shields.io/badge/RSR-Not%20Compliant-red?style=flat-square&logo=rust)](https://gitlab.com/maa-framework/6-the-foundation/aletheia) +---- + +https://gitlab.com/maa-framework/6-the-foundation/aletheia[image:https://img.shields.io/badge/RSR-Not%20Compliant-red?style=flat-square&logo=rust[RSR +Bronze]] -### Silver Level (Future) +==== Silver Level (Future) -```markdown +[source,markdown] +---- [![RSR Silver](https://img.shields.io/badge/RSR-Silver%20Compliant-blue?style=flat-square&logo=rust)](https://gitlab.com/maa-framework/6-the-foundation/aletheia) -``` +---- -### Gold Level (Future) +==== Gold Level (Future) -```markdown +[source,markdown] +---- [![RSR Gold](https://img.shields.io/badge/RSR-Gold%20Compliant-gold?style=flat-square&logo=rust)](https://gitlab.com/maa-framework/6-the-foundation/aletheia) -``` +---- -### Platinum Level (Future) +==== Platinum Level (Future) -```markdown +[source,markdown] +---- [![RSR Platinum](https://img.shields.io/badge/RSR-Platinum%20Compliant-platinum?style=flat-square&logo=rust)](https://gitlab.com/maa-framework/6-the-foundation/aletheia) -``` +---- -## Dynamic Badges (Future Feature) +=== Dynamic Badges (Future Feature) -In the future, Aletheia may support dynamic badges that automatically update: +In the future, Aletheia may support dynamic badges that automatically +update: -```markdown +[source,markdown] +---- [![RSR Compliance](https://rsr-badges.example.com/compliance/owner/repo)](https://gitlab.com/owner/repo) -``` +---- + +This would: 1. Run Aletheia verification 2. Generate badge with current +status 3. Update automatically on push -This would: -1. Run Aletheia verification -2. Generate badge with current status -3. Update automatically on push +=== Badge Styles -## Badge Styles +==== Flat Square (Recommended) -### Flat Square (Recommended) -```markdown +[source,markdown] +---- ![RSR](https://img.shields.io/badge/RSR-Bronze-green?style=flat-square) -``` +---- -### Flat -```markdown +==== Flat + +[source,markdown] +---- ![RSR](https://img.shields.io/badge/RSR-Bronze-green?style=flat) -``` +---- + +==== Plastic -### Plastic -```markdown +[source,markdown] +---- ![RSR](https://img.shields.io/badge/RSR-Bronze-green?style=plastic) -``` +---- -### For the Badge -```markdown +==== For the Badge + +[source,markdown] +---- ![RSR](https://img.shields.io/badge/RSR-Bronze-green?style=for-the-badge) -``` +---- + +==== Social -### Social -```markdown +[source,markdown] +---- ![RSR](https://img.shields.io/badge/RSR-Bronze-green?style=social) -``` +---- -## Badge Verification +=== Badge Verification Users can verify your badge claim by: -1. **Clone repository**: - ```bash - git clone https://your-repo-url.git - cd your-repo - ``` - -2. **Run Aletheia**: - ```bash - aletheia . - ``` - -3. **Check output**: - ``` - 🏆 Bronze-level RSR compliance: ACHIEVED - ``` +[arabic] +. *Clone repository*: ++ +[source,bash] +---- +git clone https://your-repo-url.git +cd your-repo +---- +. *Run Aletheia*: ++ +[source,bash] +---- +aletheia . +---- +. *Check output*: ++ +.... +🏆 Bronze-level RSR compliance: ACHIEVED +.... -## README Example +=== README Example -```markdown +[source,markdown] +---- # My Amazing Project [![RSR Bronze](https://img.shields.io/badge/RSR-Bronze%20Compliant-green?style=flat-square&logo=rust)](https://gitlab.com/maa-framework/6-the-foundation/aletheia) @@ -143,27 +166,29 @@ cargo install my-project ## License Code is under MPL-2.0 and docs are under CC-BY-SA-4.0. -``` +---- -## Custom Badges +=== Custom Badges You can create custom badges with specific scores: -```markdown +[source,markdown] +---- ![RSR](https://img.shields.io/badge/RSR-16%2F16%20Checks-green) ![RSR](https://img.shields.io/badge/RSR-87.5%25%20Compliant-yellow) -``` +---- -## Badge in CI/CD +=== Badge in CI/CD Generate badge URL based on CI results: -### GitLab CI +==== GitLab CI -```yaml +[source,yaml] +---- # .gitlab-ci.yml rsr-verify: script: @@ -178,57 +203,51 @@ rsr-verify: artifacts: reports: dotenv: build.env -``` +---- -## Badge Guidelines +=== Badge Guidelines -### Do's ✅ +==== Do’s ✅ -- ✅ Update badge when compliance changes -- ✅ Link badge to Aletheia repo or RSR docs -- ✅ Keep badge current with latest verification -- ✅ Use appropriate color (green/yellow/red) +* ✅ Update badge when compliance changes +* ✅ Link badge to Aletheia repo or RSR docs +* ✅ Keep badge current with latest verification +* ✅ Use appropriate color (green/yellow/red) -### Don'ts ❌ +==== Don’ts ❌ -- ❌ Don't claim compliance without verification -- ❌ Don't use outdated badge status -- ❌ Don't modify badge colors misleadingly -- ❌ Don't use higher-level badges prematurely +* ❌ Don’t claim compliance without verification +* ❌ Don’t use outdated badge status +* ❌ Don’t modify badge colors misleadingly +* ❌ Don’t use higher-level badges prematurely -## Verification Required +=== Verification Required To use a compliance badge: -1. **Run Aletheia**: `aletheia .` -2. **Verify output**: Ensure 16/16 checks pass -3. **Add badge**: Use appropriate badge code -4. **Keep updated**: Re-verify after changes +[arabic] +. *Run Aletheia*: `+aletheia .+` +. *Verify output*: Ensure 16/16 checks pass +. *Add badge*: Use appropriate badge code +. *Keep updated*: Re-verify after changes -## Badge Hosting +=== Badge Hosting -Badges use shields.io service: -- **Service**: https://shields.io -- **Format**: `https://img.shields.io/badge/{subject}-{status}-{color}` -- **Customization**: See https://shields.io for options +Badges use shields.io service: - *Service*: https://shields.io - +*Format*: `+https://img.shields.io/badge/{subject}-{status}-{color}+` - +*Customization*: See https://shields.io for options -## Future: Automated Badge Service +=== Future: Automated Badge Service -Planned features: -- Real-time verification API -- Automatic badge generation -- Webhook integration -- Historical compliance tracking -- Multi-repo dashboards +Planned features: - Real-time verification API - Automatic badge +generation - Webhook integration - Historical compliance tracking - +Multi-repo dashboards -## Contributing +=== Contributing -Help improve RSR badges: -- Suggest new badge designs -- Propose dynamic badge service -- Contribute to Aletheia -- Share badge usage examples +Help improve RSR badges: - Suggest new badge designs - Propose dynamic +badge service - Contribute to Aletheia - Share badge usage examples ---- +''''' -**Displaying your RSR compliance shows commitment to quality!** +*Displaying your RSR compliance shows commitment to quality!* diff --git a/aletheia/docs/DEPLOYMENT.md b/aletheia/docs/DEPLOYMENT.adoc similarity index 75% rename from aletheia/docs/DEPLOYMENT.md rename to aletheia/docs/DEPLOYMENT.adoc index 40224de..118ee0a 100644 --- a/aletheia/docs/DEPLOYMENT.md +++ b/aletheia/docs/DEPLOYMENT.adoc @@ -1,25 +1,24 @@ - -# Deployment Guide +== Deployment Guide -This document describes various ways to deploy and use Aletheia in different environments. +This document describes various ways to deploy and use Aletheia in +different environments. -## Table of Contents +=== Table of Contents -1. [Local Installation](#local-installation) -2. [Docker Deployment](#docker-deployment) -3. [CI/CD Integration](#cicd-integration) -4. [System-Wide Installation](#system-wide-installation) -5. [Cloud Deployment](#cloud-deployment) -6. [Air-Gapped Environments](#air-gapped-environments) +[arabic] +. link:#local-installation[Local Installation] +. link:#docker-deployment[Docker Deployment] +. link:#cicd-integration[CI/CD Integration] +. link:#system-wide-installation[System-Wide Installation] +. link:#cloud-deployment[Cloud Deployment] +. link:#air-gapped-environments[Air-Gapped Environments] -## Local Installation +=== Local Installation -### Quick Install (Recommended) +==== Quick Install (Recommended) -```bash +[source,bash] +---- # Using the install script curl -sSf https://gitlab.com/maa-framework/6-the-foundation/aletheia/-/raw/main/scripts/install.sh | bash @@ -27,11 +26,12 @@ curl -sSf https://gitlab.com/maa-framework/6-the-foundation/aletheia/-/raw/main/ curl -O https://gitlab.com/maa-framework/6-the-foundation/aletheia/-/raw/main/scripts/install.sh chmod +x install.sh ./install.sh -``` +---- -### Manual Build +==== Manual Build -```bash +[source,bash] +---- # Clone repository git clone https://gitlab.com/maa-framework/6-the-foundation/aletheia.git cd aletheia @@ -42,33 +42,36 @@ cargo build --release # Binary is at: target/release/aletheia # Copy to PATH location: cp target/release/aletheia ~/.local/bin/ -``` +---- -### Using Cargo Install +==== Using Cargo Install -```bash +[source,bash] +---- # Install directly from Git cargo install --git https://gitlab.com/maa-framework/6-the-foundation/aletheia.git # Or from crates.io (when published) cargo install aletheia -``` +---- -## Docker Deployment +=== Docker Deployment -### Build Docker Image +==== Build Docker Image -```bash +[source,bash] +---- # Build the image docker build -t aletheia:0.1.0 . # Or build with specific target docker build -t aletheia:latest --target=runtime . -``` +---- -### Run with Docker +==== Run with Docker -```bash +[source,bash] +---- # Verify current directory docker run -v $(pwd):/repo aletheia:0.1.0 @@ -77,11 +80,12 @@ docker run -v /path/to/repo:/repo aletheia:0.1.0 # Save results to file docker run -v $(pwd):/repo aletheia:0.1.0 > report.txt -``` +---- -### Docker Compose +==== Docker Compose -```yaml +[source,yaml] +---- # docker-compose.yml version: '3.8' @@ -91,16 +95,18 @@ services: volumes: - ./:/repo:ro command: ["/repo"] -``` +---- -```bash +[source,bash] +---- # Run with docker-compose docker-compose run aletheia -``` +---- -### Multi-Repository Verification +==== Multi-Repository Verification -```bash +[source,bash] +---- # Script to verify multiple repositories #!/bin/bash for repo in /path/to/repos/*; do @@ -108,15 +114,16 @@ for repo in /path/to/repos/*; do docker run -v "$repo:/repo" aletheia:0.1.0 echo "---" done -``` +---- -## CI/CD Integration +=== CI/CD Integration -### GitLab CI +==== GitLab CI -#### Simple Integration +===== Simple Integration -```yaml +[source,yaml] +---- # .gitlab-ci.yml rsr-compliance: stage: test @@ -126,11 +133,12 @@ rsr-compliance: script: - aletheia allow_failure: false -``` +---- -#### With Caching +===== With Caching -```yaml +[source,yaml] +---- # .gitlab-ci.yml variables: CARGO_HOME: $CI_PROJECT_DIR/.cargo @@ -149,22 +157,24 @@ rsr-compliance: fi script: - .cargo/bin/aletheia -``` +---- -#### Using Docker +===== Using Docker -```yaml +[source,yaml] +---- # .gitlab-ci.yml rsr-compliance: stage: test image: aletheia:0.1.0 script: - /aletheia . -``` +---- -### GitHub Actions +==== GitHub Actions -```yaml +[source,yaml] +---- # .github/workflows/rsr-compliance.yml name: RSR Compliance @@ -194,11 +204,12 @@ jobs: - name: Verify RSR Compliance run: aletheia -``` +---- -### Jenkins +==== Jenkins -```groovy +[source,groovy] +---- // Jenkinsfile pipeline { agent { @@ -227,11 +238,12 @@ pipeline { } } } -``` +---- -### CircleCI +==== CircleCI -```yaml +[source,yaml] +---- # .circleci/config.yml version: 2.1 @@ -260,13 +272,14 @@ workflows: build: jobs: - rsr-compliance -``` +---- -## System-Wide Installation +=== System-Wide Installation -### Linux (systemd) +==== Linux (systemd) -```bash +[source,bash] +---- # Install binary sudo cp target/release/aletheia /usr/local/bin/ @@ -302,11 +315,12 @@ EOF # Enable and start timer sudo systemctl enable aletheia-check.timer sudo systemctl start aletheia-check.timer -``` +---- -### macOS +==== macOS -```bash +[source,bash] +---- # Install binary cp target/release/aletheia /usr/local/bin/ @@ -336,13 +350,14 @@ EOF # Load LaunchAgent launchctl load ~/Library/LaunchAgents/org.maa-framework.aletheia.plist -``` +---- -## Cloud Deployment +=== Cloud Deployment -### AWS Lambda +==== AWS Lambda -```python +[source,python] +---- # lambda_function.py import subprocess import json @@ -368,11 +383,12 @@ def lambda_handler(event, context): 'error': result.stderr if result.returncode != 0 else None }) } -``` +---- -### Google Cloud Functions +==== Google Cloud Functions -```python +[source,python] +---- # main.py import subprocess from flask import jsonify @@ -395,11 +411,12 @@ def verify_rsr(request): 'output': result.stdout, 'error': result.stderr if result.returncode != 0 else None }) -``` +---- -### Kubernetes +==== Kubernetes -```yaml +[source,yaml] +---- # kubernetes/deployment.yaml apiVersion: batch/v1 kind: CronJob @@ -423,13 +440,14 @@ spec: hostPath: path: /path/to/repositories restartPolicy: OnFailure -``` +---- -## Air-Gapped Environments +=== Air-Gapped Environments -### Offline Installation +==== Offline Installation -```bash +[source,bash] +---- # On a machine with internet access: # 1. Clone repository @@ -454,95 +472,112 @@ tar -czf aletheia-offline.tar.gz \ # On air-gapped machine: tar -xzf aletheia-offline.tar.gz sudo cp aletheia /usr/local/bin/ -``` +---- -### Vendored Dependencies (Zero deps = already done!) +==== Vendored Dependencies (Zero deps = already done!) -```bash +[source,bash] +---- # Aletheia has ZERO dependencies, so it works perfectly in air-gapped environments # No cargo vendor needed! # Just copy the binary: scp target/release/aletheia airgapped-machine:/usr/local/bin/ -``` - -## Best Practices - -### Security - -1. **Verify checksums**: - ```bash - sha256sum aletheia > aletheia.sha256 - sha256sum -c aletheia.sha256 - ``` - -2. **Use specific versions**: - ```bash - # Don't use :latest in production - docker pull aletheia:0.1.0 - ``` - -3. **Run as non-root**: - ```dockerfile - USER nobody:nobody - ``` - -### Performance - -1. **Cache installations**: - - Use Docker layer caching - - Cache cargo installations in CI/CD - -2. **Parallel verification**: - ```bash - find /repos -type d -maxdepth 1 | \ - parallel -j4 'aletheia {}' - ``` - -### Monitoring - -1. **Log results**: - ```bash - aletheia | tee -a /var/log/aletheia.log - ``` - -2. **Alert on failures**: - ```bash - aletheia || notify-send "RSR compliance failed" - ``` - -## Troubleshooting - -### Issue: Binary not found - -```bash +---- + +=== Best Practices + +==== Security + +[arabic] +. *Verify checksums*: ++ +[source,bash] +---- +sha256sum aletheia > aletheia.sha256 +sha256sum -c aletheia.sha256 +---- +. *Use specific versions*: ++ +[source,bash] +---- +# Don't use :latest in production +docker pull aletheia:0.1.0 +---- +. *Run as non-root*: ++ +[source,dockerfile] +---- +USER nobody:nobody +---- + +==== Performance + +[arabic] +. *Cache installations*: +* Use Docker layer caching +* Cache cargo installations in CI/CD +. *Parallel verification*: ++ +[source,bash] +---- +find /repos -type d -maxdepth 1 | \ + parallel -j4 'aletheia {}' +---- + +==== Monitoring + +[arabic] +. *Log results*: ++ +[source,bash] +---- +aletheia | tee -a /var/log/aletheia.log +---- +. *Alert on failures*: ++ +[source,bash] +---- +aletheia || notify-send "RSR compliance failed" +---- + +=== Troubleshooting + +==== Issue: Binary not found + +[source,bash] +---- # Check installation which aletheia # Add to PATH export PATH="$PATH:$HOME/.cargo/bin" -``` +---- -### Issue: Permission denied +==== Issue: Permission denied -```bash +[source,bash] +---- # Make binary executable chmod +x /path/to/aletheia -``` +---- -### Issue: Old version +==== Issue: Old version -```bash +[source,bash] +---- # Force reinstall cargo install --force --git https://gitlab.com/maa-framework/6-the-foundation/aletheia.git -``` +---- -## Support +=== Support -- **Issues**: https://gitlab.com/maa-framework/6-the-foundation/aletheia/-/issues -- **Documentation**: https://gitlab.com/maa-framework/6-the-foundation/aletheia -- **Email**: maintainers@maa-framework.org +* *Issues*: +https://gitlab.com/maa-framework/6-the-foundation/aletheia/-/issues +* *Documentation*: +https://gitlab.com/maa-framework/6-the-foundation/aletheia +* *Email*: maintainers@maa-framework.org ---- +''''' -*Deploy Aletheia everywhere - verify truth everywhere!* +_Deploy Aletheia everywhere - verify truth everywhere!_ diff --git a/aletheia/docs/FAQ.adoc b/aletheia/docs/FAQ.adoc new file mode 100644 index 0000000..62b37d1 --- /dev/null +++ b/aletheia/docs/FAQ.adoc @@ -0,0 +1,348 @@ +== Frequently Asked Questions (FAQ) + +=== General Questions + +==== What is Aletheia? + +Aletheia (Greek: ἀλήθεια - "`truth`", "`disclosure`", "`unconcealment`") +is a zero-dependency Rust tool for verifying Rhodium Standard Repository +(RSR) compliance. It checks repositories against rigorous standards for +security, documentation, and operational excellence. + +==== What is RSR? + +RSR (Rhodium Standard Repository) is a framework defining graduated +standards for software repositories. It covers type safety, memory +safety, security, documentation, build systems, and testing. See +RSR-SPECIFICATION.md for details. + +==== Why "`Aletheia`"? + +"`Aletheia`" is ancient Greek for "`truth`" or "`unconcealment`" - not +merely factual correctness, but the revealing of reality. In software, +this means transparent processes, verifiable standards, and honest +documentation. + +==== Why "`Rhodium`"? + +Rhodium is a rare, valuable, durable precious metal. Like rhodium, +high-quality software repositories are rare, valuable, and built to +last. + +=== Installation & Usage + +==== How do I install Aletheia? + +[source,bash] +---- +# From source (recommended) +git clone https://gitlab.com/maa-framework/6-the-foundation/aletheia.git +cd aletheia +cargo build --release + +# Or install directly +cargo install --git https://gitlab.com/maa-framework/6-the-foundation/aletheia.git +---- + +==== How do I use Aletheia? + +[source,bash] +---- +# Verify current directory +cargo run + +# Verify specific repository +cargo run -- /path/to/repository +---- + +==== What languages does Aletheia support? + +Aletheia is language-agnostic. It checks documentation, structure, and +build systems - not code itself. Works with: - Rust - Python - +JavaScript/TypeScript - Go - Any language with proper documentation + +==== Can I use Aletheia in CI/CD? + +Yes! Aletheia exits with code 0 on success, 1 on failure: + +[source,yaml] +---- +# GitLab CI +rsr-compliance: + script: + - aletheia +---- + +=== Technical Questions + +==== Why zero dependencies? + +Zero dependencies provides: 1. *Security*: No supply chain attacks 2. +*Auditability*: Easy to review entire codebase 3. *Reliability*: No +dependency breakage 4. *Simplicity*: Fewer moving parts 5. *Trust*: +Users can verify everything + +==== Why no unsafe code? + +No unsafe code means: 1. *Safety*: Rust’s guarantees apply everywhere 2. +*Trust*: No hidden memory bugs 3. *Simplicity*: No manual memory +management 4. *Auditability*: No special cases to review + +==== Why offline-first? + +Offline-first ensures: 1. *Privacy*: Cannot exfiltrate data 2. +*Reliability*: Works without internet 3. *Speed*: No network latency 4. +*Security*: No remote code execution 5. *Trust*: Users control all +inputs + +==== How fast is Aletheia? + +Very fast - typically <50ms for most repositories. Bottleneck is +filesystem I/O (stat calls). + +==== How much memory does Aletheia use? + +Minimal - typically <5MB RAM. Only stores check results in memory. + +=== Compliance Questions + +==== What compliance levels exist? + +* *Bronze* (current): Foundation - docs, security, build system +* *Silver* (planned): Formal verification, advanced security +* *Gold* (planned): Multi-language, distributed systems +* *Platinum* (planned): Enterprise, CADRE integration + +==== What does Bronze compliance require? + +Bronze requires: - ✅ 7 documentation files (README, LICENSE, SECURITY, +etc.) - ✅ .well-known directory (security.txt, ai.txt, humans.txt) - ✅ +Build system (Justfile, flake.nix, CI/CD) - ✅ Source structure (src/, +tests/) + +See RSR-SPECIFICATION.md for details. + +==== How do I make my repository compliant? + +[arabic] +. Run `+aletheia+` to see what’s missing +. Create missing files (see examples in Aletheia repo) +. Re-run `+aletheia+` to verify +. See QUICK_START.md for step-by-step guide + +==== Can I skip some requirements? + +No - all Bronze requirements are mandatory. However, you can: - Use +alternative build tools (alongside required ones) - Add additional +documentation - Exceed minimum standards + +==== What if I disagree with a requirement? + +The RSR specification is open for discussion: - Open an issue on the +specification repository - Propose changes via merge request - Join +community discussions + +=== Project Questions + +==== Who maintains Aletheia? + +Aletheia is maintained by the MAA Framework team. See +link:../MAINTAINERS.md[MAINTAINERS.md] for details. + +==== How can I contribute? + +See link:../CONTRIBUTING.md[CONTRIBUTING.md] for contribution +guidelines. We welcome: - Bug reports - Feature requests - Documentation +improvements - Code contributions + +==== What license is Aletheia under? + +Dual-licensed under your choice of: - MIT License - Palimpsest License +v0.8 + +See link:../LICENSE.txt[LICENSE.txt] for details. + +==== Is Aletheia production-ready? + +Yes, for Bronze-level verification. It’s: - Well-tested (100% test pass +rate) - Zero unsafe code - Zero dependencies - Self-verified (Aletheia +verifies itself) + +Silver/Gold/Platinum levels are planned for future releases. + +=== Security Questions + +==== How do I report a vulnerability? + +See link:../SECURITY.md[SECURITY.md] for: - Security contact email - +Confidential issue reporting - Response timeline - Disclosure process + +==== Has Aletheia been audited? + +Not yet. We welcome security audits! The codebase is: - ~300 lines of +Rust - Zero unsafe code - Zero dependencies - Easy to audit + +==== What’s the threat model? + +*In Scope*: - Malicious repository contents - Path traversal attacks - +Resource exhaustion + +*Out of Scope*: - Physical access - Compromised OS/kernel - Side-channel +attacks + +See link:../SECURITY.md[SECURITY.md] for full threat model. + +==== Can Aletheia be tricked? + +Known limitations: 1. Follows symbolic links (potential path traversal) +2. Could consume memory on very large files 3. TOCTOU races between +checks and file reads + +These are documented for transparency but not considered security +vulnerabilities in the current threat model. + +=== Development Questions + +==== Can I use Aletheia as a library? + +Currently, Aletheia is binary-only. Library API may be added in future +versions. + +==== How do I run tests? + +[source,bash] +---- +cargo test # Run all tests +cargo test -- --nocapture # See output +cargo test --release # Test optimized build +---- + +==== How do I build for different platforms? + +[source,bash] +---- +# Linux (glibc) +cargo build --release --target x86_64-unknown-linux-gnu + +# Linux (musl - static binary) +cargo build --release --target x86_64-unknown-linux-musl + +# macOS +cargo build --release --target x86_64-apple-darwin + +# Windows +cargo build --release --target x86_64-pc-windows-gnu +---- + +==== How do I add a new check? + +See link:../CLAUDE.md[CLAUDE.md] for development guide. Basic steps: + +[arabic] +. Add check function +. Call from `+verify_repository()+` +. Add tests +. Update documentation + +=== Philosophy Questions + +==== What is the TPCF? + +TPCF (Tri-Perimeter Contribution Framework) is a graduated trust model: +- *Perimeter 1*: Core maintainers (full access) - *Perimeter 2*: Trusted +contributors (review/merge rights) - *Perimeter 3*: Community sandbox +(open contribution) + +See link:../CODE_OF_CONDUCT.md[CODE_OF_CONDUCT.md] for details. + +==== What is the Palimpsest License? + +The Palimpsest License v0.8 is a permissive license embodying principles +of: - Reversibility (Git makes everything reversible) - Iteration +(constant improvement) - Impermanence (nothing is final) - History +preservation (layers remain visible) + +See link:../LICENSE-PALIMPSEST.txt[LICENSE-PALIMPSEST.txt] for full +text. + +==== Why focus on emotional safety? + +We believe healthy open source requires: - Psychological safety to +experiment - Safe to fail (mistakes are learning) - Safe to dissent +(respectful disagreement) - Reduced anxiety (reversibility helps) + +See link:../CODE_OF_CONDUCT.md[CODE_OF_CONDUCT.md] for our emotional +safety framework. + +=== Roadmap Questions + +==== What’s next for Aletheia? + +Planned features: - *v0.2.0*: Silver-level compliance checks - *v0.3.0*: +Gold-level compliance checks - *v0.4.0*: JSON output format - *v0.5.0*: +Configurable checks - *v1.0.0*: Platinum-level compliance + +==== When will Silver/Gold/Platinum be ready? + +No fixed timeline. We prioritize quality over speed. Follow: - +link:../CHANGELOG.md[CHANGELOG.md] for updates - +https://gitlab.com/maa-framework/6-the-foundation/aletheia/-/issues[Issues] +for progress + +==== Can I request features? + +Yes! Open an issue: - Describe the feature - Explain the use case - +Suggest implementation (optional) + +=== Troubleshooting + +==== Aletheia won’t compile + +Check: + +[source,bash] +---- +rustc --version # Should be 1.75+ +cargo --version +---- + +Update Rust: + +[source,bash] +---- +rustup update +---- + +==== Tests fail + +Run with verbose output: + +[source,bash] +---- +cargo test -- --nocapture +---- + +Check for: - Filesystem permissions - Correct working directory - +Updated Rust version + +==== Self-verification fails + +This shouldn’t happen! If it does: 1. Check which files are missing 2. +Verify you’re in Aletheia directory 3. Open an issue (this is a bug) + +==== CI/CD integration doesn’t work + +Check: - Aletheia installed correctly - Running in repository root - +Exit code checked (0 = success, 1 = failure) + +=== Still Have Questions? + +* *Documentation*: Browse link:.[docs/] directory +* *Issues*: +https://gitlab.com/maa-framework/6-the-foundation/aletheia/-/issues +* *Email*: maintainers@maa-framework.org + +''''' + +_"`The unexamined repository is not worth maintaining.`" - Adapted from +Socrates_ diff --git a/aletheia/docs/FAQ.md b/aletheia/docs/FAQ.md deleted file mode 100644 index 09fd3cf..0000000 --- a/aletheia/docs/FAQ.md +++ /dev/null @@ -1,361 +0,0 @@ - -# Frequently Asked Questions (FAQ) - -## General Questions - -### What is Aletheia? - -Aletheia (Greek: ἀλήθεια - "truth", "disclosure", "unconcealment") is a zero-dependency Rust tool for verifying Rhodium Standard Repository (RSR) compliance. It checks repositories against rigorous standards for security, documentation, and operational excellence. - -### What is RSR? - -RSR (Rhodium Standard Repository) is a framework defining graduated standards for software repositories. It covers type safety, memory safety, security, documentation, build systems, and testing. See [RSR-SPECIFICATION.md](RSR-SPECIFICATION.md) for details. - -### Why "Aletheia"? - -"Aletheia" is ancient Greek for "truth" or "unconcealment" - not merely factual correctness, but the revealing of reality. In software, this means transparent processes, verifiable standards, and honest documentation. - -### Why "Rhodium"? - -Rhodium is a rare, valuable, durable precious metal. Like rhodium, high-quality software repositories are rare, valuable, and built to last. - -## Installation & Usage - -### How do I install Aletheia? - -```bash -# From source (recommended) -git clone https://gitlab.com/maa-framework/6-the-foundation/aletheia.git -cd aletheia -cargo build --release - -# Or install directly -cargo install --git https://gitlab.com/maa-framework/6-the-foundation/aletheia.git -``` - -### How do I use Aletheia? - -```bash -# Verify current directory -cargo run - -# Verify specific repository -cargo run -- /path/to/repository -``` - -### What languages does Aletheia support? - -Aletheia is language-agnostic. It checks documentation, structure, and build systems - not code itself. Works with: -- Rust -- Python -- JavaScript/TypeScript -- Go -- Any language with proper documentation - -### Can I use Aletheia in CI/CD? - -Yes! Aletheia exits with code 0 on success, 1 on failure: - -```yaml -# GitLab CI -rsr-compliance: - script: - - aletheia -``` - -## Technical Questions - -### Why zero dependencies? - -Zero dependencies provides: -1. **Security**: No supply chain attacks -2. **Auditability**: Easy to review entire codebase -3. **Reliability**: No dependency breakage -4. **Simplicity**: Fewer moving parts -5. **Trust**: Users can verify everything - -### Why no unsafe code? - -No unsafe code means: -1. **Safety**: Rust's guarantees apply everywhere -2. **Trust**: No hidden memory bugs -3. **Simplicity**: No manual memory management -4. **Auditability**: No special cases to review - -### Why offline-first? - -Offline-first ensures: -1. **Privacy**: Cannot exfiltrate data -2. **Reliability**: Works without internet -3. **Speed**: No network latency -4. **Security**: No remote code execution -5. **Trust**: Users control all inputs - -### How fast is Aletheia? - -Very fast - typically <50ms for most repositories. Bottleneck is filesystem I/O (stat calls). - -### How much memory does Aletheia use? - -Minimal - typically <5MB RAM. Only stores check results in memory. - -## Compliance Questions - -### What compliance levels exist? - -- **Bronze** (current): Foundation - docs, security, build system -- **Silver** (planned): Formal verification, advanced security -- **Gold** (planned): Multi-language, distributed systems -- **Platinum** (planned): Enterprise, CADRE integration - -### What does Bronze compliance require? - -Bronze requires: -- ✅ 7 documentation files (README, LICENSE, SECURITY, etc.) -- ✅ .well-known directory (security.txt, ai.txt, humans.txt) -- ✅ Build system (Justfile, flake.nix, CI/CD) -- ✅ Source structure (src/, tests/) - -See [RSR-SPECIFICATION.md](RSR-SPECIFICATION.md) for details. - -### How do I make my repository compliant? - -1. Run `aletheia` to see what's missing -2. Create missing files (see examples in Aletheia repo) -3. Re-run `aletheia` to verify -4. See [QUICK_START.md](QUICK_START.md) for step-by-step guide - -### Can I skip some requirements? - -No - all Bronze requirements are mandatory. However, you can: -- Use alternative build tools (alongside required ones) -- Add additional documentation -- Exceed minimum standards - -### What if I disagree with a requirement? - -The RSR specification is open for discussion: -- Open an issue on the specification repository -- Propose changes via merge request -- Join community discussions - -## Project Questions - -### Who maintains Aletheia? - -Aletheia is maintained by the MAA Framework team. See [MAINTAINERS.md](../MAINTAINERS.md) for details. - -### How can I contribute? - -See [CONTRIBUTING.md](../CONTRIBUTING.md) for contribution guidelines. We welcome: -- Bug reports -- Feature requests -- Documentation improvements -- Code contributions - -### What license is Aletheia under? - -Dual-licensed under your choice of: -- MIT License -- Palimpsest License v0.8 - -See [LICENSE.txt](../LICENSE.txt) for details. - -### Is Aletheia production-ready? - -Yes, for Bronze-level verification. It's: -- Well-tested (100% test pass rate) -- Zero unsafe code -- Zero dependencies -- Self-verified (Aletheia verifies itself) - -Silver/Gold/Platinum levels are planned for future releases. - -## Security Questions - -### How do I report a vulnerability? - -See [SECURITY.md](../SECURITY.md) for: -- Security contact email -- Confidential issue reporting -- Response timeline -- Disclosure process - -### Has Aletheia been audited? - -Not yet. We welcome security audits! The codebase is: -- ~300 lines of Rust -- Zero unsafe code -- Zero dependencies -- Easy to audit - -### What's the threat model? - -**In Scope**: -- Malicious repository contents -- Path traversal attacks -- Resource exhaustion - -**Out of Scope**: -- Physical access -- Compromised OS/kernel -- Side-channel attacks - -See [SECURITY.md](../SECURITY.md) for full threat model. - -### Can Aletheia be tricked? - -Known limitations: -1. Follows symbolic links (potential path traversal) -2. Could consume memory on very large files -3. TOCTOU races between checks and file reads - -These are documented for transparency but not considered security vulnerabilities in the current threat model. - -## Development Questions - -### Can I use Aletheia as a library? - -Currently, Aletheia is binary-only. Library API may be added in future versions. - -### How do I run tests? - -```bash -cargo test # Run all tests -cargo test -- --nocapture # See output -cargo test --release # Test optimized build -``` - -### How do I build for different platforms? - -```bash -# Linux (glibc) -cargo build --release --target x86_64-unknown-linux-gnu - -# Linux (musl - static binary) -cargo build --release --target x86_64-unknown-linux-musl - -# macOS -cargo build --release --target x86_64-apple-darwin - -# Windows -cargo build --release --target x86_64-pc-windows-gnu -``` - -### How do I add a new check? - -See [CLAUDE.md](../CLAUDE.md) for development guide. Basic steps: - -1. Add check function -2. Call from `verify_repository()` -3. Add tests -4. Update documentation - -## Philosophy Questions - -### What is the TPCF? - -TPCF (Tri-Perimeter Contribution Framework) is a graduated trust model: -- **Perimeter 1**: Core maintainers (full access) -- **Perimeter 2**: Trusted contributors (review/merge rights) -- **Perimeter 3**: Community sandbox (open contribution) - -See [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md) for details. - -### What is the Palimpsest License? - -The Palimpsest License v0.8 is a permissive license embodying principles of: -- Reversibility (Git makes everything reversible) -- Iteration (constant improvement) -- Impermanence (nothing is final) -- History preservation (layers remain visible) - -See [LICENSE-PALIMPSEST.txt](../LICENSE-PALIMPSEST.txt) for full text. - -### Why focus on emotional safety? - -We believe healthy open source requires: -- Psychological safety to experiment -- Safe to fail (mistakes are learning) -- Safe to dissent (respectful disagreement) -- Reduced anxiety (reversibility helps) - -See [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md) for our emotional safety framework. - -## Roadmap Questions - -### What's next for Aletheia? - -Planned features: -- **v0.2.0**: Silver-level compliance checks -- **v0.3.0**: Gold-level compliance checks -- **v0.4.0**: JSON output format -- **v0.5.0**: Configurable checks -- **v1.0.0**: Platinum-level compliance - -### When will Silver/Gold/Platinum be ready? - -No fixed timeline. We prioritize quality over speed. Follow: -- [CHANGELOG.md](../CHANGELOG.md) for updates -- [Issues](https://gitlab.com/maa-framework/6-the-foundation/aletheia/-/issues) for progress - -### Can I request features? - -Yes! Open an issue: -- Describe the feature -- Explain the use case -- Suggest implementation (optional) - -## Troubleshooting - -### Aletheia won't compile - -Check: -```bash -rustc --version # Should be 1.75+ -cargo --version -``` - -Update Rust: -```bash -rustup update -``` - -### Tests fail - -Run with verbose output: -```bash -cargo test -- --nocapture -``` - -Check for: -- Filesystem permissions -- Correct working directory -- Updated Rust version - -### Self-verification fails - -This shouldn't happen! If it does: -1. Check which files are missing -2. Verify you're in Aletheia directory -3. Open an issue (this is a bug) - -### CI/CD integration doesn't work - -Check: -- Aletheia installed correctly -- Running in repository root -- Exit code checked (0 = success, 1 = failure) - -## Still Have Questions? - -- **Documentation**: Browse [docs/](.) directory -- **Issues**: https://gitlab.com/maa-framework/6-the-foundation/aletheia/-/issues -- **Email**: maintainers@maa-framework.org - ---- - -*"The unexamined repository is not worth maintaining." - Adapted from Socrates* diff --git a/aletheia/docs/MIGRATION-GUIDE.md b/aletheia/docs/MIGRATION-GUIDE.adoc similarity index 74% rename from aletheia/docs/MIGRATION-GUIDE.md rename to aletheia/docs/MIGRATION-GUIDE.adoc index 4f9305f..211c0ba 100644 --- a/aletheia/docs/MIGRATION-GUIDE.md +++ b/aletheia/docs/MIGRATION-GUIDE.adoc @@ -1,26 +1,25 @@ - -# Migration Guide: Making Your Repository RSR-Compliant +== Migration Guide: Making Your Repository RSR-Compliant -This guide helps you migrate an existing repository to RSR Bronze-level compliance. +This guide helps you migrate an existing repository to RSR Bronze-level +compliance. -## Table of Contents +=== Table of Contents -1. [Assessment](#assessment) -2. [Documentation Migration](#documentation-migration) -3. [Security Setup](#security-setup) -4. [Build System](#build-system) -5. [Source Organization](#source-organization) -6. [Testing](#testing) -7. [Verification](#verification) +[arabic] +. link:#assessment[Assessment] +. link:#documentation-migration[Documentation Migration] +. link:#security-setup[Security Setup] +. link:#build-system[Build System] +. link:#source-organization[Source Organization] +. link:#testing[Testing] +. link:#verification[Verification] -## Assessment +=== Assessment -### Step 1: Run Initial Assessment +==== Step 1: Run Initial Assessment -```bash +[source,bash] +---- # Clone and install Aletheia git clone https://gitlab.com/maa-framework/6-the-foundation/aletheia.git cd aletheia @@ -29,11 +28,11 @@ cargo install --path . # Assess your repository cd /path/to/your/repository aletheia . -``` +---- -You'll see output like: +You’ll see output like: -``` +.... 🔍 Aletheia - RSR Compliance Verification Report ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Repository: /path/to/your/repository @@ -51,13 +50,14 @@ Repository: /path/to/your/repository Score: 3/16 checks passed (18.8%) ⚠️ Bronze-level RSR compliance: NOT MET -``` +.... -### Step 2: Create Checklist +==== Step 2: Create Checklist Based on the output, create a checklist of missing items: -```markdown +[source,markdown] +---- ## Migration Checklist ### Documentation @@ -81,15 +81,16 @@ Based on the output, create a checklist of missing items: ### Source Structure - [ ] Organize into src/ - [ ] Create tests/ directory -``` +---- -## Documentation Migration +=== Documentation Migration -### LICENSE.txt +==== LICENSE.txt -**If you already have a license:** +*If you already have a license:* -```bash +[source,bash] +---- # Rename existing license mv LICENSE LICENSE.txt @@ -103,21 +104,23 @@ This project is dual-licensed under: Choose the license that best fits your needs. EOF -``` +---- -**If you need to choose a license:** +*If you need to choose a license:* -```bash +[source,bash] +---- # MIT License (recommended for maximum compatibility) curl -o LICENSE-MIT.txt https://opensource.org/licenses/MIT # Or Apache 2.0 curl -o LICENSE-APACHE.txt https://www.apache.org/licenses/LICENSE-2.0.txt -``` +---- -### SECURITY.md +==== SECURITY.md -```bash +[source,bash] +---- # Create from template cat > SECURITY.md << 'EOF' # Security Policy @@ -143,11 +146,12 @@ Please report security vulnerabilities to: security@example.org See [.well-known/security.txt](.well-known/security.txt) for more details. EOF -``` +---- -### CONTRIBUTING.md +==== CONTRIBUTING.md -```bash +[source,bash] +---- # Create from template cat > CONTRIBUTING.md << 'EOF' # Contributing @@ -180,18 +184,20 @@ Thank you for your interest in contributing! See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) EOF -``` +---- -### CODE_OF_CONDUCT.md +==== CODE_OF_CONDUCT.md -```bash +[source,bash] +---- # Use Contributor Covenant curl -o CODE_OF_CONDUCT.md https://www.contributor-covenant.org/version/2/1/code_of_conduct/code_of_conduct.md -``` +---- -### MAINTAINERS.md +==== MAINTAINERS.md -```bash +[source,bash] +---- cat > MAINTAINERS.md << 'EOF' # Maintainers @@ -217,11 +223,12 @@ Criteria: - Major changes: Consensus among maintainers - Emergency: Any maintainer can act, notify others within 24h EOF -``` +---- -### CHANGELOG.md +==== CHANGELOG.md -```bash +[source,bash] +---- cat > CHANGELOG.md << 'EOF' # Changelog @@ -240,19 +247,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - Initial release EOF -``` +---- -## Security Setup +=== Security Setup -### Create .well-known Directory +==== Create .well-known Directory -```bash +[source,bash] +---- mkdir -p .well-known -``` +---- -### security.txt (RFC 9116) +==== security.txt (RFC 9116) -```bash +[source,bash] +---- cat > .well-known/security.txt << 'EOF' Contact: mailto:security@example.org Expires: 2026-12-31T23:59:59.000Z @@ -260,13 +269,14 @@ Preferred-Languages: en Canonical: https://example.org/.well-known/security.txt Policy: https://example.org/security-policy EOF -``` +---- -**Important**: Update expiration date and contact info! +*Important*: Update expiration date and contact info! -### ai.txt +==== ai.txt -```bash +[source,bash] +---- cat > .well-known/ai.txt << 'EOF' # AI Training and Usage Policy @@ -277,11 +287,12 @@ Attribution: Please credit the project Contact: ai-policy@example.org EOF -``` +---- -### humans.txt +==== humans.txt -```bash +[source,bash] +---- cat > .well-known/humans.txt << 'EOF' /* TEAM */ @@ -301,13 +312,14 @@ Repository: https://github.com/yourorg/yourproject License: MIT Last Updated: YYYY-MM-DD EOF -``` +---- -## Build System +=== Build System -### Justfile +==== Justfile -```bash +[source,bash] +---- cat > Justfile << 'EOF' # Build automation with Just @@ -334,11 +346,12 @@ run: clean: cargo clean EOF -``` +---- -### flake.nix (for Nix users) +==== flake.nix (for Nix users) -```bash +[source,bash] +---- cat > flake.nix << 'EOF' { description = "Your project description"; @@ -366,13 +379,14 @@ cat > flake.nix << 'EOF' }; } EOF -``` +---- -### CI/CD (.gitlab-ci.yml or GitHub Actions) +==== CI/CD (.gitlab-ci.yml or GitHub Actions) -**GitLab CI:** +*GitLab CI:* -```bash +[source,bash] +---- cat > .gitlab-ci.yml << 'EOF' stages: - check @@ -406,11 +420,12 @@ build: paths: - target/release/ EOF -``` +---- -**GitHub Actions:** +*GitHub Actions:* -```bash +[source,bash] +---- mkdir -p .github/workflows cat > .github/workflows/ci.yml << 'EOF' name: CI @@ -446,13 +461,14 @@ jobs: toolchain: stable - run: cargo build --release EOF -``` +---- -## Source Organization +=== Source Organization -### Reorganize Source Files +==== Reorganize Source Files -```bash +[source,bash] +---- # Create directories mkdir -p src tests @@ -473,13 +489,14 @@ fn test_basic() { assert_eq!(2 + 2, 4); } EOF -``` +---- -## Testing +=== Testing -### Add Tests +==== Add Tests -```bash +[source,bash] +---- # For Rust cat >> src/lib.rs << 'EOF' #[cfg(test)] @@ -493,24 +510,26 @@ EOF # Run tests cargo test -``` +---- -## Verification +=== Verification -### Final Verification +==== Final Verification -```bash +[source,bash] +---- # Run Aletheia aletheia . # Should see: # 16/16 checks passed (100.0%) # 🏆 Bronze-level RSR compliance: ACHIEVED -``` +---- -### Commit Changes +==== Commit Changes -```bash +[source,bash] +---- git add . git commit -m "feat: achieve RSR Bronze-level compliance @@ -522,44 +541,51 @@ git commit -m "feat: achieve RSR Bronze-level compliance - Add comprehensive tests Verified with Aletheia - 16/16 checks passed" -``` +---- -## Common Issues +=== Common Issues -### Issue: Multiple license files +==== Issue: Multiple license files -**Problem**: You have `LICENSE`, `LICENSE.md`, and `LICENSE.txt` +*Problem*: You have `+LICENSE+`, `+LICENSE.md+`, and `+LICENSE.txt+` -**Solution**: -```bash +*Solution*: + +[source,bash] +---- # Choose one format, use LICENSE.txt mv LICENSE LICENSE.txt rm LICENSE.md # If redundant -``` +---- + +==== Issue: Tests in wrong location -### Issue: Tests in wrong location +*Problem*: Tests are in `+test/+` but Aletheia expects `+tests/+` -**Problem**: Tests are in `test/` but Aletheia expects `tests/` +*Solution*: -**Solution**: -```bash +[source,bash] +---- mv test tests -``` +---- + +==== Issue: Missing Cargo.toml -### Issue: Missing Cargo.toml +*Problem*: Rust project without Cargo.toml -**Problem**: Rust project without Cargo.toml +*Solution*: -**Solution**: -```bash +[source,bash] +---- cargo init --name your-project-name -``` +---- -## Language-Specific Guides +=== Language-Specific Guides -### Python Projects +==== Python Projects -```bash +[source,bash] +---- # Create src/ mkdir -p src tests @@ -587,11 +613,12 @@ lint: format: black src/ tests/ EOF -``` +---- -### JavaScript/TypeScript +==== JavaScript/TypeScript -```bash +[source,bash] +---- # Create directories mkdir -p src tests @@ -613,36 +640,38 @@ lint: format: npm run format EOF -``` +---- -## Timeline +=== Timeline Typical migration timeline: -- **Day 1**: Assessment and planning (1-2 hours) -- **Day 2**: Documentation (2-3 hours) -- **Day 3**: Security and .well-known (1 hour) -- **Day 4**: Build system and CI/CD (2-3 hours) -- **Day 5**: Source organization and testing (2-4 hours) -- **Day 6**: Verification and cleanup (1 hour) +* *Day 1*: Assessment and planning (1-2 hours) +* *Day 2*: Documentation (2-3 hours) +* *Day 3*: Security and .well-known (1 hour) +* *Day 4*: Build system and CI/CD (2-3 hours) +* *Day 5*: Source organization and testing (2-4 hours) +* *Day 6*: Verification and cleanup (1 hour) -**Total**: 10-15 hours for most projects +*Total*: 10-15 hours for most projects -## Resources +=== Resources -- [RSR Specification](RSR-SPECIFICATION.md) -- [Aletheia Documentation](https://gitlab.com/maa-framework/6-the-foundation/aletheia) -- [Keep a Changelog](https://keepachangelog.com/) -- [Contributor Covenant](https://www.contributor-covenant.org/) -- [RFC 9116 (security.txt)](https://www.rfc-editor.org/rfc/rfc9116.html) +* link:RSR-SPECIFICATION.md[RSR Specification] +* https://gitlab.com/maa-framework/6-the-foundation/aletheia[Aletheia +Documentation] +* https://keepachangelog.com/[Keep a Changelog] +* https://www.contributor-covenant.org/[Contributor Covenant] +* https://www.rfc-editor.org/rfc/rfc9116.html[RFC 9116 (security.txt)] -## Support +=== Support Need help with migration? -- **Issues**: https://gitlab.com/maa-framework/6-the-foundation/aletheia/-/issues -- **Email**: maintainers@maa-framework.org +* *Issues*: +https://gitlab.com/maa-framework/6-the-foundation/aletheia/-/issues +* *Email*: maintainers@maa-framework.org ---- +''''' -*Make your repository RSR-compliant - pursue alētheia!* +_Make your repository RSR-compliant - pursue alētheia!_ diff --git a/aletheia/docs/PRIORITIES.adoc b/aletheia/docs/PRIORITIES.adoc new file mode 100644 index 0000000..aa0d743 --- /dev/null +++ b/aletheia/docs/PRIORITIES.adoc @@ -0,0 +1,258 @@ +== Aletheia Project Priorities + +*Snapshot Date*: 2025-12-26 (Updated) *Current Version*: 0.1.x +*Compliance Status*: 16/16 Bronze RSR (100%) *Codebase Size*: ~810 lines +(main.rs) + ~480 lines (tests) + +''''' + +=== Current State Assessment + +==== Strengths + +[width="100%",cols="29%,38%,33%",options="header",] +|=== +|Area |Status |Notes +|Zero Dependencies |Achieved |Only std library +|Zero Unsafe Code |Achieved |100% safe Rust +|Self-Verification |Passing |16/16 checks +|Test Coverage |Excellent |28 tests (10 unit + 18 integration) +|Security Features |Implemented |Symlink detection, timestamps, warnings +|Documentation |Complete |All required docs present +|Build Systems |Complete |Cargo, Just, Nix, CI/CD +|CLI Features |Complete |JSON, quiet, verbose, exit codes +|Security Audit |Complete |2025-12-26, 0 vulnerabilities +|=== + +==== Technical Debt + +[width="100%",cols="24%,38%,38%",options="header",] +|=== +|Item |Severity |Location +|Timestamp impl is verbose |Low |`+format_timestamp()+` - 50 lines for +date math + +|Some `+#[allow(dead_code)]+` |Low |Reserved for future use +|=== + +''''' + +=== MUST (Critical - Do First) + +==== Immediate (Before v0.1.0 Release) - COMPLETED + +[arabic] +. [line-through]#*Tag and Release v0.1.0*# ✅ COMPLETED +* Current state is release-ready +* Tag: `+git tag -a v0.1.0 -m "Initial release"+` +* Create release notes from CHANGELOG.md +. *Verify CI/CD Pipeline Works* - PENDING +* `+.gitlab-ci.yml+` exists but untested in production +* Run full pipeline before announcing release +* Fix any blocking issues +. [line-through]#*Update CHANGELOG.md*# ✅ COMPLETED +* Document security improvements from this audit +* Add symlink detection feature +* Add timestamp feature +. [line-through]#*Security Audit Documentation*# ✅ COMPLETED +* Update SECURITY.md "`Last Audit`" section +* Document that audit was performed 2025-12-26 +* Note zero vulnerabilities found + +==== Before v0.2.0 - COMPLETED + +[arabic, start=5] +. [line-through]#*Add JSON Output Format*# ✅ COMPLETED +* `+--format json+` flag implemented +* Machine-parseable results +* CI/CD ready +. [line-through]#*Exit Codes for Categories*# ✅ COMPLETED +* 0 = success (all checks passed) +* 1 = compliance failure +* 2 = security warning (critical) +* 3 = invalid path +* 4 = invalid arguments + +''''' + +=== SHOULD (Important - Do Soon) + +==== v0.2.0 - v0.3.0 Timeframe + +[arabic, start=7] +. *Configuration File Support* - PENDING +* `+.aletheia.toml+` or `+.aletheia.yaml+` +* Allow ignoring specific checks +* Custom severity levels +* Per-project overrides +. *SARIF Output* - PENDING +* Static Analysis Results Interchange Format +* GitHub/GitLab security dashboard integration +* Industry standard for security tools +. [line-through]#*Quiet and Verbose Modes*# ✅ COMPLETED +* `+--quiet+` - Only show pass/fail +* `+--verbose+` - Show all details including explanations +* Help text: `+--help+` +. *Better Error Messages* - PENDING +* Current: "`Path does not exist`" +* Better: "`Path '`/foo/bar`' does not exist. Did you mean +'`/foo/baz`'?`" +* Suggest fixes for common issues +. *README.md Generation* - PENDING +* `+aletheia init+` command +* Generate missing Bronze-level files +* Template-based scaffolding +. [line-through]#*GitHub Actions Workflow*# ✅ COMPLETED +* `+.github/workflows/aletheia.yml+` template provided +* Easy adoption for GitHub users +* Multi-platform support +. [line-through]#*Performance Benchmarks*# ✅ COMPLETED +* `+benches/verification_benchmark.rs+` fully implemented +* Measures verification speed (~12ms avg) +* Tracks min/max/avg with warmup +. [line-through]#*More Integration Tests*# ✅ COMPLETED +* 18 integration tests total +* Tests: JSON output, quiet/verbose modes, exit codes +* Tests: timestamp format, README.adoc alternative +* Tests: invalid args, invalid paths, format syntax + +''''' + +=== COULD (Nice to Have - Do Later) + +==== v0.4.0 - v0.6.0 Timeframe + +[arabic, start=15] +. *Silver-Level RSR Checks* +* Formal verification hooks +* Property-based testing detection +* Coverage thresholds +* Mutation testing validation +. *Multi-Language Detection* +* Detect project language (Rust, Python, Go, etc.) +* Language-specific checks +* Build system detection +. *HTML Report Generation* +* Visual compliance report +* Shareable dashboard +* Badge generation +. *Watch Mode* +* `+aletheia watch+` +* Re-verify on file changes +* Developer feedback loop +. *Library API* +* Currently binary-only +* Expose as library crate +* Programmatic verification +. *Incremental Verification* +* Cache previous results +* Only re-check changed files +* Faster CI runs +. *Batch Verification* +* `+aletheia scan /path/to/repos/*+` +* Verify multiple repos at once +* Summary report + +==== v0.7.0+ (Long-term) + +[arabic, start=22] +. *Gold-Level RSR* +* Multi-language support +* Polyglot build systems +* Cross-language dependencies +. *Platinum-Level RSR* +* CADRE integration +* Formal proofs +* Enterprise features +. *Plugin Architecture* +* Custom check modules +* Third-party extensions +* Language-specific plugins +. *LSP Integration* +* IDE feedback +* Real-time compliance hints +* Editor extensions + +''''' + +=== Anti-Priorities (MUST NOT) + +These violate RSR Bronze principles and must NEVER be done: + +[cols=",",options="header",] +|=== +|Anti-Priority |Reason +|Add external dependencies |Violates zero-dependency principle +|Use `+unsafe+` code |Violates memory safety guarantee +|Make network requests |Violates offline-first principle +|Phone home / telemetry |Privacy violation +|Break single-binary |Deployment complexity +|Remove existing tests |Quality regression +|=== + +''''' + +=== Recommended Next Actions + +==== This Week + +[arabic] +. [line-through]#Update CHANGELOG.md with security audit results# ✅ +DONE +. Tag v0.1.0 release +. Verify GitLab CI/CD pipeline + +==== This Month + +[arabic, start=4] +. [line-through]#Implement `+--format json+`# ✅ DONE +. [line-through]#Add distinct exit codes# ✅ DONE +. [line-through]#Write more integration tests# ✅ DONE (18 total) +. Configuration file support (`+.aletheia.toml+`) +. SARIF output format + +==== This Quarter + +[arabic, start=9] +. Silver-level RSR planning +. `+aletheia init+` scaffolding command +. Better error messages with suggestions +. Library API (programmatic usage) + +''''' + +=== Metrics to Track + +[cols=",,",options="header",] +|=== +|Metric |Current |Target (v1.0) +|Lines of Code |~810 |<1000 +|Unit Tests |10 |25+ +|Integration Tests |18 |20+ +|Dependencies |0 |0 +|Unsafe Blocks |0 |0 +|Bronze Compliance |100% |100% +|Clippy Warnings |0 |0 +|Security Audit |Complete |Annual +|=== + +''''' + +=== Decision Log + +[width="100%",cols="23%,37%,40%",options="header",] +|=== +|Date |Decision |Rationale +|2025-12-26 |Add symlink detection |Security: prevent repo escape + +|2025-12-26 |Add timestamps |TOCTOU mitigation + +|2025-12-26 |Accept README.adoc |Flexibility for AsciiDoc users + +|2025-12-26 |Critical warnings fail verification |Security-first +approach +|=== + +''''' + +*Last Updated*: 2025-12-26 *Next Review*: After v0.1.0 release diff --git a/aletheia/docs/PRIORITIES.md b/aletheia/docs/PRIORITIES.md deleted file mode 100644 index 8c40586..0000000 --- a/aletheia/docs/PRIORITIES.md +++ /dev/null @@ -1,253 +0,0 @@ - -# Aletheia Project Priorities - -**Snapshot Date**: 2025-12-26 (Updated) -**Current Version**: 0.1.x -**Compliance Status**: 16/16 Bronze RSR (100%) -**Codebase Size**: ~810 lines (main.rs) + ~480 lines (tests) - ---- - -## Current State Assessment - -### Strengths -| Area | Status | Notes | -|------|--------|-------| -| Zero Dependencies | Achieved | Only std library | -| Zero Unsafe Code | Achieved | 100% safe Rust | -| Self-Verification | Passing | 16/16 checks | -| Test Coverage | Excellent | 28 tests (10 unit + 18 integration) | -| Security Features | Implemented | Symlink detection, timestamps, warnings | -| Documentation | Complete | All required docs present | -| Build Systems | Complete | Cargo, Just, Nix, CI/CD | -| CLI Features | Complete | JSON, quiet, verbose, exit codes | -| Security Audit | Complete | 2025-12-26, 0 vulnerabilities | - -### Technical Debt -| Item | Severity | Location | -|------|----------|----------| -| Timestamp impl is verbose | Low | `format_timestamp()` - 50 lines for date math | -| Some `#[allow(dead_code)]` | Low | Reserved for future use | - ---- - -## MUST (Critical - Do First) - -### Immediate (Before v0.1.0 Release) - COMPLETED - -1. ~~**Tag and Release v0.1.0**~~ ✅ COMPLETED - - Current state is release-ready - - Tag: `git tag -a v0.1.0 -m "Initial release"` - - Create release notes from CHANGELOG.md - -2. **Verify CI/CD Pipeline Works** - PENDING - - `.gitlab-ci.yml` exists but untested in production - - Run full pipeline before announcing release - - Fix any blocking issues - -3. ~~**Update CHANGELOG.md**~~ ✅ COMPLETED - - Document security improvements from this audit - - Add symlink detection feature - - Add timestamp feature - -4. ~~**Security Audit Documentation**~~ ✅ COMPLETED - - Update SECURITY.md "Last Audit" section - - Document that audit was performed 2025-12-26 - - Note zero vulnerabilities found - -### Before v0.2.0 - COMPLETED - -5. ~~**Add JSON Output Format**~~ ✅ COMPLETED - - `--format json` flag implemented - - Machine-parseable results - - CI/CD ready - -6. ~~**Exit Codes for Categories**~~ ✅ COMPLETED - - 0 = success (all checks passed) - - 1 = compliance failure - - 2 = security warning (critical) - - 3 = invalid path - - 4 = invalid arguments - ---- - -## SHOULD (Important - Do Soon) - -### v0.2.0 - v0.3.0 Timeframe - -7. **Configuration File Support** - PENDING - - `.aletheia.toml` or `.aletheia.yaml` - - Allow ignoring specific checks - - Custom severity levels - - Per-project overrides - -8. **SARIF Output** - PENDING - - Static Analysis Results Interchange Format - - GitHub/GitLab security dashboard integration - - Industry standard for security tools - -9. ~~**Quiet and Verbose Modes**~~ ✅ COMPLETED - - `--quiet` - Only show pass/fail - - `--verbose` - Show all details including explanations - - Help text: `--help` - -10. **Better Error Messages** - PENDING - - Current: "Path does not exist" - - Better: "Path '/foo/bar' does not exist. Did you mean '/foo/baz'?" - - Suggest fixes for common issues - -11. **README.md Generation** - PENDING - - `aletheia init` command - - Generate missing Bronze-level files - - Template-based scaffolding - -12. ~~**GitHub Actions Workflow**~~ ✅ COMPLETED - - `.github/workflows/aletheia.yml` template provided - - Easy adoption for GitHub users - - Multi-platform support - -13. ~~**Performance Benchmarks**~~ ✅ COMPLETED - - `benches/verification_benchmark.rs` fully implemented - - Measures verification speed (~12ms avg) - - Tracks min/max/avg with warmup - -14. ~~**More Integration Tests**~~ ✅ COMPLETED - - 18 integration tests total - - Tests: JSON output, quiet/verbose modes, exit codes - - Tests: timestamp format, README.adoc alternative - - Tests: invalid args, invalid paths, format syntax - ---- - -## COULD (Nice to Have - Do Later) - -### v0.4.0 - v0.6.0 Timeframe - -15. **Silver-Level RSR Checks** - - Formal verification hooks - - Property-based testing detection - - Coverage thresholds - - Mutation testing validation - -16. **Multi-Language Detection** - - Detect project language (Rust, Python, Go, etc.) - - Language-specific checks - - Build system detection - -17. **HTML Report Generation** - - Visual compliance report - - Shareable dashboard - - Badge generation - -18. **Watch Mode** - - `aletheia watch` - - Re-verify on file changes - - Developer feedback loop - -19. **Library API** - - Currently binary-only - - Expose as library crate - - Programmatic verification - -20. **Incremental Verification** - - Cache previous results - - Only re-check changed files - - Faster CI runs - -21. **Batch Verification** - - `aletheia scan /path/to/repos/*` - - Verify multiple repos at once - - Summary report - -### v0.7.0+ (Long-term) - -22. **Gold-Level RSR** - - Multi-language support - - Polyglot build systems - - Cross-language dependencies - -23. **Platinum-Level RSR** - - CADRE integration - - Formal proofs - - Enterprise features - -24. **Plugin Architecture** - - Custom check modules - - Third-party extensions - - Language-specific plugins - -25. **LSP Integration** - - IDE feedback - - Real-time compliance hints - - Editor extensions - ---- - -## Anti-Priorities (MUST NOT) - -These violate RSR Bronze principles and must NEVER be done: - -| Anti-Priority | Reason | -|---------------|--------| -| Add external dependencies | Violates zero-dependency principle | -| Use `unsafe` code | Violates memory safety guarantee | -| Make network requests | Violates offline-first principle | -| Phone home / telemetry | Privacy violation | -| Break single-binary | Deployment complexity | -| Remove existing tests | Quality regression | - ---- - -## Recommended Next Actions - -### This Week -1. ~~Update CHANGELOG.md with security audit results~~ ✅ DONE -2. Tag v0.1.0 release -3. Verify GitLab CI/CD pipeline - -### This Month -4. ~~Implement `--format json`~~ ✅ DONE -5. ~~Add distinct exit codes~~ ✅ DONE -6. ~~Write more integration tests~~ ✅ DONE (18 total) -7. Configuration file support (`.aletheia.toml`) -8. SARIF output format - -### This Quarter -9. Silver-level RSR planning -10. `aletheia init` scaffolding command -11. Better error messages with suggestions -12. Library API (programmatic usage) - ---- - -## Metrics to Track - -| Metric | Current | Target (v1.0) | -|--------|---------|---------------| -| Lines of Code | ~810 | <1000 | -| Unit Tests | 10 | 25+ | -| Integration Tests | 18 | 20+ | -| Dependencies | 0 | 0 | -| Unsafe Blocks | 0 | 0 | -| Bronze Compliance | 100% | 100% | -| Clippy Warnings | 0 | 0 | -| Security Audit | Complete | Annual | - ---- - -## Decision Log - -| Date | Decision | Rationale | -|------|----------|-----------| -| 2025-12-26 | Add symlink detection | Security: prevent repo escape | -| 2025-12-26 | Add timestamps | TOCTOU mitigation | -| 2025-12-26 | Accept README.adoc | Flexibility for AsciiDoc users | -| 2025-12-26 | Critical warnings fail verification | Security-first approach | - ---- - -**Last Updated**: 2025-12-26 -**Next Review**: After v0.1.0 release diff --git a/aletheia/docs/QUICK_START.md b/aletheia/docs/QUICK_START.adoc similarity index 64% rename from aletheia/docs/QUICK_START.md rename to aletheia/docs/QUICK_START.adoc index 66c3e97..2f39661 100644 --- a/aletheia/docs/QUICK_START.md +++ b/aletheia/docs/QUICK_START.adoc @@ -1,16 +1,13 @@ - -# Quick Start Guide +== Quick Start Guide Get started with Aletheia in 5 minutes. -## Installation +=== Installation -### Option 1: Build from Source (Recommended) +==== Option 1: Build from Source (Recommended) -```bash +[source,bash] +---- # Clone the repository git clone https://gitlab.com/maa-framework/6-the-foundation/aletheia.git cd aletheia @@ -20,11 +17,12 @@ cargo build --release # Run verification cargo run -``` +---- -### Option 2: Using Nix (Reproducible Build) +==== Option 2: Using Nix (Reproducible Build) -```bash +[source,bash] +---- # Clone the repository git clone https://gitlab.com/maa-framework/6-the-foundation/aletheia.git cd aletheia @@ -35,36 +33,39 @@ nix develop # Build and run just build just run -``` +---- -### Option 3: Direct Installation +==== Option 3: Direct Installation -```bash +[source,bash] +---- # Install directly from repository cargo install --git https://gitlab.com/maa-framework/6-the-foundation/aletheia.git -``` +---- -## First Verification +=== First Verification -### Verify Current Directory +==== Verify Current Directory -```bash +[source,bash] +---- cargo run -``` +---- This verifies the current directory against RSR Bronze-level standards. -### Verify Specific Repository +==== Verify Specific Repository -```bash +[source,bash] +---- cargo run -- /path/to/your/repository -``` +---- -## Understanding the Output +=== Understanding the Output -### Passing Example +==== Passing Example -``` +.... 🔍 Aletheia - RSR Compliance Verification Report ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Repository: /home/user/my-project @@ -96,13 +97,13 @@ Repository: /home/user/my-project ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Score: 16/16 checks passed (100.0%) 🏆 Bronze-level RSR compliance: ACHIEVED -``` +.... -**Exit code**: 0 (success) +*Exit code*: 0 (success) -### Failing Example +==== Failing Example -``` +.... 🔍 Aletheia - RSR Compliance Verification Report ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Repository: /home/user/incomplete-project @@ -116,17 +117,18 @@ Repository: /home/user/incomplete-project ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Score: 8/16 checks passed (50.0%) ⚠️ Bronze-level RSR compliance: NOT MET -``` +.... -**Exit code**: 1 (failure) +*Exit code*: 1 (failure) -## Making Your Repository Compliant +=== Making Your Repository Compliant If your repository fails verification, follow these steps: -### 1. Create Missing Documentation +==== 1. Create Missing Documentation -```bash +[source,bash] +---- # Required files touch README.md touch LICENSE.txt @@ -135,44 +137,49 @@ touch CONTRIBUTING.md touch CODE_OF_CONDUCT.md touch MAINTAINERS.md touch CHANGELOG.md -``` +---- -See [examples in Aletheia repository](../) for content templates. +See link:../[examples in Aletheia repository] for content templates. -### 2. Create .well-known Directory +==== 2. Create .well-known Directory -```bash +[source,bash] +---- mkdir -p .well-known touch .well-known/security.txt touch .well-known/ai.txt touch .well-known/humans.txt -``` +---- -**security.txt** (RFC 9116 format): -``` +*security.txt* (RFC 9116 format): + +.... Contact: mailto:security@example.org Expires: 2026-01-01T00:00:00.000Z Preferred-Languages: en Canonical: https://example.org/.well-known/security.txt -``` +.... + +*ai.txt* (AI training policy): -**ai.txt** (AI training policy): -``` +.... # AI Training Policy License: MIT Training: Allowed with attribution -``` +.... + +*humans.txt* (attribution): -**humans.txt** (attribution): -``` +.... /* TEAM */ Project: Your Project Maintainers: Your Team -``` +.... -### 3. Create Build System Files +==== 3. Create Build System Files -```bash +[source,bash] +---- # Create Justfile touch Justfile @@ -181,30 +188,33 @@ touch flake.nix # Create CI/CD touch .gitlab-ci.yml # or .github/workflows/ci.yml -``` +---- -### 4. Organize Source Structure +==== 4. Organize Source Structure -```bash +[source,bash] +---- # Create required directories mkdir -p src mkdir -p tests # Move source files to src/ mv *.rs src/ # (or your language) -``` +---- -### 5. Re-verify +==== 5. Re-verify -```bash +[source,bash] +---- cargo run -``` +---- -## Using with CI/CD +=== Using with CI/CD -### GitLab CI +==== GitLab CI -```yaml +[source,yaml] +---- # .gitlab-ci.yml rsr-compliance: stage: test @@ -213,11 +223,12 @@ rsr-compliance: - cargo install --git https://gitlab.com/maa-framework/6-the-foundation/aletheia.git - aletheia allow_failure: false -``` +---- -### GitHub Actions +==== GitHub Actions -```yaml +[source,yaml] +---- # .github/workflows/rsr.yml name: RSR Compliance on: [push, pull_request] @@ -231,13 +242,14 @@ jobs: toolchain: stable - run: cargo install --git https://gitlab.com/maa-framework/6-the-foundation/aletheia.git - run: aletheia -``` +---- -## Development Workflow +=== Development Workflow -### Using Just (Recommended) +==== Using Just (Recommended) -```bash +[source,bash] +---- # List all commands just @@ -252,11 +264,12 @@ just check # Verify RSR compliance just validate -``` +---- -### Using Cargo Directly +==== Using Cargo Directly -```bash +[source,bash] +---- # Build cargo build --release @@ -271,64 +284,70 @@ cargo clippy # Verify cargo run -``` +---- -## Common Issues +=== Common Issues -### Issue: "Path does not exist" +==== Issue: "`Path does not exist`" -**Problem**: Specified path doesn't exist +*Problem*: Specified path doesn’t exist -**Solution**: -```bash +*Solution*: + +[source,bash] +---- # Check path ls /path/to/repository # Use absolute path cargo run -- /absolute/path/to/repository -``` +---- + +==== Issue: "`Not a directory`" -### Issue: "Not a directory" +*Problem*: Path is a file, not a directory -**Problem**: Path is a file, not a directory +*Solution*: -**Solution**: -```bash +[source,bash] +---- # Verify directory cargo run -- /path/to/directory/ -``` +---- + +==== Issue: Low compliance score -### Issue: Low compliance score +*Problem*: Missing required files -**Problem**: Missing required files +*Solution*: 1. Check which files are missing (marked with ❌) 2. Create +missing files 3. Re-run verification -**Solution**: -1. Check which files are missing (marked with ❌) -2. Create missing files -3. Re-run verification +==== Issue: Tests not found -### Issue: Tests not found +*Problem*: No `+tests/+` directory -**Problem**: No `tests/` directory +*Solution*: -**Solution**: -```bash +[source,bash] +---- mkdir tests # Add test files -``` +---- -## Next Steps +=== Next Steps -- Read [ARCHITECTURE.md](ARCHITECTURE.md) - Understand how Aletheia works -- Read [RSR-SPECIFICATION.md](RSR-SPECIFICATION.md) - Learn RSR standards -- Read [CONTRIBUTING.md](../CONTRIBUTING.md) - Contribute to Aletheia +* Read ARCHITECTURE.md - Understand how Aletheia works +* Read RSR-SPECIFICATION.md - Learn RSR standards +* Read link:../CONTRIBUTING.md[CONTRIBUTING.md] - Contribute to Aletheia -## Support +=== Support -- **Issues**: https://gitlab.com/maa-framework/6-the-foundation/aletheia/-/issues -- **Documentation**: https://gitlab.com/maa-framework/6-the-foundation/aletheia -- **Email**: maintainers@maa-framework.org +* *Issues*: +https://gitlab.com/maa-framework/6-the-foundation/aletheia/-/issues +* *Documentation*: +https://gitlab.com/maa-framework/6-the-foundation/aletheia +* *Email*: maintainers@maa-framework.org ---- +''''' -*Start pursuing alētheia (truth) through rigorous standards!* +_Start pursuing alētheia (truth) through rigorous standards!_ diff --git a/aletheia/docs/RSR-SPECIFICATION.adoc b/aletheia/docs/RSR-SPECIFICATION.adoc new file mode 100644 index 0000000..d696c5a --- /dev/null +++ b/aletheia/docs/RSR-SPECIFICATION.adoc @@ -0,0 +1,341 @@ +== RSR (Rhodium Standard Repository) Specification + +=== Version 0.1.0 + +This document specifies the Rhodium Standard Repository (RSR) framework +compliance levels and requirements. + +=== Table of Contents + +[arabic] +. link:#overview[Overview] +. link:#compliance-levels[Compliance Levels] +. link:#bronze-level-requirements[Bronze Level Requirements] +. link:#silver-level-requirements[Silver Level Requirements] +. link:#gold-level-requirements[Gold Level Requirements] +. link:#platinum-level-requirements[Platinum Level Requirements] +. link:#tpcf-integration[TPCF Integration] + +=== Overview + +The Rhodium Standard Repository (RSR) framework defines a graduated set +of standards for software repositories, covering: + +* *Type Safety*: Compile-time correctness guarantees +* *Memory Safety*: Protection against memory vulnerabilities +* *Security*: Vulnerability disclosure and secure development +* *Documentation*: Comprehensive project documentation +* *Build System*: Reproducible, automated builds +* *Testing*: Comprehensive test coverage +* *Offline-First*: Air-gapped operation capability +* *Community*: Governance and contribution guidelines + +The name "`Rhodium`" references the precious metal’s properties: - +*Rare*: High standards are uncommon - *Valuable*: Quality software is +precious - *Durable*: Well-built software lasts - *Reflective*: +Standards help us see clearly + +=== Compliance Levels + +==== Level Hierarchy + +.... +Platinum (Highest) + ↑ + Gold + ↑ + Silver + ↑ + Bronze (Entry Level) +.... + +Each level builds upon the requirements of the previous level. + +=== Bronze Level Requirements + +*Goal*: Establish foundational quality, security, and documentation +standards. + +==== 1. Type Safety + +*Required*: Compile-time type checking + +* *Rust*: Use Rust 2021 edition or later (built-in type safety) +* *Other Languages*: Must have static type checking enabled +** TypeScript: `+strict: true+` in tsconfig.json +** Python: Type hints + mypy strict mode +** Go: Standard compiler (built-in) +** Haskell: GHC (built-in) + +==== 2. Memory Safety + +*Required*: Protection against memory vulnerabilities + +* *Rust*: Ownership model, zero `+unsafe+` blocks +* *Other Languages*: Memory-safe by design (GC languages) or formal +verification + +==== 3. Zero Dependencies (Language-Specific) + +*Required*: Minimal dependency footprint + +* *Interpreted Languages* (Python, JavaScript, Ruby): Use only standard +library +* *Compiled Languages* (Rust, Go): Zero external dependencies +* *Exceptions*: Build tools (cargo, npm) and dev dependencies for +testing are allowed + +==== 4. Offline-First + +*Required*: Works completely air-gapped + +* No network calls in core functionality +* No external API dependencies +* No analytics or telemetry +* All resources bundled or locally available + +==== 5. Documentation + +*Required Files*: + +* ✅ `+README.md+` - Project overview, quick start, usage +* ✅ `+LICENSE.txt+` - Open source license (MIT, Apache, GPL, etc.) +* ✅ `+SECURITY.md+` - Security policy and vulnerability disclosure +* ✅ `+CONTRIBUTING.md+` - Contribution guidelines +* ✅ `+CODE_OF_CONDUCT.md+` - Community standards +* ✅ `+MAINTAINERS.md+` - Project governance +* ✅ `+CHANGELOG.md+` - Version history (Keep a Changelog format) + +*Minimum Content*: + +* *README.md*: Purpose, quick start, installation, basic usage +* *LICENSE.txt*: Valid OSI-approved license +* *SECURITY.md*: Contact info, disclosure policy, response timeline +* *CONTRIBUTING.md*: How to contribute, code style, PR process +* *CODE_OF_CONDUCT.md*: Community standards (Contributor Covenant or +similar) +* *MAINTAINERS.md*: Who maintains the project, decision process +* *CHANGELOG.md*: Version history following Keep a Changelog + +==== 6. .well-known Directory + +*Required*: RFC 9116 compliance and metadata + +* ✅ `+.well-known/security.txt+` - RFC 9116 compliant security contact +* ✅ `+.well-known/ai.txt+` - AI training and usage policies +* ✅ `+.well-known/humans.txt+` - Human-readable attribution + +*security.txt Format*: + +.... +Contact: mailto:security@example.org +Expires: 2026-01-01T00:00:00.000Z +Preferred-Languages: en +Canonical: https://example.org/.well-known/security.txt +Policy: https://example.org/security-policy +.... + +==== 7. Build System + +*Required*: Automated, reproducible builds + +* ✅ `+justfile+` - Build automation (using Just) +* ✅ `+flake.nix+` - Nix reproducible builds +* ✅ `+.gitlab-ci.yml+` or `+.github/workflows/+` - CI/CD pipeline + +*Minimum Recipes*: - `+build+` - Build the project - `+test+` - Run all +tests - `+lint+` - Run linters - `+fmt+` - Format code - `+check+` - Run +all checks + +==== 8. Source Structure + +*Required*: Organized source code + +* ✅ `+src/+` directory - Source code +* ✅ `+tests/+` directory - Test files +* Clear separation of concerns +* Logical file organization + +==== 9. Testing + +*Required*: Comprehensive test suite + +* Unit tests for core functionality +* Integration tests for workflows +* 100% test pass rate (no skipped tests in default run) +* Tests run in CI/CD + +==== 10. Version Control + +*Required*: Git best practices + +* `+.gitignore+` - Ignore build artifacts +* Clear commit messages +* Semantic versioning (semver) +* Tagged releases + +==== 11. License Compliance + +*Required*: Clear, OSI-approved licensing + +* Valid open source license +* License file in root +* Copyright notices +* Dual licensing allowed (e.g., MIT OR Apache-2.0) + +=== Silver Level Requirements + +*Goal*: Add formal verification and advanced security. + +_(All Bronze requirements PLUS):_ + +==== 1. Formal Verification + +* Formal proofs of key algorithms +* Property-based testing (QuickCheck, PropTest) +* SPARK proofs (for Ada) +* TLA+ specifications (for distributed systems) + +==== 2. Security Hardening + +* Security audit completed +* Dependency scanning (if dependencies exist) +* SBOM (Software Bill of Materials) generation +* Signed releases + +==== 3. Advanced Documentation + +* Architecture Decision Records (ADRs) +* API documentation (rustdoc, JSDoc, etc.) +* Usage examples +* Performance benchmarks + +==== 4. Enhanced Testing + +* Mutation testing (cargo-mutants) +* Fuzzing tests +* Coverage >80% +* Benchmark suite + +=== Gold Level Requirements + +*Goal*: Multi-language verification and distributed systems support. + +_(All Silver requirements PLUS):_ + +==== 1. Multi-Language Support + +* FFI contracts for language boundaries +* WASM sandboxing for untrusted code +* Type-safe language interop + +==== 2. Distributed Systems + +* CRDT-based state management +* Offline-first data sync +* Conflict-free merging +* TLA+ formal specifications + +==== 3. Advanced Architecture + +* Modular plugin system +* Clean architecture boundaries +* Dependency injection +* Testable design + +=== Platinum Level Requirements + +*Goal*: Production-grade enterprise systems with full CADRE integration. + +_(All Gold requirements PLUS):_ + +==== 1. CADRE Integration + +* Conflict-free Asynchronous Data Replication Engine +* Production-tested at scale +* Multi-datacenter support +* Disaster recovery tested + +==== 2. Enterprise Features + +* Audit logging +* Role-based access control +* Compliance reporting (SOC2, GDPR, etc.) +* SLA guarantees + +==== 3. Operational Excellence + +* Monitoring and observability +* Incident response playbooks +* Disaster recovery procedures +* 24/7 support capability + +=== TPCF Integration + +RSR compliant repositories should operate under the Tri-Perimeter +Contribution Framework (TPCF): + +==== Perimeter 1: Inner Sanctum + +* Core maintainers +* Full repository access +* Decision-making authority + +==== Perimeter 2: Trusted Contributors + +* Regular contributors +* Review and merge permissions for specific areas +* Elevated trust level + +==== Perimeter 3: Community Sandbox + +* Open contribution +* Anyone can submit PRs +* All contributions reviewed + +=== Verification + +Projects can verify RSR compliance using: + +[source,bash] +---- +# Using Aletheia +aletheia /path/to/repository + +# Manual checklist +- Check all documentation files exist +- Verify .well-known directory +- Run build system +- Run tests +- Check for unsafe code +- Verify zero dependencies +---- + +=== Roadmap + +* *v0.1.0*: Bronze level specification (current) +* *v0.2.0*: Silver level specification +* *v0.3.0*: Gold level specification +* *v1.0.0*: Platinum level specification +* *v2.0.0*: Language-specific extensions + +=== References + +* https://www.rfc-editor.org/rfc/rfc9116.html[RFC 9116 - security.txt] +* https://keepachangelog.com/[Keep a Changelog] +* https://semver.org/[Semantic Versioning] +* https://www.contributor-covenant.org/[Contributor Covenant] +* https://gitlab.com/maa-framework/tpcf[TPCF Specification] + +=== Contributing to RSR + +The RSR specification itself is open for community input: + +* *Issues*: Suggest improvements +* *Discussions*: Debate requirements +* *Pull Requests*: Propose changes + +''''' + +*Version*: 0.1.0 *Last Updated*: 2025-11-22 *License*: CC-BY-4.0 +*Contact*: rsr@maa-framework.org diff --git a/aletheia/docs/RSR-SPECIFICATION.md b/aletheia/docs/RSR-SPECIFICATION.md deleted file mode 100644 index e1edf16..0000000 --- a/aletheia/docs/RSR-SPECIFICATION.md +++ /dev/null @@ -1,337 +0,0 @@ - -# RSR (Rhodium Standard Repository) Specification - -## Version 0.1.0 - -This document specifies the Rhodium Standard Repository (RSR) framework compliance levels and requirements. - -## Table of Contents - -1. [Overview](#overview) -2. [Compliance Levels](#compliance-levels) -3. [Bronze Level Requirements](#bronze-level-requirements) -4. [Silver Level Requirements](#silver-level-requirements) -5. [Gold Level Requirements](#gold-level-requirements) -6. [Platinum Level Requirements](#platinum-level-requirements) -7. [TPCF Integration](#tpcf-integration) - -## Overview - -The Rhodium Standard Repository (RSR) framework defines a graduated set of standards for software repositories, covering: - -- **Type Safety**: Compile-time correctness guarantees -- **Memory Safety**: Protection against memory vulnerabilities -- **Security**: Vulnerability disclosure and secure development -- **Documentation**: Comprehensive project documentation -- **Build System**: Reproducible, automated builds -- **Testing**: Comprehensive test coverage -- **Offline-First**: Air-gapped operation capability -- **Community**: Governance and contribution guidelines - -The name "Rhodium" references the precious metal's properties: -- **Rare**: High standards are uncommon -- **Valuable**: Quality software is precious -- **Durable**: Well-built software lasts -- **Reflective**: Standards help us see clearly - -## Compliance Levels - -### Level Hierarchy - -``` -Platinum (Highest) - ↑ - Gold - ↑ - Silver - ↑ - Bronze (Entry Level) -``` - -Each level builds upon the requirements of the previous level. - -## Bronze Level Requirements - -**Goal**: Establish foundational quality, security, and documentation standards. - -### 1. Type Safety - -**Required**: Compile-time type checking - -- **Rust**: Use Rust 2021 edition or later (built-in type safety) -- **Other Languages**: Must have static type checking enabled - - TypeScript: `strict: true` in tsconfig.json - - Python: Type hints + mypy strict mode - - Go: Standard compiler (built-in) - - Haskell: GHC (built-in) - -### 2. Memory Safety - -**Required**: Protection against memory vulnerabilities - -- **Rust**: Ownership model, zero `unsafe` blocks -- **Other Languages**: Memory-safe by design (GC languages) or formal verification - -### 3. Zero Dependencies (Language-Specific) - -**Required**: Minimal dependency footprint - -- **Interpreted Languages** (Python, JavaScript, Ruby): Use only standard library -- **Compiled Languages** (Rust, Go): Zero external dependencies -- **Exceptions**: Build tools (cargo, npm) and dev dependencies for testing are allowed - -### 4. Offline-First - -**Required**: Works completely air-gapped - -- No network calls in core functionality -- No external API dependencies -- No analytics or telemetry -- All resources bundled or locally available - -### 5. Documentation - -**Required Files**: - -- ✅ `README.md` - Project overview, quick start, usage -- ✅ `LICENSE.txt` - Open source license (MIT, Apache, GPL, etc.) -- ✅ `SECURITY.md` - Security policy and vulnerability disclosure -- ✅ `CONTRIBUTING.md` - Contribution guidelines -- ✅ `CODE_OF_CONDUCT.md` - Community standards -- ✅ `MAINTAINERS.md` - Project governance -- ✅ `CHANGELOG.md` - Version history (Keep a Changelog format) - -**Minimum Content**: - -- **README.md**: Purpose, quick start, installation, basic usage -- **LICENSE.txt**: Valid OSI-approved license -- **SECURITY.md**: Contact info, disclosure policy, response timeline -- **CONTRIBUTING.md**: How to contribute, code style, PR process -- **CODE_OF_CONDUCT.md**: Community standards (Contributor Covenant or similar) -- **MAINTAINERS.md**: Who maintains the project, decision process -- **CHANGELOG.md**: Version history following Keep a Changelog - -### 6. .well-known Directory - -**Required**: RFC 9116 compliance and metadata - -- ✅ `.well-known/security.txt` - RFC 9116 compliant security contact -- ✅ `.well-known/ai.txt` - AI training and usage policies -- ✅ `.well-known/humans.txt` - Human-readable attribution - -**security.txt Format**: -``` -Contact: mailto:security@example.org -Expires: 2026-01-01T00:00:00.000Z -Preferred-Languages: en -Canonical: https://example.org/.well-known/security.txt -Policy: https://example.org/security-policy -``` - -### 7. Build System - -**Required**: Automated, reproducible builds - -- ✅ `justfile` - Build automation (using Just) -- ✅ `flake.nix` - Nix reproducible builds -- ✅ `.gitlab-ci.yml` or `.github/workflows/` - CI/CD pipeline - -**Minimum Recipes**: -- `build` - Build the project -- `test` - Run all tests -- `lint` - Run linters -- `fmt` - Format code -- `check` - Run all checks - -### 8. Source Structure - -**Required**: Organized source code - -- ✅ `src/` directory - Source code -- ✅ `tests/` directory - Test files -- Clear separation of concerns -- Logical file organization - -### 9. Testing - -**Required**: Comprehensive test suite - -- Unit tests for core functionality -- Integration tests for workflows -- 100% test pass rate (no skipped tests in default run) -- Tests run in CI/CD - -### 10. Version Control - -**Required**: Git best practices - -- `.gitignore` - Ignore build artifacts -- Clear commit messages -- Semantic versioning (semver) -- Tagged releases - -### 11. License Compliance - -**Required**: Clear, OSI-approved licensing - -- Valid open source license -- License file in root -- Copyright notices -- Dual licensing allowed (e.g., MIT OR Apache-2.0) - -## Silver Level Requirements - -**Goal**: Add formal verification and advanced security. - -*(All Bronze requirements PLUS):* - -### 1. Formal Verification - -- Formal proofs of key algorithms -- Property-based testing (QuickCheck, PropTest) -- SPARK proofs (for Ada) -- TLA+ specifications (for distributed systems) - -### 2. Security Hardening - -- Security audit completed -- Dependency scanning (if dependencies exist) -- SBOM (Software Bill of Materials) generation -- Signed releases - -### 3. Advanced Documentation - -- Architecture Decision Records (ADRs) -- API documentation (rustdoc, JSDoc, etc.) -- Usage examples -- Performance benchmarks - -### 4. Enhanced Testing - -- Mutation testing (cargo-mutants) -- Fuzzing tests -- Coverage >80% -- Benchmark suite - -## Gold Level Requirements - -**Goal**: Multi-language verification and distributed systems support. - -*(All Silver requirements PLUS):* - -### 1. Multi-Language Support - -- FFI contracts for language boundaries -- WASM sandboxing for untrusted code -- Type-safe language interop - -### 2. Distributed Systems - -- CRDT-based state management -- Offline-first data sync -- Conflict-free merging -- TLA+ formal specifications - -### 3. Advanced Architecture - -- Modular plugin system -- Clean architecture boundaries -- Dependency injection -- Testable design - -## Platinum Level Requirements - -**Goal**: Production-grade enterprise systems with full CADRE integration. - -*(All Gold requirements PLUS):* - -### 1. CADRE Integration - -- Conflict-free Asynchronous Data Replication Engine -- Production-tested at scale -- Multi-datacenter support -- Disaster recovery tested - -### 2. Enterprise Features - -- Audit logging -- Role-based access control -- Compliance reporting (SOC2, GDPR, etc.) -- SLA guarantees - -### 3. Operational Excellence - -- Monitoring and observability -- Incident response playbooks -- Disaster recovery procedures -- 24/7 support capability - -## TPCF Integration - -RSR compliant repositories should operate under the Tri-Perimeter Contribution Framework (TPCF): - -### Perimeter 1: Inner Sanctum -- Core maintainers -- Full repository access -- Decision-making authority - -### Perimeter 2: Trusted Contributors -- Regular contributors -- Review and merge permissions for specific areas -- Elevated trust level - -### Perimeter 3: Community Sandbox -- Open contribution -- Anyone can submit PRs -- All contributions reviewed - -## Verification - -Projects can verify RSR compliance using: - -```bash -# Using Aletheia -aletheia /path/to/repository - -# Manual checklist -- Check all documentation files exist -- Verify .well-known directory -- Run build system -- Run tests -- Check for unsafe code -- Verify zero dependencies -``` - -## Roadmap - -- **v0.1.0**: Bronze level specification (current) -- **v0.2.0**: Silver level specification -- **v0.3.0**: Gold level specification -- **v1.0.0**: Platinum level specification -- **v2.0.0**: Language-specific extensions - -## References - -- [RFC 9116 - security.txt](https://www.rfc-editor.org/rfc/rfc9116.html) -- [Keep a Changelog](https://keepachangelog.com/) -- [Semantic Versioning](https://semver.org/) -- [Contributor Covenant](https://www.contributor-covenant.org/) -- [TPCF Specification](https://gitlab.com/maa-framework/tpcf) - -## Contributing to RSR - -The RSR specification itself is open for community input: - -- **Issues**: Suggest improvements -- **Discussions**: Debate requirements -- **Pull Requests**: Propose changes - ---- - -**Version**: 0.1.0 -**Last Updated**: 2025-11-22 -**License**: CC-BY-4.0 -**Contact**: rsr@maa-framework.org diff --git a/aletheia/docs/SILVER-LEVEL.md b/aletheia/docs/SILVER-LEVEL.adoc similarity index 58% rename from aletheia/docs/SILVER-LEVEL.md rename to aletheia/docs/SILVER-LEVEL.adoc index 2998f9d..ff3590b 100644 --- a/aletheia/docs/SILVER-LEVEL.md +++ b/aletheia/docs/SILVER-LEVEL.adoc @@ -1,29 +1,25 @@ - -# RSR Silver-Level Compliance (Future) +== RSR Silver-Level Compliance (Future) -**Status**: 🔄 Planned for v0.2.0 +*Status*: 🔄 Planned for v0.2.0 -This document outlines the planned Silver-level RSR compliance requirements. These extend Bronze-level requirements with formal verification and advanced security. +This document outlines the planned Silver-level RSR compliance +requirements. These extend Bronze-level requirements with formal +verification and advanced security. -## Overview +=== Overview -Silver-level compliance builds upon Bronze by adding: -- Formal verification of critical code paths -- Property-based testing -- Advanced security measures -- Enhanced documentation -- Performance guarantees +Silver-level compliance builds upon Bronze by adding: - Formal +verification of critical code paths - Property-based testing - Advanced +security measures - Enhanced documentation - Performance guarantees -## Requirements +=== Requirements -### 1. Formal Verification ⏳ +==== 1. Formal Verification ⏳ -#### SPARK Proofs (For Ada) +===== SPARK Proofs (For Ada) -```ada +[source,ada] +---- -- Example: Formally verified bounds checking procedure Check_Bounds(Index : Natural; Max : Natural) with Pre => Index <= Max, @@ -33,11 +29,12 @@ begin -- Proof: Index is always within bounds null; end Check_Bounds; -``` +---- -#### TLA+ Specifications (For Distributed Systems) +===== TLA+ Specifications (For Distributed Systems) -```tla +[source,tla] +---- ---- MODULE AletheiVerification ---- EXTENDS Integers, Sequences @@ -68,11 +65,12 @@ Next == Spec == Init /\ [][Next]_<> ==== -``` +---- -#### Property-Based Testing (QuickCheck/PropTest) +===== Property-Based Testing (QuickCheck/PropTest) -```rust +[source,rust] +---- // Example: Property-based test for check result accumulation #[cfg(test)] mod property_tests { @@ -103,20 +101,21 @@ mod property_tests { quickcheck(prop_check_count_never_decreases as fn(usize, Vec) -> TestResult); } } -``` +---- -### 2. Advanced Security ⏳ +==== 2. Advanced Security ⏳ -#### Security Audit +===== Security Audit -- **Requirement**: Professional third-party security audit -- **Scope**: Full codebase review -- **Report**: Public audit report published -- **Remediation**: All findings addressed +* *Requirement*: Professional third-party security audit +* *Scope*: Full codebase review +* *Report*: Public audit report published +* *Remediation*: All findings addressed -#### Dependency Scanning +===== Dependency Scanning -```toml +[source,toml] +---- # cargo-audit configuration [audit] deny = ["unmaintained", "unsound", "yanked"] @@ -126,11 +125,12 @@ vulnerability = "deny" unmaintained = "warn" unsound = "warn" yanked = "deny" -``` +---- -#### SBOM Generation +===== SBOM Generation -```yaml +[source,yaml] +---- # Software Bill of Materials (SBOM) # Generated automatically in CI/CD @@ -142,24 +142,26 @@ sbom: artifacts: paths: - sbom.json -``` +---- -#### Signed Releases +===== Signed Releases -```bash +[source,bash] +---- # GPG-signed releases git tag -s v0.2.0 -m "Release v0.2.0 (Silver-level)" git push --tags # Verify signature git tag -v v0.2.0 -``` +---- -### 3. Enhanced Documentation ⏳ +==== 3. Enhanced Documentation ⏳ -#### Architecture Decision Records (ADRs) +===== Architecture Decision Records (ADRs) -```markdown +[source,markdown] +---- # ADR 001: Use Rust for Implementation ## Status @@ -175,11 +177,12 @@ Use Rust for Aletheia implementation. - **Positive**: Memory safety, type safety, zero-cost abstractions - **Negative**: Steeper learning curve for contributors - **Neutral**: Requires Rust toolchain -``` +---- -#### API Documentation +===== API Documentation -```rust +[source,rust] +---- /// Verify repository against RSR Bronze-level standards. /// /// # Arguments @@ -208,23 +211,25 @@ Use Rust for Aletheia implementation. pub fn verify_repository(repo_path: &Path) -> Result { // Implementation } -``` +---- -### 4. Enhanced Testing ⏳ +==== 4. Enhanced Testing ⏳ -#### Mutation Testing +===== Mutation Testing -```bash +[source,bash] +---- # Using cargo-mutants cargo install cargo-mutants cargo mutants # Expected: High mutation kill rate (>80%) -``` +---- -#### Fuzzing +===== Fuzzing -```rust +[source,rust] +---- // Fuzz testing for path handling #[cfg(fuzzing)] use libfuzzer_sys::fuzz_target; @@ -236,11 +241,12 @@ fuzz_target!(|data: &[u8]| { let _ = verify_repository(&path); } }); -``` +---- -#### Coverage Targets +===== Coverage Targets -```yaml +[source,yaml] +---- # Minimum coverage: 80% coverage: stage: test @@ -252,13 +258,14 @@ coverage: echo "Coverage $COVERAGE < 80%" exit 1 fi -``` +---- -### 5. Performance Guarantees ⏳ +==== 5. Performance Guarantees ⏳ -#### Benchmarking Suite +===== Benchmarking Suite -```rust +[source,rust] +---- // Criterion benchmarks (if dependencies allowed) // For now, custom benchmarking @@ -268,11 +275,12 @@ const PERFORMANCE_TARGETS: &[(&str, u128)] = &[ ("Single compliance check", 50), // 50μs ("Full verification", 1000), // 1ms ]; -``` +---- -#### Memory Limits +===== Memory Limits -```rust +[source,rust] +---- // Maximum memory usage: 10MB for typical repository const MAX_MEMORY_BYTES: usize = 10 * 1024 * 1024; @@ -281,97 +289,102 @@ fn test_memory_usage() { // Track memory usage during verification // Fail if exceeds limit } -``` +---- -## Implementation Plan +=== Implementation Plan -### Phase 1: Verification Foundation (v0.2.0) +==== Phase 1: Verification Foundation (v0.2.0) -- [ ] Add property-based testing framework -- [ ] Implement TLA+ specification for verification logic -- [ ] Create formal proofs for critical functions -- [ ] Document all algorithms with invariants +* [ ] Add property-based testing framework +* [ ] Implement TLA+ specification for verification logic +* [ ] Create formal proofs for critical functions +* [ ] Document all algorithms with invariants -### Phase 2: Security Enhancement (v0.2.1) +==== Phase 2: Security Enhancement (v0.2.1) -- [ ] Complete professional security audit -- [ ] Implement SBOM generation -- [ ] Set up GPG signing for releases -- [ ] Add dependency scanning to CI/CD +* [ ] Complete professional security audit +* [ ] Implement SBOM generation +* [ ] Set up GPG signing for releases +* [ ] Add dependency scanning to CI/CD -### Phase 3: Documentation & Testing (v0.2.2) +==== Phase 3: Documentation & Testing (v0.2.2) -- [ ] Create ADRs for all major decisions -- [ ] Generate comprehensive API docs -- [ ] Implement mutation testing -- [ ] Add fuzz testing -- [ ] Achieve 80%+ code coverage +* [ ] Create ADRs for all major decisions +* [ ] Generate comprehensive API docs +* [ ] Implement mutation testing +* [ ] Add fuzz testing +* [ ] Achieve 80%+ code coverage -### Phase 4: Performance & Polish (v0.2.3) +==== Phase 4: Performance & Polish (v0.2.3) -- [ ] Comprehensive benchmark suite -- [ ] Memory profiling -- [ ] Performance regression tests -- [ ] Optimization based on profiling +* [ ] Comprehensive benchmark suite +* [ ] Memory profiling +* [ ] Performance regression tests +* [ ] Optimization based on profiling -## Verification Checklist +=== Verification Checklist Silver-level compliance requires: -- ✅ All Bronze-level requirements met -- ⏳ Formal verification of critical code -- ⏳ Property-based tests for all public APIs -- ⏳ Professional security audit completed -- ⏳ SBOM generated and published -- ⏳ Releases GPG-signed -- ⏳ ADRs for all major decisions -- ⏳ API documentation complete -- ⏳ Mutation testing implemented -- ⏳ Fuzz testing added -- ⏳ Code coverage >80% -- ⏳ Performance benchmarks established -- ⏳ Memory usage profiled and limited - -## Migration from Bronze +* ✅ All Bronze-level requirements met +* ⏳ Formal verification of critical code +* ⏳ Property-based tests for all public APIs +* ⏳ Professional security audit completed +* ⏳ SBOM generated and published +* ⏳ Releases GPG-signed +* ⏳ ADRs for all major decisions +* ⏳ API documentation complete +* ⏳ Mutation testing implemented +* ⏳ Fuzz testing added +* ⏳ Code coverage >80% +* ⏳ Performance benchmarks established +* ⏳ Memory usage profiled and limited + +=== Migration from Bronze Existing Bronze-level repositories can upgrade to Silver by: -1. Adding property-based tests -2. Creating formal specifications -3. Completing security audit -4. Generating SBOM -5. Setting up signed releases -6. Writing ADRs -7. Expanding documentation -8. Adding mutation/fuzz tests -9. Achieving coverage targets -10. Establishing performance baselines - -## Tools Required - -### Formal Verification -- TLA+ Toolbox -- SPARK Pro (for Ada) -- Coq or Isabelle (for proof assistants) - -### Testing -- cargo-mutants (mutation testing) -- cargo-fuzz (fuzz testing) -- cargo-tarpaulin (coverage) - -### Security -- cargo-audit (dependency scanning) -- cargo-sbom (SBOM generation) -- GPG (release signing) - -### Performance -- cargo-bench (benchmarking) -- valgrind (memory profiling) -- perf (CPU profiling) - -## Example Silver-Level Repository - -``` +[arabic] +. Adding property-based tests +. Creating formal specifications +. Completing security audit +. Generating SBOM +. Setting up signed releases +. Writing ADRs +. Expanding documentation +. Adding mutation/fuzz tests +. Achieving coverage targets +. Establishing performance baselines + +=== Tools Required + +==== Formal Verification + +* TLA+ Toolbox +* SPARK Pro (for Ada) +* Coq or Isabelle (for proof assistants) + +==== Testing + +* cargo-mutants (mutation testing) +* cargo-fuzz (fuzz testing) +* cargo-tarpaulin (coverage) + +==== Security + +* cargo-audit (dependency scanning) +* cargo-sbom (SBOM generation) +* GPG (release signing) + +==== Performance + +* cargo-bench (benchmarking) +* valgrind (memory profiling) +* perf (CPU profiling) + +=== Example Silver-Level Repository + +.... silver-example/ ├── docs/ │ ├── adr/ # Architecture Decision Records @@ -394,18 +407,17 @@ silver-example/ ├── .cargo/ │ └── audit.toml # cargo-audit config └── (All Bronze-level files) -``` +.... -## Resources +=== Resources -- [TLA+ Homepage](https://lamport.azurewebsites.net/tla/tla.html) -- [SPARK Ada](https://www.adacore.com/about-spark) -- [QuickCheck for Rust](https://github.com/BurntSushi/quickcheck) -- [Mutation Testing](https://github.com/sourcefrog/cargo-mutants) -- [Fuzzing Book](https://www.fuzzingbook.org/) +* https://lamport.azurewebsites.net/tla/tla.html[TLA+ Homepage] +* https://www.adacore.com/about-spark[SPARK Ada] +* https://github.com/BurntSushi/quickcheck[QuickCheck for Rust] +* https://github.com/sourcefrog/cargo-mutants[Mutation Testing] +* https://www.fuzzingbook.org/[Fuzzing Book] ---- +''''' -**Status**: Planning phase -**Target Release**: v0.2.0 -**Timeline**: TBD based on community feedback +*Status*: Planning phase *Target Release*: v0.2.0 *Timeline*: TBD based +on community feedback diff --git a/aletheia/extraction/rhodium-pipeline/docs/VALUE-CHAIN-POLICY.md b/aletheia/docs/VALUE-CHAIN-POLICY.adoc similarity index 56% rename from aletheia/extraction/rhodium-pipeline/docs/VALUE-CHAIN-POLICY.md rename to aletheia/docs/VALUE-CHAIN-POLICY.adoc index 192eb61..03661ca 100644 --- a/aletheia/extraction/rhodium-pipeline/docs/VALUE-CHAIN-POLICY.md +++ b/aletheia/docs/VALUE-CHAIN-POLICY.adoc @@ -1,32 +1,40 @@ - -# Hyperpolymath Project Value Chain Policy +== Hyperpolymath Project Value Chain Policy -This document defines the standard value chain model for all Hyperpolymath projects. It is based on Porter's Value Chain framework, adapted for software development. +This document defines the standard value chain model for all +Hyperpolymath projects. It is based on Porter’s Value Chain framework, +adapted for software development. -## Overview +=== Overview Every Hyperpolymath project has two types of activities: -1. **Support Activities** - Cross-cutting concerns that apply at all stages -2. **Primary Activities** - The value flow from inputs to outputs +[arabic] +. *Support Activities* - Cross-cutting concerns that apply at all stages +. *Primary Activities* - The value flow from inputs to outputs -## Support Activities (Cross-Cutting) +=== Support Activities (Cross-Cutting) These apply horizontally across all primary activities: -| Activity | Description | Tools | -|----------|-------------|-------| -| **Technology** | CCCP stack (containers, runtime, shell) | Cerro Torre, Svalinn, Valence Shell | -| **Formalizations** | Proofs, validation, verification | Absolute Zero, Echidna, Coq/Lean/Z3 | -| **Standards** | Repository and code standards | RSR, CCCP, .scm files, Palimpsest | -| **Infrastructure** | Build, CI/CD, deployment | mustfile, rhodium-pipeline, GitLab CI | +[width="100%",cols="34%,43%,23%",options="header",] +|=== +|Activity |Description |Tools +|*Technology* |CCCP stack (containers, runtime, shell) |Cerro Torre, +Svalinn, Valence Shell -## Primary Activities (Value Flow) +|*Formalizations* |Proofs, validation, verification |Absolute Zero, +Echidna, Coq/Lean/Z3 -``` +|*Standards* |Repository and code standards |RSR, CCCP, .scm files, +Palimpsest + +|*Infrastructure* |Build, CI/CD, deployment |mustfile, rhodium-pipeline, +GitLab CI +|=== + +=== Primary Activities (Value Flow) + +.... ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ INBOUND │ │ │ │ OUTBOUND │ │ MARKETING │ │ │ │ LOGISTICS │──▶│ OPERATIONS │──▶│ LOGISTICS │──▶│ & SALES │──▶│ SERVICE │ @@ -34,121 +42,133 @@ These apply horizontally across all primary activities: │ Theoretical │ │ Core │ │ Outputs │ │ Standards │ │ Maintenance │ │ foundations │ │ project │ │ & exports │ │ & business │ │ & ops │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ -``` +.... + +==== 1. Inbound Logistics + +*What*: Foundational inputs specific to the project’s domain + +Examples: - For Aletheia: Absolute Zero (CNO proofs, Landauer, Bennett) +- For rhodibot: RSR specification - For oikos: Economic/ecological +theory + +==== 2. Operations -### 1. Inbound Logistics -**What**: Foundational inputs specific to the project's domain +*What*: The core project work - what this repository actually builds -Examples: -- For Aletheia: Absolute Zero (CNO proofs, Landauer, Bennett) -- For rhodibot: RSR specification -- For oikos: Economic/ecological theory +Examples: - For Aletheia: Reversible Minix research (r-Minix precursor) +- For rhodibot: Compliance checking engine - For oikos: +Economic/ecological analyzer -### 2. Operations -**What**: The core project work - what this repository actually builds +==== 3. Outbound Logistics -Examples: -- For Aletheia: Reversible Minix research (r-Minix precursor) -- For rhodibot: Compliance checking engine -- For oikos: Economic/ecological analyzer +*What*: Where outputs go - integration with CCCP stack or other projects -### 3. Outbound Logistics -**What**: Where outputs go - integration with CCCP stack or other projects +Examples: - To CCCP technology stack (containers, runtime) - To +downstream projects - To future implementations (e.g., Aletheia → +r-Minix) -Examples: -- To CCCP technology stack (containers, runtime) -- To downstream projects -- To future implementations (e.g., Aletheia → r-Minix) +==== 4. Marketing & Sales -### 4. Marketing & Sales -**What**: RSR ecosystem, maintenance strategies, business extensions +*What*: RSR ecosystem, maintenance strategies, business extensions -Components: -- **Corrective maintenance** - Bug fixes, issue resolution -- **Adaptive maintenance** - Platform/environment changes -- **Perfective maintenance** - Improvements, optimizations +Components: - *Corrective maintenance* - Bug fixes, issue resolution - +*Adaptive maintenance* - Platform/environment changes - *Perfective +maintenance* - Improvements, optimizations -### 5. Service -**What**: Ongoing operational support via automation +==== 5. Service -Tools: -- **feedback-o-tron** - Feedback collection and processing -- **cicd-hyper-a** - CI/CD automation -- **robot-repo-automaton** - Repository automation +*What*: Ongoing operational support via automation -## Two Input Systems +Tools: - *feedback-o-tron* - Feedback collection and processing - +*cicd-hyper-a* - CI/CD automation - *robot-repo-automaton* - Repository +automation + +=== Two Input Systems All projects receive inputs from two complementary systems: -### RSR - Rhodium Standard Repositories -- **Layer**: Repository organization -- **Handles**: Documentation, security.txt, CI/CD, build systems -- **Tools**: rhodium-standard-repositories, rsr-template-repo, rhodibot, rhodium-pipeline +==== RSR - Rhodium Standard Repositories + +* *Layer*: Repository organization +* *Handles*: Documentation, security.txt, CI/CD, build systems +* *Tools*: rhodium-standard-repositories, rsr-template-repo, rhodibot, +rhodium-pipeline + +==== CCCP - Campaign for Cooling Coding and Programming -### CCCP - Campaign for Cooling Coding and Programming -- **Layer**: Technology stack and code -- **Handles**: Languages, containers, integrations, efficiency -- **Tools**: Cerro Torre, Svalinn, Valence Shell, rescript-tea, cadre-router +* *Layer*: Technology stack and code +* *Handles*: Languages, containers, integrations, efficiency +* *Tools*: Cerro Torre, Svalinn, Valence Shell, rescript-tea, +cadre-router -## Project-Specific Foundations +=== Project-Specific Foundations Each project may have domain-specific foundational inputs: -| Project | Foundational Input | -|---------|-------------------| -| Aletheia | Absolute Zero (CNO proofs, reversibility theory) | -| Valence Shell | Absolute Zero (filesystem CNO proofs) | -| Oikos | Economic/ecological theory | -| Echidnabot | Formal methods, SAT/SMT solving | +[cols=",",options="header",] +|=== +|Project |Foundational Input +|Aletheia |Absolute Zero (CNO proofs, reversibility theory) +|Valence Shell |Absolute Zero (filesystem CNO proofs) +|Oikos |Economic/ecological theory +|Echidnabot |Formal methods, SAT/SMT solving +|=== -## Standard Files +=== Standard Files All properly configured projects include: -### AI Support Files (.scm - Guile Scheme) -- `META.scm` - Project metadata -- `ECOSYSTEM.scm` - Ecosystem connections -- `STATE.scm` - Current project state -- `PLAYBOOK.scm` - Development workflows -- `AGENTIC.scm` - AI agent configuration -- `NEUROSYM.scm` - Neurosymbolic settings +==== AI Support Files (.scm - Guile Scheme) + +* `+META.scm+` - Project metadata +* `+ECOSYSTEM.scm+` - Ecosystem connections +* `+STATE.scm+` - Current project state +* `+PLAYBOOK.scm+` - Development workflows +* `+AGENTIC.scm+` - AI agent configuration +* `+NEUROSYM.scm+` - Neurosymbolic settings + +==== Build & Standards + +* `+mustfile+` - Build/task automation +* RSR compliance files (README, LICENSE, SECURITY.md, etc.) +* `+.well-known/+` directory -### Build & Standards -- `mustfile` - Build/task automation -- RSR compliance files (README, LICENSE, SECURITY.md, etc.) -- `.well-known/` directory +==== Licensing -### Licensing -- **Base**: MIT or AGPL (user choice) -- **Overlay**: Palimpsest License (optional but encouraged) +* *Base*: MIT or AGPL (user choice) +* *Overlay*: Palimpsest License (optional but encouraged) -## Bot Ecosystem +=== Bot Ecosystem Projects are supported by bots operating in multiple modes: -| Bot | Role | -|-----|------| -| **rhodibot** | RSR compliance (consultant, advisor, regulator) | -| **echidnabot** | Formal proof validation | -| **oikos bot** | Economic/ecological analysis | +[cols=",",options="header",] +|=== +|Bot |Role +|*rhodibot* |RSR compliance (consultant, advisor, regulator) +|*echidnabot* |Formal proof validation +|*oikos bot* |Economic/ecological analysis +|=== -Bots are **self-referential** - they validate their own code. +Bots are *self-referential* - they validate their own code. -## Applying This Policy +=== Applying This Policy When setting up a new project: -1. Start with `rsr-template-repo` -2. Apply customizations via `repo-customiser` -3. Identify the project's **foundational input** (inbound logistics) -4. Define the **core operations** (what this project builds) -5. Specify **outbound targets** (where outputs go) -6. Configure **maintenance strategy** (corrective/adaptive/perfective) -7. Set up **service automation** (feedback-o-tron, cicd-hyper-a, etc.) +[arabic] +. Start with `+rsr-template-repo+` +. Apply customizations via `+repo-customiser+` +. Identify the project’s *foundational input* (inbound logistics) +. Define the *core operations* (what this project builds) +. Specify *outbound targets* (where outputs go) +. Configure *maintenance strategy* (corrective/adaptive/perfective) +. Set up *service automation* (feedback-o-tron, cicd-hyper-a, etc.) -## Diagram +=== Diagram -``` +.... ┌─────────────────────────────────────────────────────────────────────────────────────┐ │ SUPPORT ACTIVITIES (Cross-cutting) │ ├─────────────────────────────────────────────────────────────────────────────────────┤ @@ -176,8 +196,9 @@ When setting up a new project: │ ═══════════════════════════════════════════════════════════════════════════════▶ │ │ VALUE CREATION MARGIN │ └─────────────────────────────────────────────────────────────────────────────────────┘ -``` +.... ---- +''''' -*This policy applies to all Hyperpolymath projects and their satellite repositories.* +_This policy applies to all Hyperpolymath projects and their satellite +repositories._ diff --git a/aletheia/extraction/rhodibot/README.md b/aletheia/extraction/rhodibot/README.adoc similarity index 63% rename from aletheia/extraction/rhodibot/README.md rename to aletheia/extraction/rhodibot/README.adoc index ccf4c6f..04ec73a 100644 --- a/aletheia/extraction/rhodibot/README.md +++ b/aletheia/extraction/rhodibot/README.adoc @@ -1,25 +1,28 @@ - -# Rhodibot +== Rhodibot -[![RSR Bronze](https://img.shields.io/badge/RSR-Bronze-cd7f32)](https://github.com/hyperpolymath/rhodium-standard-repositories) +https://github.com/hyperpolymath/rhodium-standard-repositories[image:https://img.shields.io/badge/RSR-Bronze-cd7f32[RSR +Bronze]] -> **Rho**dium Stan**d**ard Repos**i**tory **Bot** +____ +**Rho**dium Stan**d**ard Repos**i**tory *Bot* +____ -Rhodibot is like Dependabot, but for repository standards compliance instead of dependency updates. It acts as a consultant, regulator, advisor, and policy manager for RSR (Rhodium Standard Repository) compliance. +Rhodibot is like Dependabot, but for repository standards compliance +instead of dependency updates. It acts as a consultant, regulator, +advisor, and policy manager for RSR (Rhodium Standard Repository) +compliance. -## What Rhodibot Does +=== What Rhodibot Does -- **Checks** repositories for RSR compliance (Bronze, Silver, Gold, Platinum levels) -- **Reports** issues via CI/CD annotations (GitHub Actions, GitLab CI) -- **Generates** badges and conformity documents -- **Advises** on compliance gaps and how to fix them +* *Checks* repositories for RSR compliance (Bronze, Silver, Gold, +Platinum levels) +* *Reports* issues via CI/CD annotations (GitHub Actions, GitLab CI) +* *Generates* badges and conformity documents +* *Advises* on compliance gaps and how to fix them -## Ecosystem Architecture +=== Ecosystem Architecture -``` +.... ┌─────────────────────────────────────┐ │ rhodium-standard-repositories │ │ (The RSR Specification) │ @@ -47,15 +50,20 @@ Rhodibot is like Dependabot, but for repository standards compliance instead of │ • oikos (Economic/Ecological) │ │ • Custom organization standards │ └─────────────────────────────────────┘ -``` +.... -**Satellite of:** [rhodium-standard-repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) +*Satellite of:* +https://github.com/hyperpolymath/rhodium-standard-repositories[rhodium-standard-repositories] -Rhodibot sits at the center of RSR compliance enforcement, connecting templates, pipelines, and the standard. It can be invoked by CI/CD systems, used interactively, or integrated via the repo-customiser C4 control point. +Rhodibot sits at the center of RSR compliance enforcement, connecting +templates, pipelines, and the standard. It can be invoked by CI/CD +systems, used interactively, or integrated via the repo-customiser C4 +control point. -## Quick Start +=== Quick Start -```bash +[source,bash] +---- # Install cargo install rhodibot @@ -67,13 +75,14 @@ rhodibot badge # Generate conformity document rhodibot conformity -``` +---- -## CI/CD Integration +=== CI/CD Integration -### GitHub Actions +==== GitHub Actions -```yaml +[source,yaml] +---- name: RSR Compliance on: [push, pull_request] @@ -86,21 +95,22 @@ jobs: with: path: '.' fail-on-warning: true -``` +---- -### GitLab CI +==== GitLab CI -```yaml +[source,yaml] +---- rhodibot: stage: test image: hyperpolymath/rhodibot:latest script: - rhodibot check . -``` +---- -## CLI Usage +=== CLI Usage -``` +.... rhodibot [COMMAND] [OPTIONS] [PATH] COMMANDS: @@ -120,60 +130,69 @@ EXIT CODES: 2 Security - Critical security warnings detected 3 Error - Invalid path provided 4 Error - Invalid arguments -``` +.... -## Design Principles +=== Design Principles -1. **Zero Dependencies** - Only Rust standard library (RSR Bronze compliant) -2. **Zero Unsafe Code** - 100% safe Rust -3. **Offline-First** - Works without network access -4. **Security-Aware** - Detects symlink attacks, validates paths -5. **CI/CD Native** - First-class GitHub Actions and GitLab CI support +[arabic] +. *Zero Dependencies* - Only Rust standard library (RSR Bronze +compliant) +. *Zero Unsafe Code* - 100% safe Rust +. *Offline-First* - Works without network access +. *Security-Aware* - Detects symlink attacks, validates paths +. *CI/CD Native* - First-class GitHub Actions and GitLab CI support -## Bronze Compliance Checks +=== Bronze Compliance Checks Rhodibot checks for these Bronze-level requirements: -### Documentation -- README.md (or README.adoc) -- LICENSE.txt -- SECURITY.md -- CONTRIBUTING.md -- CODE_OF_CONDUCT.md -- MAINTAINERS.md -- CHANGELOG.md +==== Documentation -### .well-known Directory -- .well-known/security.txt (RFC 9116) -- .well-known/ai.txt -- .well-known/humans.txt +* README.md (or README.adoc) +* LICENSE.txt +* SECURITY.md +* CONTRIBUTING.md +* CODE_OF_CONDUCT.md +* MAINTAINERS.md +* CHANGELOG.md -### Build System -- Justfile -- flake.nix -- .gitlab-ci.yml +==== .well-known Directory -### Source Structure -- src/ directory -- tests/ directory +* .well-known/security.txt (RFC 9116) +* .well-known/ai.txt +* .well-known/humans.txt -## Security +==== Build System + +* Justfile +* flake.nix +* .gitlab-ci.yml + +==== Source Structure + +* src/ directory +* tests/ directory + +=== Security Rhodibot includes security features: -- **Symlink Detection**: Warns about symlinks that point outside the repository -- **Path Validation**: Prevents directory traversal attacks -- **No Network**: Cannot exfiltrate data (offline-first design) -- **Zero Dependencies**: No supply chain attack surface +* *Symlink Detection*: Warns about symlinks that point outside the +repository +* *Path Validation*: Prevents directory traversal attacks +* *No Network*: Cannot exfiltrate data (offline-first design) +* *Zero Dependencies*: No supply chain attack surface -## License +=== License MIT OR Apache-2.0 -## Contributing +=== Contributing -See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. +See CONTRIBUTING.md for guidelines. ---- +''''' -*Part of the [Rhodium Standard](https://github.com/hyperpolymath/rhodium-standard-repositories) ecosystem* +_Part of the +https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard] ecosystem_ diff --git a/aletheia/extraction/rhodibot/docs/VALUE-CHAIN-POLICY.md b/aletheia/extraction/rhodibot/docs/VALUE-CHAIN-POLICY.adoc similarity index 56% rename from aletheia/extraction/rhodibot/docs/VALUE-CHAIN-POLICY.md rename to aletheia/extraction/rhodibot/docs/VALUE-CHAIN-POLICY.adoc index 192eb61..03661ca 100644 --- a/aletheia/extraction/rhodibot/docs/VALUE-CHAIN-POLICY.md +++ b/aletheia/extraction/rhodibot/docs/VALUE-CHAIN-POLICY.adoc @@ -1,32 +1,40 @@ - -# Hyperpolymath Project Value Chain Policy +== Hyperpolymath Project Value Chain Policy -This document defines the standard value chain model for all Hyperpolymath projects. It is based on Porter's Value Chain framework, adapted for software development. +This document defines the standard value chain model for all +Hyperpolymath projects. It is based on Porter’s Value Chain framework, +adapted for software development. -## Overview +=== Overview Every Hyperpolymath project has two types of activities: -1. **Support Activities** - Cross-cutting concerns that apply at all stages -2. **Primary Activities** - The value flow from inputs to outputs +[arabic] +. *Support Activities* - Cross-cutting concerns that apply at all stages +. *Primary Activities* - The value flow from inputs to outputs -## Support Activities (Cross-Cutting) +=== Support Activities (Cross-Cutting) These apply horizontally across all primary activities: -| Activity | Description | Tools | -|----------|-------------|-------| -| **Technology** | CCCP stack (containers, runtime, shell) | Cerro Torre, Svalinn, Valence Shell | -| **Formalizations** | Proofs, validation, verification | Absolute Zero, Echidna, Coq/Lean/Z3 | -| **Standards** | Repository and code standards | RSR, CCCP, .scm files, Palimpsest | -| **Infrastructure** | Build, CI/CD, deployment | mustfile, rhodium-pipeline, GitLab CI | +[width="100%",cols="34%,43%,23%",options="header",] +|=== +|Activity |Description |Tools +|*Technology* |CCCP stack (containers, runtime, shell) |Cerro Torre, +Svalinn, Valence Shell -## Primary Activities (Value Flow) +|*Formalizations* |Proofs, validation, verification |Absolute Zero, +Echidna, Coq/Lean/Z3 -``` +|*Standards* |Repository and code standards |RSR, CCCP, .scm files, +Palimpsest + +|*Infrastructure* |Build, CI/CD, deployment |mustfile, rhodium-pipeline, +GitLab CI +|=== + +=== Primary Activities (Value Flow) + +.... ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ INBOUND │ │ │ │ OUTBOUND │ │ MARKETING │ │ │ │ LOGISTICS │──▶│ OPERATIONS │──▶│ LOGISTICS │──▶│ & SALES │──▶│ SERVICE │ @@ -34,121 +42,133 @@ These apply horizontally across all primary activities: │ Theoretical │ │ Core │ │ Outputs │ │ Standards │ │ Maintenance │ │ foundations │ │ project │ │ & exports │ │ & business │ │ & ops │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ -``` +.... + +==== 1. Inbound Logistics + +*What*: Foundational inputs specific to the project’s domain + +Examples: - For Aletheia: Absolute Zero (CNO proofs, Landauer, Bennett) +- For rhodibot: RSR specification - For oikos: Economic/ecological +theory + +==== 2. Operations -### 1. Inbound Logistics -**What**: Foundational inputs specific to the project's domain +*What*: The core project work - what this repository actually builds -Examples: -- For Aletheia: Absolute Zero (CNO proofs, Landauer, Bennett) -- For rhodibot: RSR specification -- For oikos: Economic/ecological theory +Examples: - For Aletheia: Reversible Minix research (r-Minix precursor) +- For rhodibot: Compliance checking engine - For oikos: +Economic/ecological analyzer -### 2. Operations -**What**: The core project work - what this repository actually builds +==== 3. Outbound Logistics -Examples: -- For Aletheia: Reversible Minix research (r-Minix precursor) -- For rhodibot: Compliance checking engine -- For oikos: Economic/ecological analyzer +*What*: Where outputs go - integration with CCCP stack or other projects -### 3. Outbound Logistics -**What**: Where outputs go - integration with CCCP stack or other projects +Examples: - To CCCP technology stack (containers, runtime) - To +downstream projects - To future implementations (e.g., Aletheia → +r-Minix) -Examples: -- To CCCP technology stack (containers, runtime) -- To downstream projects -- To future implementations (e.g., Aletheia → r-Minix) +==== 4. Marketing & Sales -### 4. Marketing & Sales -**What**: RSR ecosystem, maintenance strategies, business extensions +*What*: RSR ecosystem, maintenance strategies, business extensions -Components: -- **Corrective maintenance** - Bug fixes, issue resolution -- **Adaptive maintenance** - Platform/environment changes -- **Perfective maintenance** - Improvements, optimizations +Components: - *Corrective maintenance* - Bug fixes, issue resolution - +*Adaptive maintenance* - Platform/environment changes - *Perfective +maintenance* - Improvements, optimizations -### 5. Service -**What**: Ongoing operational support via automation +==== 5. Service -Tools: -- **feedback-o-tron** - Feedback collection and processing -- **cicd-hyper-a** - CI/CD automation -- **robot-repo-automaton** - Repository automation +*What*: Ongoing operational support via automation -## Two Input Systems +Tools: - *feedback-o-tron* - Feedback collection and processing - +*cicd-hyper-a* - CI/CD automation - *robot-repo-automaton* - Repository +automation + +=== Two Input Systems All projects receive inputs from two complementary systems: -### RSR - Rhodium Standard Repositories -- **Layer**: Repository organization -- **Handles**: Documentation, security.txt, CI/CD, build systems -- **Tools**: rhodium-standard-repositories, rsr-template-repo, rhodibot, rhodium-pipeline +==== RSR - Rhodium Standard Repositories + +* *Layer*: Repository organization +* *Handles*: Documentation, security.txt, CI/CD, build systems +* *Tools*: rhodium-standard-repositories, rsr-template-repo, rhodibot, +rhodium-pipeline + +==== CCCP - Campaign for Cooling Coding and Programming -### CCCP - Campaign for Cooling Coding and Programming -- **Layer**: Technology stack and code -- **Handles**: Languages, containers, integrations, efficiency -- **Tools**: Cerro Torre, Svalinn, Valence Shell, rescript-tea, cadre-router +* *Layer*: Technology stack and code +* *Handles*: Languages, containers, integrations, efficiency +* *Tools*: Cerro Torre, Svalinn, Valence Shell, rescript-tea, +cadre-router -## Project-Specific Foundations +=== Project-Specific Foundations Each project may have domain-specific foundational inputs: -| Project | Foundational Input | -|---------|-------------------| -| Aletheia | Absolute Zero (CNO proofs, reversibility theory) | -| Valence Shell | Absolute Zero (filesystem CNO proofs) | -| Oikos | Economic/ecological theory | -| Echidnabot | Formal methods, SAT/SMT solving | +[cols=",",options="header",] +|=== +|Project |Foundational Input +|Aletheia |Absolute Zero (CNO proofs, reversibility theory) +|Valence Shell |Absolute Zero (filesystem CNO proofs) +|Oikos |Economic/ecological theory +|Echidnabot |Formal methods, SAT/SMT solving +|=== -## Standard Files +=== Standard Files All properly configured projects include: -### AI Support Files (.scm - Guile Scheme) -- `META.scm` - Project metadata -- `ECOSYSTEM.scm` - Ecosystem connections -- `STATE.scm` - Current project state -- `PLAYBOOK.scm` - Development workflows -- `AGENTIC.scm` - AI agent configuration -- `NEUROSYM.scm` - Neurosymbolic settings +==== AI Support Files (.scm - Guile Scheme) + +* `+META.scm+` - Project metadata +* `+ECOSYSTEM.scm+` - Ecosystem connections +* `+STATE.scm+` - Current project state +* `+PLAYBOOK.scm+` - Development workflows +* `+AGENTIC.scm+` - AI agent configuration +* `+NEUROSYM.scm+` - Neurosymbolic settings + +==== Build & Standards + +* `+mustfile+` - Build/task automation +* RSR compliance files (README, LICENSE, SECURITY.md, etc.) +* `+.well-known/+` directory -### Build & Standards -- `mustfile` - Build/task automation -- RSR compliance files (README, LICENSE, SECURITY.md, etc.) -- `.well-known/` directory +==== Licensing -### Licensing -- **Base**: MIT or AGPL (user choice) -- **Overlay**: Palimpsest License (optional but encouraged) +* *Base*: MIT or AGPL (user choice) +* *Overlay*: Palimpsest License (optional but encouraged) -## Bot Ecosystem +=== Bot Ecosystem Projects are supported by bots operating in multiple modes: -| Bot | Role | -|-----|------| -| **rhodibot** | RSR compliance (consultant, advisor, regulator) | -| **echidnabot** | Formal proof validation | -| **oikos bot** | Economic/ecological analysis | +[cols=",",options="header",] +|=== +|Bot |Role +|*rhodibot* |RSR compliance (consultant, advisor, regulator) +|*echidnabot* |Formal proof validation +|*oikos bot* |Economic/ecological analysis +|=== -Bots are **self-referential** - they validate their own code. +Bots are *self-referential* - they validate their own code. -## Applying This Policy +=== Applying This Policy When setting up a new project: -1. Start with `rsr-template-repo` -2. Apply customizations via `repo-customiser` -3. Identify the project's **foundational input** (inbound logistics) -4. Define the **core operations** (what this project builds) -5. Specify **outbound targets** (where outputs go) -6. Configure **maintenance strategy** (corrective/adaptive/perfective) -7. Set up **service automation** (feedback-o-tron, cicd-hyper-a, etc.) +[arabic] +. Start with `+rsr-template-repo+` +. Apply customizations via `+repo-customiser+` +. Identify the project’s *foundational input* (inbound logistics) +. Define the *core operations* (what this project builds) +. Specify *outbound targets* (where outputs go) +. Configure *maintenance strategy* (corrective/adaptive/perfective) +. Set up *service automation* (feedback-o-tron, cicd-hyper-a, etc.) -## Diagram +=== Diagram -``` +.... ┌─────────────────────────────────────────────────────────────────────────────────────┐ │ SUPPORT ACTIVITIES (Cross-cutting) │ ├─────────────────────────────────────────────────────────────────────────────────────┤ @@ -176,8 +196,9 @@ When setting up a new project: │ ═══════════════════════════════════════════════════════════════════════════════▶ │ │ VALUE CREATION MARGIN │ └─────────────────────────────────────────────────────────────────────────────────────┘ -``` +.... ---- +''''' -*This policy applies to all Hyperpolymath projects and their satellite repositories.* +_This policy applies to all Hyperpolymath projects and their satellite +repositories._ diff --git a/aletheia/extraction/rhodium-pipeline/README.md b/aletheia/extraction/rhodium-pipeline/README.adoc similarity index 71% rename from aletheia/extraction/rhodium-pipeline/README.md rename to aletheia/extraction/rhodium-pipeline/README.adoc index ccf3e3e..a2a4820 100644 --- a/aletheia/extraction/rhodium-pipeline/README.md +++ b/aletheia/extraction/rhodium-pipeline/README.adoc @@ -1,23 +1,21 @@ - -# Rhodium Pipeline +== Rhodium Pipeline -[![RSR Bronze](https://img.shields.io/badge/RSR-Bronze-cd7f32)](https://github.com/hyperpolymath/rhodium-standard-repositories) +https://github.com/hyperpolymath/rhodium-standard-repositories[image:https://img.shields.io/badge/RSR-Bronze-cd7f32[RSR +Bronze]] CI/CD pipeline generator and templates for RSR-compliant projects. -## What Rhodium Pipeline Does +=== What Rhodium Pipeline Does -- **Generates** CI/CD configuration files (GitHub Actions, GitLab CI) -- **Templates** for RSR-compliant pipelines -- **Validates** existing pipeline configurations -- **Enforces** RSR build requirements (zero dependencies, zero unsafe, etc.) +* *Generates* CI/CD configuration files (GitHub Actions, GitLab CI) +* *Templates* for RSR-compliant pipelines +* *Validates* existing pipeline configurations +* *Enforces* RSR build requirements (zero dependencies, zero unsafe, +etc.) -## Ecosystem Architecture +=== Ecosystem Architecture -``` +.... ┌─────────────────────────────────────┐ │ rhodium-standard-repositories │ │ (The RSR Specification) │ @@ -52,15 +50,19 @@ CI/CD pipeline generator and templates for RSR-compliant projects. │ (C4 Control Point - Generic) │ │ Works with ANY .scm standard │ └─────────────────────────────────────┘ -``` +.... -**Satellite of:** [rhodium-standard-repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) +*Satellite of:* +https://github.com/hyperpolymath/rhodium-standard-repositories[rhodium-standard-repositories] -Rhodium Pipeline generates CI/CD configurations that enforce RSR compliance automatically. It works with rhodibot to verify compliance during pipeline runs. +Rhodium Pipeline generates CI/CD configurations that enforce RSR +compliance automatically. It works with rhodibot to verify compliance +during pipeline runs. -## Quick Start +=== Quick Start -```bash +[source,bash] +---- # Install cargo install rhodium-pipeline @@ -72,44 +74,49 @@ rhodium-pipeline generate gitlab # Validate existing pipeline rhodium-pipeline validate . -``` +---- -## Pipeline Stages +=== Pipeline Stages Rhodium Pipeline generates pipelines with these stages: -### 1. Check Stage -- Format verification (`cargo fmt --check`) -- Linting (`cargo clippy`) -- Unsafe code detection -- Dependency audit (verify zero deps) - -### 2. Test Stage -- Unit tests -- Integration tests -- Documentation tests -- Release mode tests - -### 3. Build Stage -- Debug build -- Release build -- Cross-platform builds (Linux, macOS, Windows) -- MUSL static builds - -### 4. Verify Stage -- RSR compliance check (via rhodibot) -- Self-verification -- Badge generation -- Conformity document generation - -### 5. Deploy Stage (optional) -- Binary releases -- Container images -- Documentation deployment - -## CLI Usage - -``` +==== 1. Check Stage + +* Format verification (`+cargo fmt --check+`) +* Linting (`+cargo clippy+`) +* Unsafe code detection +* Dependency audit (verify zero deps) + +==== 2. Test Stage + +* Unit tests +* Integration tests +* Documentation tests +* Release mode tests + +==== 3. Build Stage + +* Debug build +* Release build +* Cross-platform builds (Linux, macOS, Windows) +* MUSL static builds + +==== 4. Verify Stage + +* RSR compliance check (via rhodibot) +* Self-verification +* Badge generation +* Conformity document generation + +==== 5. Deploy Stage (optional) + +* Binary releases +* Container images +* Documentation deployment + +=== CLI Usage + +.... rhodium-pipeline [COMMAND] [OPTIONS] COMMANDS: @@ -127,13 +134,14 @@ OPTIONS: -o, --output Output path (default: current directory) -f, --force Overwrite existing files -h, --help Print help information -``` +.... -## Templates +=== Templates -### Bronze Pipeline (Default) +==== Bronze Pipeline (Default) -```yaml +[source,yaml] +---- # Minimum viable RSR-compliant pipeline stages: [check, test, build, verify] features: @@ -144,11 +152,12 @@ features: - unit-tests - release-build - rsr-compliance -``` +---- -### Silver Pipeline +==== Silver Pipeline -```yaml +[source,yaml] +---- # Extended pipeline with advanced checks stages: [check, test, security, build, verify] features: @@ -157,11 +166,12 @@ features: - coverage-threshold - mutation-testing - formal-verification-hooks -``` +---- -### Gold Pipeline +==== Gold Pipeline -```yaml +[source,yaml] +---- # Multi-language, multi-platform pipeline stages: [check, test, security, build, verify, deploy] features: @@ -170,54 +180,57 @@ features: - container-builds - documentation-deploy - release-automation -``` +---- + +=== Design Principles -## Design Principles +[arabic] +. *Zero Dependencies* - Only Rust standard library +. *Zero Unsafe Code* - 100% safe Rust +. *Template-Based* - Easy customization +. *Platform-Agnostic* - Works with any CI/CD system +. *RSR-First* - Enforces RSR requirements by default -1. **Zero Dependencies** - Only Rust standard library -2. **Zero Unsafe Code** - 100% safe Rust -3. **Template-Based** - Easy customization -4. **Platform-Agnostic** - Works with any CI/CD system -5. **RSR-First** - Enforces RSR requirements by default +=== Generated Files -## Generated Files +==== GitHub Actions -### GitHub Actions -``` +.... .github/ workflows/ ci.yml # Main CI pipeline release.yml # Release automation pages.yml # Documentation deployment -``` +.... + +==== GitLab CI -### GitLab CI -``` +.... .gitlab-ci.yml # Full pipeline configuration -``` +.... -## Validation +=== Validation Rhodium Pipeline can validate existing configurations: -```bash +[source,bash] +---- rhodium-pipeline validate . -``` +---- -Checks: -- Required stages present -- RSR checks configured -- Security scans enabled -- No unsafe operations +Checks: - Required stages present - RSR checks configured - Security +scans enabled - No unsafe operations -## License +=== License MIT OR Apache-2.0 -## Contributing +=== Contributing -See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. +See CONTRIBUTING.md for guidelines. ---- +''''' -*Part of the [Rhodium Standard](https://github.com/hyperpolymath/rhodium-standard-repositories) ecosystem* +_Part of the +https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard] ecosystem_ diff --git a/aletheia/docs/VALUE-CHAIN-POLICY.md b/aletheia/extraction/rhodium-pipeline/docs/VALUE-CHAIN-POLICY.adoc similarity index 56% rename from aletheia/docs/VALUE-CHAIN-POLICY.md rename to aletheia/extraction/rhodium-pipeline/docs/VALUE-CHAIN-POLICY.adoc index 192eb61..03661ca 100644 --- a/aletheia/docs/VALUE-CHAIN-POLICY.md +++ b/aletheia/extraction/rhodium-pipeline/docs/VALUE-CHAIN-POLICY.adoc @@ -1,32 +1,40 @@ - -# Hyperpolymath Project Value Chain Policy +== Hyperpolymath Project Value Chain Policy -This document defines the standard value chain model for all Hyperpolymath projects. It is based on Porter's Value Chain framework, adapted for software development. +This document defines the standard value chain model for all +Hyperpolymath projects. It is based on Porter’s Value Chain framework, +adapted for software development. -## Overview +=== Overview Every Hyperpolymath project has two types of activities: -1. **Support Activities** - Cross-cutting concerns that apply at all stages -2. **Primary Activities** - The value flow from inputs to outputs +[arabic] +. *Support Activities* - Cross-cutting concerns that apply at all stages +. *Primary Activities* - The value flow from inputs to outputs -## Support Activities (Cross-Cutting) +=== Support Activities (Cross-Cutting) These apply horizontally across all primary activities: -| Activity | Description | Tools | -|----------|-------------|-------| -| **Technology** | CCCP stack (containers, runtime, shell) | Cerro Torre, Svalinn, Valence Shell | -| **Formalizations** | Proofs, validation, verification | Absolute Zero, Echidna, Coq/Lean/Z3 | -| **Standards** | Repository and code standards | RSR, CCCP, .scm files, Palimpsest | -| **Infrastructure** | Build, CI/CD, deployment | mustfile, rhodium-pipeline, GitLab CI | +[width="100%",cols="34%,43%,23%",options="header",] +|=== +|Activity |Description |Tools +|*Technology* |CCCP stack (containers, runtime, shell) |Cerro Torre, +Svalinn, Valence Shell -## Primary Activities (Value Flow) +|*Formalizations* |Proofs, validation, verification |Absolute Zero, +Echidna, Coq/Lean/Z3 -``` +|*Standards* |Repository and code standards |RSR, CCCP, .scm files, +Palimpsest + +|*Infrastructure* |Build, CI/CD, deployment |mustfile, rhodium-pipeline, +GitLab CI +|=== + +=== Primary Activities (Value Flow) + +.... ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ INBOUND │ │ │ │ OUTBOUND │ │ MARKETING │ │ │ │ LOGISTICS │──▶│ OPERATIONS │──▶│ LOGISTICS │──▶│ & SALES │──▶│ SERVICE │ @@ -34,121 +42,133 @@ These apply horizontally across all primary activities: │ Theoretical │ │ Core │ │ Outputs │ │ Standards │ │ Maintenance │ │ foundations │ │ project │ │ & exports │ │ & business │ │ & ops │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ -``` +.... + +==== 1. Inbound Logistics + +*What*: Foundational inputs specific to the project’s domain + +Examples: - For Aletheia: Absolute Zero (CNO proofs, Landauer, Bennett) +- For rhodibot: RSR specification - For oikos: Economic/ecological +theory + +==== 2. Operations -### 1. Inbound Logistics -**What**: Foundational inputs specific to the project's domain +*What*: The core project work - what this repository actually builds -Examples: -- For Aletheia: Absolute Zero (CNO proofs, Landauer, Bennett) -- For rhodibot: RSR specification -- For oikos: Economic/ecological theory +Examples: - For Aletheia: Reversible Minix research (r-Minix precursor) +- For rhodibot: Compliance checking engine - For oikos: +Economic/ecological analyzer -### 2. Operations -**What**: The core project work - what this repository actually builds +==== 3. Outbound Logistics -Examples: -- For Aletheia: Reversible Minix research (r-Minix precursor) -- For rhodibot: Compliance checking engine -- For oikos: Economic/ecological analyzer +*What*: Where outputs go - integration with CCCP stack or other projects -### 3. Outbound Logistics -**What**: Where outputs go - integration with CCCP stack or other projects +Examples: - To CCCP technology stack (containers, runtime) - To +downstream projects - To future implementations (e.g., Aletheia → +r-Minix) -Examples: -- To CCCP technology stack (containers, runtime) -- To downstream projects -- To future implementations (e.g., Aletheia → r-Minix) +==== 4. Marketing & Sales -### 4. Marketing & Sales -**What**: RSR ecosystem, maintenance strategies, business extensions +*What*: RSR ecosystem, maintenance strategies, business extensions -Components: -- **Corrective maintenance** - Bug fixes, issue resolution -- **Adaptive maintenance** - Platform/environment changes -- **Perfective maintenance** - Improvements, optimizations +Components: - *Corrective maintenance* - Bug fixes, issue resolution - +*Adaptive maintenance* - Platform/environment changes - *Perfective +maintenance* - Improvements, optimizations -### 5. Service -**What**: Ongoing operational support via automation +==== 5. Service -Tools: -- **feedback-o-tron** - Feedback collection and processing -- **cicd-hyper-a** - CI/CD automation -- **robot-repo-automaton** - Repository automation +*What*: Ongoing operational support via automation -## Two Input Systems +Tools: - *feedback-o-tron* - Feedback collection and processing - +*cicd-hyper-a* - CI/CD automation - *robot-repo-automaton* - Repository +automation + +=== Two Input Systems All projects receive inputs from two complementary systems: -### RSR - Rhodium Standard Repositories -- **Layer**: Repository organization -- **Handles**: Documentation, security.txt, CI/CD, build systems -- **Tools**: rhodium-standard-repositories, rsr-template-repo, rhodibot, rhodium-pipeline +==== RSR - Rhodium Standard Repositories + +* *Layer*: Repository organization +* *Handles*: Documentation, security.txt, CI/CD, build systems +* *Tools*: rhodium-standard-repositories, rsr-template-repo, rhodibot, +rhodium-pipeline + +==== CCCP - Campaign for Cooling Coding and Programming -### CCCP - Campaign for Cooling Coding and Programming -- **Layer**: Technology stack and code -- **Handles**: Languages, containers, integrations, efficiency -- **Tools**: Cerro Torre, Svalinn, Valence Shell, rescript-tea, cadre-router +* *Layer*: Technology stack and code +* *Handles*: Languages, containers, integrations, efficiency +* *Tools*: Cerro Torre, Svalinn, Valence Shell, rescript-tea, +cadre-router -## Project-Specific Foundations +=== Project-Specific Foundations Each project may have domain-specific foundational inputs: -| Project | Foundational Input | -|---------|-------------------| -| Aletheia | Absolute Zero (CNO proofs, reversibility theory) | -| Valence Shell | Absolute Zero (filesystem CNO proofs) | -| Oikos | Economic/ecological theory | -| Echidnabot | Formal methods, SAT/SMT solving | +[cols=",",options="header",] +|=== +|Project |Foundational Input +|Aletheia |Absolute Zero (CNO proofs, reversibility theory) +|Valence Shell |Absolute Zero (filesystem CNO proofs) +|Oikos |Economic/ecological theory +|Echidnabot |Formal methods, SAT/SMT solving +|=== -## Standard Files +=== Standard Files All properly configured projects include: -### AI Support Files (.scm - Guile Scheme) -- `META.scm` - Project metadata -- `ECOSYSTEM.scm` - Ecosystem connections -- `STATE.scm` - Current project state -- `PLAYBOOK.scm` - Development workflows -- `AGENTIC.scm` - AI agent configuration -- `NEUROSYM.scm` - Neurosymbolic settings +==== AI Support Files (.scm - Guile Scheme) + +* `+META.scm+` - Project metadata +* `+ECOSYSTEM.scm+` - Ecosystem connections +* `+STATE.scm+` - Current project state +* `+PLAYBOOK.scm+` - Development workflows +* `+AGENTIC.scm+` - AI agent configuration +* `+NEUROSYM.scm+` - Neurosymbolic settings + +==== Build & Standards + +* `+mustfile+` - Build/task automation +* RSR compliance files (README, LICENSE, SECURITY.md, etc.) +* `+.well-known/+` directory -### Build & Standards -- `mustfile` - Build/task automation -- RSR compliance files (README, LICENSE, SECURITY.md, etc.) -- `.well-known/` directory +==== Licensing -### Licensing -- **Base**: MIT or AGPL (user choice) -- **Overlay**: Palimpsest License (optional but encouraged) +* *Base*: MIT or AGPL (user choice) +* *Overlay*: Palimpsest License (optional but encouraged) -## Bot Ecosystem +=== Bot Ecosystem Projects are supported by bots operating in multiple modes: -| Bot | Role | -|-----|------| -| **rhodibot** | RSR compliance (consultant, advisor, regulator) | -| **echidnabot** | Formal proof validation | -| **oikos bot** | Economic/ecological analysis | +[cols=",",options="header",] +|=== +|Bot |Role +|*rhodibot* |RSR compliance (consultant, advisor, regulator) +|*echidnabot* |Formal proof validation +|*oikos bot* |Economic/ecological analysis +|=== -Bots are **self-referential** - they validate their own code. +Bots are *self-referential* - they validate their own code. -## Applying This Policy +=== Applying This Policy When setting up a new project: -1. Start with `rsr-template-repo` -2. Apply customizations via `repo-customiser` -3. Identify the project's **foundational input** (inbound logistics) -4. Define the **core operations** (what this project builds) -5. Specify **outbound targets** (where outputs go) -6. Configure **maintenance strategy** (corrective/adaptive/perfective) -7. Set up **service automation** (feedback-o-tron, cicd-hyper-a, etc.) +[arabic] +. Start with `+rsr-template-repo+` +. Apply customizations via `+repo-customiser+` +. Identify the project’s *foundational input* (inbound logistics) +. Define the *core operations* (what this project builds) +. Specify *outbound targets* (where outputs go) +. Configure *maintenance strategy* (corrective/adaptive/perfective) +. Set up *service automation* (feedback-o-tron, cicd-hyper-a, etc.) -## Diagram +=== Diagram -``` +.... ┌─────────────────────────────────────────────────────────────────────────────────────┐ │ SUPPORT ACTIVITIES (Cross-cutting) │ ├─────────────────────────────────────────────────────────────────────────────────────┤ @@ -176,8 +196,9 @@ When setting up a new project: │ ═══════════════════════════════════════════════════════════════════════════════▶ │ │ VALUE CREATION MARGIN │ └─────────────────────────────────────────────────────────────────────────────────────┘ -``` +.... ---- +''''' -*This policy applies to all Hyperpolymath projects and their satellite repositories.* +_This policy applies to all Hyperpolymath projects and their satellite +repositories._ diff --git a/aletheia/templates/bronze-rust/README-template.adoc b/aletheia/templates/bronze-rust/README-template.adoc new file mode 100644 index 0000000..2ed5ce1 --- /dev/null +++ b/aletheia/templates/bronze-rust/README-template.adoc @@ -0,0 +1,83 @@ +== maa-framework + +____ +\{\{PROJECT_DESCRIPTION}} +____ + +=== 🚀 Quick Start + +[source,bash] +---- +# Clone the repository +git clone {{REPOSITORY_URL}} +cd maa-framework + +# Build +cargo build --release + +# Run +cargo run + +# Test +cargo test +---- + +=== 📊 RSR Compliance + +*Level*: Bronze ✅ + +This project maintains RSR Bronze-level compliance: + +* ✅ Type Safety: Rust compile-time guarantees +* ✅ Memory Safety: Ownership model, zero unsafe blocks +* ✅ Zero Dependencies: Only standard library +* ✅ Offline-First: No network dependencies +* ✅ Complete Documentation: All required docs present +* ✅ Security: RFC 9116 compliant security.txt +* ✅ Build System: Justfile, flake.nix, CI/CD +* ✅ Testing: Comprehensive test suite + +Verify compliance: + +[source,bash] +---- +aletheia . +---- + +=== 🎯 Features + +* Feature 1: \{\{FEATURE_1_DESCRIPTION}} +* Feature 2: \{\{FEATURE_2_DESCRIPTION}} +* Feature 3: \{\{FEATURE_3_DESCRIPTION}} + +=== 📖 Documentation + +* link:SECURITY.md[Security Policy] - Vulnerability disclosure +* link:CONTRIBUTING.md[Contributing Guide] - How to contribute +* link:CODE_OF_CONDUCT.md[Code of Conduct] - Community standards +* link:CHANGELOG.md[Changelog] - Version history + +=== 🤝 Contributing + +We welcome contributions! See CONTRIBUTING.md for guidelines. + +=== 📜 License + +Dual-licensed under: - MIT License - See LICENSE-MIT.txt - +\{\{ALTERNATIVE_LICENSE}} - See LICENSE-%7B%7BALTERNATIVE%7D%7D.txt + +=== 🙏 Acknowledgments + +* Built with https://www.rust-lang.org/[Rust] +* RSR compliant via +https://gitlab.com/maa-framework/6-the-foundation/aletheia[Aletheia] + +=== 📞 Contact + +* *Repository*: \{\{REPOSITORY_URL}} +* *Issues*: \{\{ISSUES_URL}} +* *Security*: See SECURITY.md + +''''' + +_\{\{PROJECT_TAGLINE}}_ diff --git a/aletheia/templates/bronze-rust/README-template.md b/aletheia/templates/bronze-rust/README-template.md deleted file mode 100644 index b865f07..0000000 --- a/aletheia/templates/bronze-rust/README-template.md +++ /dev/null @@ -1,82 +0,0 @@ - -# maa-framework - -> {{PROJECT_DESCRIPTION}} - -## 🚀 Quick Start - -```bash -# Clone the repository -git clone {{REPOSITORY_URL}} -cd maa-framework - -# Build -cargo build --release - -# Run -cargo run - -# Test -cargo test -``` - -## 📊 RSR Compliance - -**Level**: Bronze ✅ - -This project maintains RSR Bronze-level compliance: - -- ✅ Type Safety: Rust compile-time guarantees -- ✅ Memory Safety: Ownership model, zero unsafe blocks -- ✅ Zero Dependencies: Only standard library -- ✅ Offline-First: No network dependencies -- ✅ Complete Documentation: All required docs present -- ✅ Security: RFC 9116 compliant security.txt -- ✅ Build System: Justfile, flake.nix, CI/CD -- ✅ Testing: Comprehensive test suite - -Verify compliance: -```bash -aletheia . -``` - -## 🎯 Features - -- Feature 1: {{FEATURE_1_DESCRIPTION}} -- Feature 2: {{FEATURE_2_DESCRIPTION}} -- Feature 3: {{FEATURE_3_DESCRIPTION}} - -## 📖 Documentation - -- [Security Policy](SECURITY.md) - Vulnerability disclosure -- [Contributing Guide](CONTRIBUTING.md) - How to contribute -- [Code of Conduct](CODE_OF_CONDUCT.md) - Community standards -- [Changelog](CHANGELOG.md) - Version history - -## 🤝 Contributing - -We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. - -## 📜 License - -Dual-licensed under: -- MIT License - See [LICENSE-MIT.txt](LICENSE-MIT.txt) -- {{ALTERNATIVE_LICENSE}} - See [LICENSE-{{ALTERNATIVE}}.txt](LICENSE-{{ALTERNATIVE}}.txt) - -## 🙏 Acknowledgments - -- Built with [Rust](https://www.rust-lang.org/) -- RSR compliant via [Aletheia](https://gitlab.com/maa-framework/6-the-foundation/aletheia) - -## 📞 Contact - -- **Repository**: {{REPOSITORY_URL}} -- **Issues**: {{ISSUES_URL}} -- **Security**: See [SECURITY.md](SECURITY.md) - ---- - -*{{PROJECT_TAGLINE}}* diff --git a/docs/proof-debt.adoc b/docs/proof-debt.adoc new file mode 100644 index 0000000..a28d18f --- /dev/null +++ b/docs/proof-debt.adoc @@ -0,0 +1,254 @@ +== Proof Debt — maa-framework + +*Schema*: `+hyperpolymath/standards+` +https://github.com/hyperpolymath/standards/blob/main/docs/TRUSTED-BASE-REDUCTION-POLICY.adoc[`+docs/TRUSTED-BASE-REDUCTION-POLICY.adoc+`] +— the canonical policy, landed via standards#203. *Enforcement*: +standards#211 (`+scripts/check-trusted-base.sh+`). + +This file is the schema-conformant per-repo proof-debt index for +`+hyperpolymath/maa-framework+`. The broader strategic proof goals +across the repo live in link:../PROOF-NEEDS.md[`+PROOF-NEEDS.md+`]; this +file enumerates the _specific_ soundness-relevant escape hatches that +the +https://github.com/hyperpolymath/standards/blob/main/scripts/check-trusted-base.sh[`+check-trusted-base.sh+`] +CI gate detects in source. + +=== Schema extension for maa-framework: §(e) SUBMODULE — estate-sibling + +maa-framework mounts the sibling estate repo +`+hyperpolymath/absolute-zero+` at `+absolute-zero/+` as a *git +submodule* (pinned via `+.gitmodules+`). The canonical home of those +proof files is the standalone `+absolute-zero+` repo, which has its own +`+docs/proof-debt.md+` (seeded under the same standards#203 chain). + +To avoid double-counting (and double-discharging) the same markers, we +extend the schema with a fifth disposition: + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Disposition |Marker |Definition +|*(e) SUBMODULE — estate-sibling* |`+// SUBMODULE: +` +|The marker lives in a directory mounted as a submodule pinned to +another estate repository. Disposition is *delegated* to the canonical +repo’s `+docs/proof-debt.md+`. Closing the marker upstream + bumping the +submodule pin is the close-out path. +|=== + +`+(e)+` is *out of scope* for maa-framework’s own proof-debt close-out +budget. The maintainers’ obligation is just to bump the submodule pin +periodically (`+git submodule update --remote absolute-zero+` then +commit the resulting pin advance) and to flag if a marker disappears +upstream but persists here (cannot happen post-bump; can briefly happen +between upstream-close and pin-bump). + +The `+(e)+` extension is documented inline here per the standards#203 +policy’s guidance: "`extend the schema; document the extension at the +top of the file as a repo-specific note.`" If the pattern recurs across +other estate repos, it will be promoted into the central policy. + +*Prior wording* (2026-05-27 → 2026-05-30): this section originally +referred to a vendored in-tree copy that had drifted from upstream. PR +#83 (re-vendor) re-aligned the trees; this conversion replaces the +vendored snapshot with a submodule pin, resolving the open owner +question below. + +=== Marker count (2026-05-27) + +`+scripts/check-trusted-base.sh+`-style grep over +`+*.v / *.lean / *.agda / *.idr / *.fst / *.dfy / *.rs / *.hs+`: + +* *150 syntactic matches across 13 files* (the higher number vs the +audit’s "`134`" reflects a more inclusive regex; the audit excluded some +comment/import false positives). +* *All 13 files* live under `+absolute-zero/proofs/{coq,lean4,agda}/+`. +* *All 13 files* live in the `+hyperpolymath/absolute-zero+` submodule +pinned at the SHA recorded in `+.gitmodules+` + the index. File-header +author/license headers ("`Author: Jonathan D. A. Jewell; Project: +Absolute Zero`") confirm canonical home in the sibling repo. +* The two trees are byte-equivalent at the pinned SHA (drift can only +appear once upstream advances past the pin — bump the pin to clear). +* `+check-trusted-base.sh+` uses `+find .+` which walks submodule +contents naturally, so the 149/150 count is preserved post-conversion. + +Disposition split: + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Disposition |Files |Marker count |Notes +|(a) DISCHARGED |0 |0 |— + +|(b) BUDGETED |0 |0 |— + +|(c) NECESSARY AXIOM |0 |0 |(See §(e). The axioms in those files are +mostly genuine §(c)-class — physical constants, no-cloning, +function-extensionality — but the canonical home is the sibling repo.) + +|(d) DEBT |0 |0 |(PROOF-NEEDS.md flags `+y_not_cno+` `+Admitted+` as a +known gap — that’s also (e) since it lives in the submodule subtree.) + +|*(e) SUBMODULE — estate-sibling* |*13* |*150* |All under +`+absolute-zero/+` (submodule); canonical home +`+hyperpolymath/absolute-zero+` at the pinned SHA. +|=== + +=== (a) DISCHARGED in this repo + +_(None — maa-framework itself contains no proof-bearing source outside +the `+absolute-zero/+` submodule.)_ + +=== (b) BUDGETED — tested with a refutation budget + +_(None — same reason as §(a).)_ + +=== (c) NECESSARY AXIOM + +_(None — same reason as §(a). Note: the axioms inside `+absolute-zero/+` +(`+kB_positive+`, `+temperature_positive+`, `+no_cloning+`, the +unitary-gate postulates, Shannon-entropy axioms, +function-extensionality, etc.) are genuine §(c)-class candidates, but +their canonical disposition lives in the sibling repo. See §(e).)_ + +=== (d) DEBT — actively to be closed + +_(None — same reason as §(a). `+PROOF-NEEDS.md+` notes a known +`+Admitted+` on `+y_not_cno+` in `+proofs/coq/lambda/LambdaCNO.v+`; that +file is in the submodule subtree (§(e)), so the discharge happens +upstream in `+hyperpolymath/absolute-zero+`.)_ + +=== (e) SUBMODULE — estate-sibling + +All entries below have the form: +`+ — — +`. +The *canonical home* for every entry is `+hyperpolymath/absolute-zero+`; +this file does not duplicate that repo’s proof-debt classification. + +==== `+absolute-zero/proofs/coq/+` (7 files, 91 markers) + +[width="100%",cols="30%,>40%,30%",options="header",] +|=== +|File |Markers |Sample disposition (in sibling repo) +|`+absolute-zero/proofs/coq/quantum/QuantumCNO.v+` |35 |Mostly §(c): +physical constants (`+kB_positive+`, `+temperature_positive+`), +gate-unitarity (`+X_gate_unitary+`, `+H_gate_unitary+`, +`+CNOT_gate_unitary+`), inner-product / `+Cexp+` algebra, +`+no_cloning+`, `+unitary_preserves_entropy+`. + +|`+absolute-zero/proofs/coq/physics/StatMech.v+` |17 |§(c): +Shannon-entropy non-negativity / maximum / point-zero, +`+landauer_principle+`, `+reversible_zero_dissipation+`, physical +constants. + +|`+absolute-zero/proofs/coq/physics/LandauerDerivation.v+` |14 |§(c): +same family as `+StatMech.v+` plus `+second_law+`, +`+isothermal_work_bound+`, `+entropy_change_erasure+`, +`+cno_preserves_shannon_entropy+`. + +|`+absolute-zero/proofs/coq/filesystem/FilesystemCNO.v+` |13 |§(c): +syscall semantics (`+mkdir_rmdir_inverse+`, `+create_unlink_inverse+`, +`+read_write_identity+`, `+chmod_identity+`, `+chown_identity+`, +`+rename_inverse+`, `+snapshot_restore_identity+`) — POSIX-spec +assumptions standard in filesystem formalisations. + +|`+absolute-zero/proofs/coq/common/CNO.v+` |5 |§(c)+(d) mix: +`+eval_deterministic+` (operational-semantics assumption), +`+cno_decidable+` (decidability postulate), +`+eval_respects_state_eq_left/right+` (one has a "`TODO: Prove this +axiom by induction on eval structure`" comment — that’s a (d) entry +upstream). + +|`+absolute-zero/proofs/coq/lambda/LambdaCNO.v+` |5 |§(c): `+y_not_cno+` +(Y-combinator non-termination — well-established but not derivable in +pure Coq), `+eta_equivalence+`. *Note: PROOF-NEEDS.md targets +`+y_not_cno+` for discharge; close upstream.* + +|`+absolute-zero/proofs/coq/quantum/QuantumMechanicsExact.v+` |4 |§(c): +`+X_gate_unitary+`, `+unitary_preserves_entropy+`, `+no_cloning+` +(subset of QuantumCNO.v). + +|`+absolute-zero/proofs/coq/category/CNOCategory.v+` |2 |§(c): +`+hom_functor+` (Hom-functor functoriality, standard category-theory +result). +|=== + +==== `+absolute-zero/proofs/lean4/+` (4 files, 54 markers) + +[width="100%",cols="30%,>40%,30%",options="header",] +|=== +|File |Markers |Sample disposition (in sibling repo) +|`+absolute-zero/proofs/lean4/FilesystemCNO.lean+` |22 |§(c): Lean4 port +of `+FilesystemCNO.v+` axioms — same family of syscall-semantics +postulates plus `+mkdir_test_not_identity+`, `+mkdir_idempotent+`. + +|`+absolute-zero/proofs/lean4/StatMech.lean+` |15 |§(c): Lean4 port of +`+StatMech.v+` plus `+programState_eq_eval_fixpoint+`, +`+state_preserving_dist+`. + +|`+absolute-zero/proofs/lean4/QuantumCNO.lean+` |14 |§(c): Lean4 port of +`+QuantumCNO.v+`. + +|`+absolute-zero/proofs/lean4/LambdaCNO.lean+` |3 |§(c): +`+subst_closed_term+`, `+y_combinator_not_identity+`, +`+eta_equivalence+`. +|=== + +==== `+absolute-zero/proofs/agda/+` (1 file, 1 marker) + +[width="100%",cols="30%,>40%,30%",options="header",] +|=== +|File |Markers |Disposition +|`+absolute-zero/proofs/agda/EchoBridgeCNO.agda+` |1 |False positive on +the strict grep — the single hit is +`+open import Axiom.Extensionality.Propositional+`, which is a *module +import* (the agda-stdlib path), not a `+postulate+`. Treat as resolved +on close inspection. +|=== + +==== One outlier on close inspection + +The `+EchoBridgeCNO.agda+` count is a grep false positive +(`+Axiom.Extensionality.Propositional+` is the agda-stdlib module path, +not an axiom declaration). The real "`load-bearing escape hatches`" +count across `+absolute-zero/+` is therefore *149*, not 150. Schema +preserves the grep number for CI parity with `+check-trusted-base.sh+`. + +=== How to update this file + +[arabic] +. Re-run `+bash scripts/check-trusted-base.sh .+` (from standards#211) +from the repo root. +. If markers in `+absolute-zero/+` change, the close-out path is to fix +the canonical `+hyperpolymath/absolute-zero+` repo upstream and bump the +submodule pin here (`+git submodule update --remote absolute-zero+` then +commit). +. If a *new* proof-bearing file appears *outside* `+absolute-zero/+` +(e.g. under `+aletheia/+` for the Rust verification pipeline, or under +`+contractiles/+`), classify it into §(a)/(b)/(c)/(d) per the canonical +schema. That would be load-bearing maa-framework debt. + +=== Resolved owner questions + +[arabic] +. *[line-through]#Vendoring policy#* (resolved 2026-05-30): the +`+absolute-zero/+` subtree is now a git submodule pinned to +`+hyperpolymath/absolute-zero+`. Canonical proof-debt.md is the single +source of truth; this file delegates via §(e) SUBMODULE. +. *[line-through]#Re-sync cadence#* (resolved by above): submodule pin +advances are the re-sync mechanism. Bump on a release-driven schedule, +or when upstream lands a marker discharge that’s worth pulling. + +=== Companion documents + +* link:../PROOF-NEEDS.md[`+PROOF-NEEDS.md+`] — the broader strategic +proof narrative for maa-framework as a whole. +* `+hyperpolymath/standards+` +https://github.com/hyperpolymath/standards/blob/main/docs/TRUSTED-BASE-REDUCTION-POLICY.adoc[`+docs/TRUSTED-BASE-REDUCTION-POLICY.adoc+`] +— the canonical schema. +* `+hyperpolymath/standards+` +https://github.com/hyperpolymath/standards/blob/main/scripts/check-trusted-base.sh[`+scripts/check-trusted-base.sh+`] +— the CI gate. +* `+hyperpolymath/absolute-zero+` `+docs/proof-debt.md+` — the canonical +per-marker disposition for everything in §(e). + +''''' + +Initial seed under standards#203 + standards#211, 2026-05-27. diff --git a/docs/proof-debt.md b/docs/proof-debt.md deleted file mode 100644 index c88c416..0000000 --- a/docs/proof-debt.md +++ /dev/null @@ -1,185 +0,0 @@ - -# Proof Debt — maa-framework - -**Schema**: `hyperpolymath/standards` -[`docs/TRUSTED-BASE-REDUCTION-POLICY.adoc`](https://github.com/hyperpolymath/standards/blob/main/docs/TRUSTED-BASE-REDUCTION-POLICY.adoc) -— the canonical policy, landed via standards#203. -**Enforcement**: standards#211 (`scripts/check-trusted-base.sh`). - -This file is the schema-conformant per-repo proof-debt index for -`hyperpolymath/maa-framework`. The broader strategic proof goals across -the repo live in [`PROOF-NEEDS.md`](../PROOF-NEEDS.md); this file -enumerates the *specific* soundness-relevant escape hatches that the -[`check-trusted-base.sh`](https://github.com/hyperpolymath/standards/blob/main/scripts/check-trusted-base.sh) -CI gate detects in source. - -## Schema extension for maa-framework: §(e) SUBMODULE — estate-sibling - -maa-framework mounts the sibling estate repo `hyperpolymath/absolute-zero` -at `absolute-zero/` as a **git submodule** (pinned via `.gitmodules`). -The canonical home of those proof files is the standalone -`absolute-zero` repo, which has its own `docs/proof-debt.md` (seeded -under the same standards#203 chain). - -To avoid double-counting (and double-discharging) the same markers, we -extend the schema with a fifth disposition: - -| Disposition | Marker | Definition | -| --- | --- | --- | -| **(e) SUBMODULE — estate-sibling** | `// SUBMODULE: ` | The marker lives in a directory mounted as a submodule pinned to another estate repository. Disposition is **delegated** to the canonical repo's `docs/proof-debt.md`. Closing the marker upstream + bumping the submodule pin is the close-out path. | - -`(e)` is **out of scope** for maa-framework's own proof-debt close-out -budget. The maintainers' obligation is just to bump the submodule pin -periodically (`git submodule update --remote absolute-zero` then commit -the resulting pin advance) and to flag if a marker disappears upstream -but persists here (cannot happen post-bump; can briefly happen between -upstream-close and pin-bump). - -The `(e)` extension is documented inline here per the standards#203 -policy's guidance: "extend the schema; document the extension at the -top of the file as a repo-specific note." If the pattern recurs across -other estate repos, it will be promoted into the central policy. - -**Prior wording** (2026-05-27 → 2026-05-30): this section originally -referred to a vendored in-tree copy that had drifted from upstream. -PR #83 (re-vendor) re-aligned the trees; this conversion replaces the -vendored snapshot with a submodule pin, resolving the open owner -question below. - -## Marker count (2026-05-27) - -`scripts/check-trusted-base.sh`-style grep over `*.v / *.lean / *.agda / -*.idr / *.fst / *.dfy / *.rs / *.hs`: - -- **150 syntactic matches across 13 files** (the higher number vs the - audit's "134" reflects a more inclusive regex; the audit excluded - some comment/import false positives). -- **All 13 files** live under `absolute-zero/proofs/{coq,lean4,agda}/`. -- **All 13 files** live in the `hyperpolymath/absolute-zero` submodule - pinned at the SHA recorded in `.gitmodules` + the index. File-header - author/license headers ("Author: Jonathan D. A. Jewell; Project: - Absolute Zero") confirm canonical home in the sibling repo. -- The two trees are byte-equivalent at the pinned SHA (drift can only - appear once upstream advances past the pin — bump the pin to clear). -- `check-trusted-base.sh` uses `find .` which walks submodule contents - naturally, so the 149/150 count is preserved post-conversion. - -Disposition split: - -| Disposition | Files | Marker count | Notes | -| --- | --- | --- | --- | -| (a) DISCHARGED | 0 | 0 | — | -| (b) BUDGETED | 0 | 0 | — | -| (c) NECESSARY AXIOM | 0 | 0 | (See §(e). The axioms in those files are mostly genuine §(c)-class — physical constants, no-cloning, function-extensionality — but the canonical home is the sibling repo.) | -| (d) DEBT | 0 | 0 | (PROOF-NEEDS.md flags `y_not_cno` `Admitted` as a known gap — that's also (e) since it lives in the submodule subtree.) | -| **(e) SUBMODULE — estate-sibling** | **13** | **150** | All under `absolute-zero/` (submodule); canonical home `hyperpolymath/absolute-zero` at the pinned SHA. | - -## (a) DISCHARGED in this repo - -*(None — maa-framework itself contains no proof-bearing source outside -the `absolute-zero/` submodule.)* - -## (b) BUDGETED — tested with a refutation budget - -*(None — same reason as §(a).)* - -## (c) NECESSARY AXIOM - -*(None — same reason as §(a). Note: the axioms inside `absolute-zero/` -(`kB_positive`, `temperature_positive`, `no_cloning`, the unitary-gate -postulates, Shannon-entropy axioms, function-extensionality, etc.) are -genuine §(c)-class candidates, but their canonical disposition lives in -the sibling repo. See §(e).)* - -## (d) DEBT — actively to be closed - -*(None — same reason as §(a). `PROOF-NEEDS.md` notes a known `Admitted` -on `y_not_cno` in `proofs/coq/lambda/LambdaCNO.v`; that file is in the -submodule subtree (§(e)), so the discharge happens upstream in -`hyperpolymath/absolute-zero`.)* - -## (e) SUBMODULE — estate-sibling - -All entries below have the form: ` — — -`. The **canonical home** for every entry -is `hyperpolymath/absolute-zero`; this file does not duplicate that -repo's proof-debt classification. - -### `absolute-zero/proofs/coq/` (7 files, 91 markers) - -| File | Markers | Sample disposition (in sibling repo) | -| --- | ---: | --- | -| `absolute-zero/proofs/coq/quantum/QuantumCNO.v` | 35 | Mostly §(c): physical constants (`kB_positive`, `temperature_positive`), gate-unitarity (`X_gate_unitary`, `H_gate_unitary`, `CNOT_gate_unitary`), inner-product / `Cexp` algebra, `no_cloning`, `unitary_preserves_entropy`. | -| `absolute-zero/proofs/coq/physics/StatMech.v` | 17 | §(c): Shannon-entropy non-negativity / maximum / point-zero, `landauer_principle`, `reversible_zero_dissipation`, physical constants. | -| `absolute-zero/proofs/coq/physics/LandauerDerivation.v` | 14 | §(c): same family as `StatMech.v` plus `second_law`, `isothermal_work_bound`, `entropy_change_erasure`, `cno_preserves_shannon_entropy`. | -| `absolute-zero/proofs/coq/filesystem/FilesystemCNO.v` | 13 | §(c): syscall semantics (`mkdir_rmdir_inverse`, `create_unlink_inverse`, `read_write_identity`, `chmod_identity`, `chown_identity`, `rename_inverse`, `snapshot_restore_identity`) — POSIX-spec assumptions standard in filesystem formalisations. | -| `absolute-zero/proofs/coq/common/CNO.v` | 5 | §(c)+(d) mix: `eval_deterministic` (operational-semantics assumption), `cno_decidable` (decidability postulate), `eval_respects_state_eq_left/right` (one has a "TODO: Prove this axiom by induction on eval structure" comment — that's a (d) entry upstream). | -| `absolute-zero/proofs/coq/lambda/LambdaCNO.v` | 5 | §(c): `y_not_cno` (Y-combinator non-termination — well-established but not derivable in pure Coq), `eta_equivalence`. **Note: PROOF-NEEDS.md targets `y_not_cno` for discharge; close upstream.** | -| `absolute-zero/proofs/coq/quantum/QuantumMechanicsExact.v` | 4 | §(c): `X_gate_unitary`, `unitary_preserves_entropy`, `no_cloning` (subset of QuantumCNO.v). | -| `absolute-zero/proofs/coq/category/CNOCategory.v` | 2 | §(c): `hom_functor` (Hom-functor functoriality, standard category-theory result). | - -### `absolute-zero/proofs/lean4/` (4 files, 54 markers) - -| File | Markers | Sample disposition (in sibling repo) | -| --- | ---: | --- | -| `absolute-zero/proofs/lean4/FilesystemCNO.lean` | 22 | §(c): Lean4 port of `FilesystemCNO.v` axioms — same family of syscall-semantics postulates plus `mkdir_test_not_identity`, `mkdir_idempotent`. | -| `absolute-zero/proofs/lean4/StatMech.lean` | 15 | §(c): Lean4 port of `StatMech.v` plus `programState_eq_eval_fixpoint`, `state_preserving_dist`. | -| `absolute-zero/proofs/lean4/QuantumCNO.lean` | 14 | §(c): Lean4 port of `QuantumCNO.v`. | -| `absolute-zero/proofs/lean4/LambdaCNO.lean` | 3 | §(c): `subst_closed_term`, `y_combinator_not_identity`, `eta_equivalence`. | - -### `absolute-zero/proofs/agda/` (1 file, 1 marker) - -| File | Markers | Disposition | -| --- | ---: | --- | -| `absolute-zero/proofs/agda/EchoBridgeCNO.agda` | 1 | False positive on the strict grep — the single hit is `open import Axiom.Extensionality.Propositional`, which is a **module import** (the agda-stdlib path), not a `postulate`. Treat as resolved on close inspection. | - -### One outlier on close inspection - -The `EchoBridgeCNO.agda` count is a grep false positive -(`Axiom.Extensionality.Propositional` is the agda-stdlib module path, -not an axiom declaration). The real "load-bearing escape hatches" count -across `absolute-zero/` is therefore **149**, not 150. Schema preserves -the grep number for CI parity with `check-trusted-base.sh`. - -## How to update this file - -1. Re-run `bash scripts/check-trusted-base.sh .` (from standards#211) - from the repo root. -2. If markers in `absolute-zero/` change, the close-out path is to fix - the canonical `hyperpolymath/absolute-zero` repo upstream and bump - the submodule pin here (`git submodule update --remote absolute-zero` - then commit). -3. If a **new** proof-bearing file appears **outside** `absolute-zero/` - (e.g. under `aletheia/` for the Rust verification pipeline, or under - `contractiles/`), classify it into §(a)/(b)/(c)/(d) per the canonical - schema. That would be load-bearing maa-framework debt. - -## Resolved owner questions - -1. **~~Vendoring policy~~** (resolved 2026-05-30): the `absolute-zero/` - subtree is now a git submodule pinned to `hyperpolymath/absolute-zero`. - Canonical proof-debt.md is the single source of truth; this file - delegates via §(e) SUBMODULE. -2. **~~Re-sync cadence~~** (resolved by above): submodule pin advances - are the re-sync mechanism. Bump on a release-driven schedule, or - when upstream lands a marker discharge that's worth pulling. - -## Companion documents - -- [`PROOF-NEEDS.md`](../PROOF-NEEDS.md) — the broader strategic proof - narrative for maa-framework as a whole. -- `hyperpolymath/standards` - [`docs/TRUSTED-BASE-REDUCTION-POLICY.adoc`](https://github.com/hyperpolymath/standards/blob/main/docs/TRUSTED-BASE-REDUCTION-POLICY.adoc) - — the canonical schema. -- `hyperpolymath/standards` - [`scripts/check-trusted-base.sh`](https://github.com/hyperpolymath/standards/blob/main/scripts/check-trusted-base.sh) - — the CI gate. -- `hyperpolymath/absolute-zero` `docs/proof-debt.md` — the canonical - per-marker disposition for everything in §(e). - ---- - -Initial seed under standards#203 + standards#211, 2026-05-27. diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..802a968 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,88 @@ +== Tech-Debt Audit — maa-framework — 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:* `+HIGH+`. + +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 + +Scanner counted the following markers in proof-bearing files of this +repo: + +.... +files= 25 | Coq-Axm/Adm= 80 | Lean-srry/ax= 54 | Agda-pst= 0 | Idr-blv= 0 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 0 +.... + +*Total markers:* 134. *Severity:* `+>0134+`. + +*Marker types* (any non-zero counts above): - Coq `+Axiom+`/`+Admitted+` +— unconditional proof escapes. - Lean `+sorry+`/`+axiom+` — Lean’s +equivalent. - Agda `+postulate+` — accepted axiomatically. - Idris2 +`+believe_me+`/`+assert_total+` — runtime-safe coercion / totality +assumption. - Idris2 top-level `+partial+` — totality-check waived. - F* +`+assume val+`/`+admit_p+` — F* admit. - `+TODO PROOF+` / `+OWED:+` — +self-documented debt markers. - `+unsafePerformIO+`/`+unsafeCoerce+` — +soundness-relevant escape hatches in Haskell/Rust source. + +*Recommended next move:* triage each finding into one of: (a) discharge +by proof, (b) cover with property-tests + a documented refutation +budget, or (c) annotate as a known/necessary axiom (e.g. `+funExt+`) in +`+docs/proof-debt.md+`. + +=== 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 |122 +|`+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 +122 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/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index 2c86c92..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,72 +0,0 @@ - -# Tech-Debt Audit — maa-framework — 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:** `HIGH`. - -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 - -Scanner counted the following markers in proof-bearing files of this repo: - -``` -files= 25 | Coq-Axm/Adm= 80 | Lean-srry/ax= 54 | Agda-pst= 0 | Idr-blv= 0 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 0 -``` - -**Total markers:** 134. **Severity:** `>0134`. - -**Marker types** (any non-zero counts above): -- Coq `Axiom`/`Admitted` — unconditional proof escapes. -- Lean `sorry`/`axiom` — Lean's equivalent. -- Agda `postulate` — accepted axiomatically. -- Idris2 `believe_me`/`assert_total` — runtime-safe coercion / totality assumption. -- Idris2 top-level `partial` — totality-check waived. -- F\* `assume val`/`admit_p` — F\* admit. -- `TODO PROOF` / `OWED:` — self-documented debt markers. -- `unsafePerformIO`/`unsafeCoerce` — soundness-relevant escape hatches in Haskell/Rust source. - -**Recommended next move:** triage each finding into one of: (a) discharge by proof, (b) cover with property-tests + a documented refutation budget, or (c) annotate as a known/necessary axiom (e.g. `funExt`) in `docs/proof-debt.md`. - -## 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 | 122 | -| `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 122 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/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..25805e0 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — maa-framework (Developer) + +=== What is maa-framework? + +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/llm-warmup-dev.md b/llm-warmup-dev.md deleted file mode 100644 index 95a9b0f..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — maa-framework (Developer) - -## What is maa-framework? -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/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..4e87f99 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — maa-framework (User) + +=== What is maa-framework? + +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/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index fb6eb7e..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — maa-framework (User) - -## What is maa-framework? -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