image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[MPL-2.0-or-later,link="https://opensource.org/licenses/MPL-2.0"]
image:https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-license"]

== License & Philosophy

This project must declare **MPL-2.0-or-later** for platform/tooling compatibility.

Philosophy: **Palimpsest**. The Palimpsest-MPL (PMPL) text is provided in `license/PMPL-1.0.txt`, and the canonical source is the palimpsest-license repository.

// SPDX-License-Identifier: MPL-2.0
// SPDX-FileCopyrightText: 2025 The Rhodium Standard Contributors
= Rhodium Standard Repositories (RSR)

:toc: left
:toclevels: 3
:icons: font
:source-highlighter: rouge
:experimental:

image::https://img.shields.io/badge/RSR-Gold%20(100%25)-ffd700[RSR Compliance,link=https://gitlab.com/hyperpolymath/rhodium-standard-repositories]
image::https://img.shields.io/badge/CCCP-Certified-red[CCCP]

== Overview

The *Rhodium Standard Repository (RSR)* framework provides comprehensive standards for emotionally safe, technically excellent, and politically autonomous software development. It embodies the principles of the *Campaign for Cooler Coding and Programming (CCCP)*.

=== Why "Rhodium"?

Rhodium is the *rarest and most precious* of all metals, chosen for specific symbolic properties:

* **Rarest precious metal**: Excellence over ubiquity
* **Catalytic role**: Transforms toxic outputs into safer alternatives
* **Wedding ring plating**: Durability for long-term commitments and maintainability
* **Corrosion resistance**: Systems that don't decay under pressure

=== Core Principles

[cols="1,3",options="header"]
|===
| Principle | Description

| Emotional Safety
| Reversibility, safe experimentation, no shame in mistakes

| Offline-First
| Work continues without constant connectivity

| Post-JavaScript Liberation
| Rejecting npm/node ecosystem fragility

| Formal Verification
| Correctness as mutual aid

| Community Over Ego
| Architecture enforces collaborative patterns

| Language Polyglotism
| Using Ada, Chapel, Elixir, Haskell, Julia, ReScript, Rust instead of JavaScript/Python monoculture
|===

=== AI Context Files

RSR repositories include machine-readable A2ML files for AI assistant context preservation,
located in `.machine_readable/6a2/`:

[cols="1,3",options="header"]

|===

| File | Purpose

| `.machine_readable/6a2/META.a2ml`

| Architecture decisions (ADRs), development practices, design rationale

| `.machine_readable/6a2/ECOSYSTEM.a2ml`

| Project ecosystem position, relationships, explicit boundaries

| `.machine_readable/6a2/STATE.a2ml`

| Current project state, progress tracking, session continuity

| `.machine_readable/6a2/AGENTIC.a2ml`

| AI agent constraints, gating policies, entropy budgets

| `.machine_readable/6a2/NEUROSYM.a2ml`

| Neurosymbolic integration config for Hypatia scanning

| `.machine_readable/6a2/PLAYBOOK.a2ml`

| Operational runbooks, release and incident procedures

|===

NOTE: The estate migrated from Guile Scheme (`.scm`) to A2ML (`.a2ml`) format on
2026-04-12. The canonical path is `.machine_readable/6a2/<FILE>.a2ml`. Legacy `.scm`
files are deprecated. See link:../state-a2ml/[state-a2ml] for the A2ML state spec.

These files work alongside `.claude/CLAUDE.md` (or similar AI instruction files) to provide structured context that persists across AI conversation sessions. See link:docs/ai-context-files.md[AI Context Files Specification] for complete documentation and links to the specification repositories.

== Quick Start

[source,bash]
----
# Clone the repository
git clone https://gitlab.com/hyperpolymath/rhodium-standard-repositories.git
cd rhodium-standard-repositories

# Enter Nix development environment
nix develop

# Run audit on your repository
./rsr-audit.sh /path/to/your/repo

# Validate RSR compliance
just validate

# See all available tasks
just --list
----

== Project Structure

[source]
----
rhodium-standard-repositories/
├── examples/                    # Example RSR-compliant repositories
│   ├── rhodium-minimal/        # Minimal CLI tool (Silver+ compliance)
│   ├── rhodium-web/            # Web application (planned)
│   └── rhodium-service/        # Backend service (planned)
├── templates/                   # Repository templates
│   ├── rust-cli/               # Rust CLI application template
│   ├── elixir-service/         # Elixir OTP service template
│   └── rescript-web/           # ReScript web application template
├── docs/                        # Comprehensive documentation
│   ├── haskell-registry-design.md  # Validation service design
│   ├── standards/              # Individual standard specifications
│   └── guides/                 # Implementation guides
├── rsr-audit.sh                # Compliance audit script
├── CLAUDE.md                   # AI assistant guidance
├── COMPLIANCE_CHECKLIST.md     # Detailed compliance checklist
└── README.adoc                 # This file
----

== Features

=== RSR Audit System

Comprehensive compliance checking with 100+ automated tests:

[source,bash]
----
# Text output (default)
./rsr-audit.sh /path/to/repo

# JSON output (for CI/CD)
./rsr-audit.sh /path/to/repo json

# HTML report
./rsr-audit.sh /path/to/repo html > report.html
----

==== Compliance Levels

[cols="1,1,3",options="header"]
|===
| Level | Score | Description

| 🏆 Gold
| 100%
| Full RSR compliance, exemplar repository

| 🥈 Silver
| 90-99%
| Strong compliance, production-ready

| 🥉 Bronze
| 75-89%
| Basic compliance, good foundation

| ❌ Non-Compliant
| <75%
| Below minimum standards
|===

==== Exit Codes

* `0` - Gold compliance (100%)
* `1` - Silver compliance (90-99%)
* `2` - Bronze compliance (75-89%)
* `3` - Non-compliant (<75%)
* `4` - Error running audit

=== Haskell Registry (Planned)

Production-grade validation service providing:

* Cryptographic attestations (Ed25519 signatures)
* Public compliance registry
* Badge generation (shields.io integration)
* JSON-LD attestation format
* 90-day validity periods

See link:docs/haskell-registry-design.md[Haskell Registry Design] for complete specification.

== RSR Compliance Categories

The RSR framework validates 11 comprehensive categories:

. **Foundational Infrastructure**: Nix, Justfile, GitLab CI, Podman, Git configuration
. **Documentation Standards**: README, LICENSE, SECURITY, CODE_OF_CONDUCT, CONTRIBUTING, .well-known/
. **Security Architecture**: Type safety, memory safety, SPDX headers, supply chain security
. **Architecture Principles**: Offline-first, CRDTs, reversibility, reproducibility
. **Web Standards & Protocols**: DNS, TLS, HTTP security headers (if applicable)
. **Semantic Web & IndieWeb**: Schema.org, RDF, Webmention (if applicable)
. **FOSS & Licensing**: License clarity, contributor rights, funding transparency
. **Cognitive Ergonomics**: Information architecture, accessibility, i18n
. **Lifecycle Management**: Dependency management, SemVer, EOL planning
. **Community & Governance**: TPCF framework, CoC, governance model
. **Mutually Assured Accountability**: MAA principles, audit trails, provenance

See link:COMPLIANCE_CHECKLIST.md[Compliance Checklist] for detailed requirements.

== Installation

=== Prerequisites

* Nix with flakes enabled
* Podman (for containerized examples)
* Just task runner
* Git

=== Nix Development Environment

[source,bash]
----
# Enter development shell
nix develop

# Build all examples
just build-all

# Run tests
just test-all

# Validate compliance
just validate
----

=== Manual Installation

[source,bash]
----
# Install dependencies (example for Debian/Ubuntu)
curl -L https://nixos.org/nix/install | sh
apt-get install podman just git

# Clone repository
git clone https://gitlab.com/hyperpolymath/rhodium-standard-repositories.git
cd rhodium-standard-repositories

# Make audit script executable
chmod +x rsr-audit.sh
----

== Usage

=== Auditing Your Repository

[source,bash]
----
# Audit current directory
./rsr-audit.sh .

# Audit specific repository
./rsr-audit.sh /path/to/repo

# Get JSON output for CI/CD
./rsr-audit.sh . json | jq '.score'
----

=== Creating a New RSR-Compliant Repository

[source,bash]
----
# Copy template
cp -r templates/rust-cli my-new-project
cd my-new-project

# Initialize
just init

# Customize
$EDITOR README.adoc LICENSE.txt SECURITY.md

# Validate
just validate
----

=== Integrating with CI/CD

.GitLab CI Example
[source,yaml]
----
rsr-compliance:
  stage: validate
  script:
    - wget https://gitlab.com/hyperpolymath/rhodium-standard-repositories/-/raw/main/rsr-audit.sh
    - chmod +x rsr-audit.sh
    - ./rsr-audit.sh . json > audit.json
    - cat audit.json
  artifacts:
    reports:
      codequality: audit.json
    paths:
      - audit.json
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
----

== Examples

=== Rhodium Minimal

A minimal CLI tool demonstrating Silver+ RSR compliance:

[source,bash]
----
cd examples/rhodium-minimal
just build
just test
./target/debug/rhodium-minimal --help
----

Features:
* Rust for memory safety
* Complete TPCF documentation
* .well-known/ directory with all files
* SPDX headers on all source files
* Comprehensive governance (GOVERNANCE.md)
* Funding transparency (FUNDING.yml)

== Contributing

We welcome contributions! Please read our contribution guidelines:

* link:CONTRIBUTING.adoc[Contributing Guide] - How to contribute
* link:CODE_OF_CONDUCT.adoc[Code of Conduct] - Community standards
* link:GOVERNANCE.adoc[Governance] - Decision-making process
* link:SECURITY.md[Security Policy] - Reporting vulnerabilities

=== Tri-Perimeter Contribution Framework (TPCF)

RSR uses a graduated trust model:

* 🔒 *Perimeter 1 (Core)*: Maintainers only - shell runtime, build systems
* 🧠 *Perimeter 2 (Expert)*: Trusted contributors - protocol extensions, validators
* 🌱 *Perimeter 3 (Community)*: Open to all - docs, tests, proposals

See link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] for details.

== Documentation

=== Core Documents

* link:CLAUDE.md[CLAUDE.md] - AI assistant guidance for working with RSR
* link:COMPLIANCE_CHECKLIST.md[Compliance Checklist] - Detailed 150+ point checklist
* link:CCCP-MANIFESTO.md[CCCP Manifesto] - Campaign for Cooler Coding and Programming
* link:RSR-AUDIT-GUIDE.md[Audit Guide] - Using the audit system
* link:RSR-AUDIT-SHOWCASE.md[Audit Showcase] - Complete audit system overview

=== Additional Resources

* link:docs/haskell-registry-design.md[Haskell Registry Design] - Validation service architecture
* link:PROJECT-STATUS.md[Project Status] - Current development status
* link:MAINTAINERS.adoc[Maintainers] - Project maintainers and contributors

== License

This project is dual-licensed under:

* *Palimpsest-MPL-1.0 License* - Permissive open source license
* *Palimpsest License v0.8* - Ethical AI and attribution framework

See link:LICENSE.txt[LICENSE.txt] for complete terms.

Key points:

* ✅ Commercial use allowed with attribution
* ✅ Modification and distribution permitted
* ✅ Open-source AI training allowed
* ❌ Proprietary AI training prohibited
* ❌ Attribution stripping prohibited

== Funding

This project is supported by:

* OpenCollective: https://opencollective.com/rhodium-standard
* GitLab Sponsors: https://gitlab.com/hyperpolymath

See link:FUNDING.yml[FUNDING.yml] for all funding options.

== Support

* *Issues*: https://gitlab.com/hyperpolymath/rhodium-standard-repositories/-/issues
* *Merge Requests*: https://gitlab.com/hyperpolymath/rhodium-standard-repositories/-/merge_requests
* *Discussions*: https://gitlab.com/hyperpolymath/rhodium-standard-repositories/-/issues (use ~discussion label)
* *Email*: rhodium-standard@proton.me

== Roadmap

.Short Term (Q1 2025)
* [x] RSR audit system
* [x] Rhodium-minimal example (Silver+ compliance)
* [ ] Complete Haskell registry implementation
* [ ] Additional example repositories (web, service)

.Medium Term (Q2-Q3 2025)
* [ ] Repository templates for all major languages
* [ ] Integration with popular CI/CD platforms
* [ ] Community registry of RSR-compliant repositories
* [ ] Certification process for Gold compliance

.Long Term (2025+)
* [ ] RSR IDE extensions (VS Code, Vim, Emacs)
* [ ] Automated compliance repair tools
* [ ] Industry adoption and case studies
* [ ] Academic partnerships for formal verification research

== Acknowledgments

The Rhodium Standard builds on decades of best practices from:

* IndieWeb community
* Semantic Web initiative
* FOSS movement and copyleft tradition
* Formal methods research (SPARK, Coq, TLA+)
* Erlang/OTP fault tolerance patterns
* CRDTs and distributed systems research

See link:MAINTAINERS.adoc[MAINTAINERS.md] and link:.well-known/humans.txt[humans.txt] for contributor attribution.

== Citation

If you use RSR in academic work, please cite:

[source,bibtex]
----
@misc{rhodium-standard-2025,
  title={Rhodium Standard Repositories: A Framework for Emotionally Safe, Technically Excellent Software Development},
  author={The Rhodium Standard Contributors},
  year={2025},
  howpublished={\url{https://gitlab.com/hyperpolymath/rhodium-standard-repositories}},
  note={Campaign for Cooler Coding and Programming (CCCP)}
}
----

---

_"We build systems that don't decay under pressure, communities that support experimentation without shame, and infrastructure that respects human autonomy."_

— The Rhodium Standard
