From 10220af11932e1b6fc6c05f14846bfa18de9854c Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 26 Dec 2025 14:03:30 +0000 Subject: [PATCH] Add comprehensive README and development roadmap - Expand README.adoc with full documentation of repository contents - Document language policy, governance templates, Palimpsest principles - Add usage instructions for new projects and contributors - Create ROADMAP.adoc outlining planned phases: - Template expansion (GOVERNANCE, MAINTAINERS, ADR, RFC) - Tooling specifications (justfile, flake.nix, guix.scm) - Documentation standards - Security & compliance - Ecosystem integration --- README.adoc | 129 +++++++++++++++++++++++++++++++++++++++++++++++++-- ROADMAP.adoc | 120 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 245 insertions(+), 4 deletions(-) create mode 100644 ROADMAP.adoc diff --git a/README.adoc b/README.adoc index 60ebbd7..fbbe137 100644 --- a/README.adoc +++ b/README.adoc @@ -1,12 +1,133 @@ -= Standards += Hyperpolymath Standards :toc: auto +:toc-placement!: +:icons: font -Organization-wide standards and specifications for the Hyperpolymath ecosystem. +Organization-wide standards, specifications, and governance templates for the Hyperpolymath ecosystem. + +toc::[] == Overview -Canonical standards, specifications, and documentation governing all Hyperpolymath projects. +This repository serves as the canonical source for policies, templates, and specifications governing all Hyperpolymath projects. It provides: + +* **Language Policy** — Which languages and tools are permitted across the ecosystem +* **Governance Templates** — Reusable CODE_OF_CONDUCT, CONTRIBUTING, and SECURITY documents +* **Licensing Framework** — Dual MIT/AGPL-3.0-or-later with Palimpsest philosophical principles +* **Infrastructure** — Multi-forge synchronization and CI/CD workflows + +== Contents + +=== Language Policy + +The link:.claude/CLAUDE.md[Hyperpolymath Language Policy] defines the technology stack permitted across all projects: + +[cols="1,2,2", options="header"] +|=== +|Category |Allowed |Banned + +|**Primary Languages** +|ReScript, Rust, Gleam +|TypeScript, Go, Java/Kotlin + +|**Runtime** +|Deno +|Node.js, npm, Bun, pnpm, yarn + +|**Mobile** +|Tauri 2.0+, Dioxus +|React Native, Flutter/Dart, Swift, Kotlin + +|**Config** +|Nickel, Guile Scheme +|— + +|**Special Purpose** +|Python (SaltStack only), Julia (batch), OCaml (AffineScript), Ada (safety-critical) +|Python (general) +|=== + +*Rationale:* Preference for FOSS tools with independent governance (no Big Tech dependencies), type safety, and Rust-first mobile development. + +=== Governance Templates + +Reusable templates with `{{PLACEHOLDER}}` values for consistent project governance: + +* `CODE_OF_CONDUCT.md` — Based on Contributor Covenant 2.1 with perimeter-based enforcement +* `CONTRIBUTING.md` — Development workflow, branch naming, commit conventions +* `SECURITY.md` — Vulnerability reporting, disclosure policy, safe harbour provisions + +=== Palimpsest Principles + +The licensing framework includes a non-binding philosophical overlay encouraging: + +* **Consent-based digital interaction** — Explicit permission for data use +* **Transparent AI training practices** — Opt-in rather than opt-out +* **Preservation of metadata and attribution** — Maintaining creative lineage +* **Protection of narrative intent** — Respecting cultural context + +See: https://github.com/hyperpolymath/palimpsest-license[Palimpsest License] + +=== Infrastructure + +* **Instant Forge Sync** — GitHub Actions workflow triggering propagation to all forges on push/release +* **CodeQL Analysis** — Automated security scanning +* **Issue Templates** — Standardized bug reports, feature requests, documentation issues, questions + +== Usage + +=== For New Hyperpolymath Projects + +1. Copy templates to your repository +2. Replace all `{{PLACEHOLDER}}` values +3. Add the language policy to `.claude/CLAUDE.md` +4. Configure forge sync (requires `FARM_DISPATCH_TOKEN`) + +=== For Contributors + +* Read the link:.claude/CLAUDE.md[Language Policy] before proposing code +* Follow the template in `CONTRIBUTING.md` for your project +* Report security issues per `SECURITY.md` + +== Repository Structure + +[source] +---- +standards/ +├── .claude/ +│ └── CLAUDE.md # Language policy +├── .github/ +│ ├── ISSUE_TEMPLATE/ # Bug, feature, docs, question templates +│ ├── workflows/ # CI/CD workflows +│ ├── FUNDING.yml # Sponsorship links +│ └── dependabot.yml # Dependency updates +├── CODE_OF_CONDUCT.md # Template +├── CONTRIBUTING.md # Template +├── SECURITY.md # Template +├── LICENSE.txt # MIT OR AGPL-3.0-or-later + Palimpsest +├── ROADMAP.adoc # Development roadmap +└── README.adoc # This file +---- + +== Related Projects + +* https://github.com/hyperpolymath/palimpsest-license[Palimpsest License] — Consent-based licensing framework +* https://github.com/hyperpolymath[Hyperpolymath Organization] — All ecosystem projects == License -AGPL-3.0-or-later +Dual-licensed under MIT OR AGPL-3.0-or-later (your choice). + +See link:LICENSE.txt[LICENSE.txt] for full terms and Palimpsest philosophical overlay. + +== Contributing + +This is a standards repository. To propose changes: + +1. Open a Discussion for major policy changes +2. Submit an Issue for template improvements +3. PRs welcome for typos, clarifications, and infrastructure fixes + +--- + +_Canonical standards for the Hyperpolymath ecosystem._ diff --git a/ROADMAP.adoc b/ROADMAP.adoc new file mode 100644 index 0000000..1c1a88e --- /dev/null +++ b/ROADMAP.adoc @@ -0,0 +1,120 @@ += Hyperpolymath Standards Roadmap +:toc: auto +:icons: font + +Development roadmap for the Hyperpolymath standards and specifications repository. + +== Current State + +=== Implemented + +[cols="1,3,1", options="header"] +|=== +|Component |Description |Status + +|**Language Policy** +|Comprehensive allowed/banned language specification in `.claude/CLAUDE.md` +|Complete + +|**License Framework** +|Dual MIT/AGPL-3.0-or-later with Palimpsest philosophical overlay +|Complete + +|**Governance Templates** +|CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md with placeholder system +|Complete + +|**Issue Templates** +|Bug report, feature request, documentation, question templates +|Complete + +|**Forge Sync** +|Instant propagation workflow to multiple forges +|Complete + +|**Security Scanning** +|CodeQL workflow integration +|Complete +|=== + +== Planned Development + +=== Phase 1: Template Expansion + +* [ ] **GOVERNANCE.md template** — Decision-making processes, roles, voting procedures +* [ ] **MAINTAINERS.md template** — Maintainer list format with contact and responsibility areas +* [ ] **CHANGELOG.md template** — Standardized changelog format (Keep a Changelog compliant) +* [ ] **ADR template** — Architecture Decision Records format for technical decisions +* [ ] **RFC template** — Request for Comments process for major proposals + +=== Phase 2: Tooling Specifications + +* [ ] **justfile standard** — Common task runner commands across projects +* [ ] **flake.nix template** — Standardized Nix flake structure +* [ ] **guix.scm template** — Guix package definition template +* [ ] **deno.json template** — Deno configuration with import maps +* [ ] **.editorconfig** — Consistent editor settings across projects + +=== Phase 3: Documentation Standards + +* [ ] **API documentation standard** — Required sections, format, examples +* [ ] **README structure guide** — Minimum required sections for project READMEs +* [ ] **Diagram conventions** — Preferred formats (Mermaid, PlantUML, D2) +* [ ] **Versioning policy** — SemVer interpretation and pre-release conventions + +=== Phase 4: Security & Compliance + +* [ ] **Dependency policy** — Allowed sources, pinning requirements, audit procedures +* [ ] **Cryptography standards** — Approved algorithms, key management practices +* [ ] **SBOM requirements** — Software Bill of Materials generation and format +* [ ] **Signing policy** — Commit signing, release signing, key distribution + +=== Phase 5: Ecosystem Integration + +* [ ] **Project template repository** — Cookiecutter/copier template for new projects +* [ ] **Compliance checker** — Automated validation of projects against standards +* [ ] **Badge system** — Visual indicators of standards compliance +* [ ] **Migration guides** — Transitioning existing projects to Hyperpolymath standards + +== Conceptual Work + +=== Palimpsest License Development + +The Palimpsest philosophical overlay referenced in `LICENSE.txt` represents ongoing conceptual work on: + +* **Consent-based data use** — Framework for explicit permission in digital contexts +* **AI training transparency** — Standards for disclosing training data sources +* **Attribution preservation** — Technical and legal mechanisms for creative lineage +* **Narrative intent protection** — Safeguarding cultural and contextual meaning + +See: https://github.com/hyperpolymath/palimpsest-license[palimpsest-license repository] + +=== Language Policy Evolution + +The language policy may expand to include: + +* **WebAssembly guidelines** — WASM compilation targets and toolchains +* **Database preferences** — SQLite, PostgreSQL, SurrealDB recommendations +* **Protocol specifications** — Preferred serialization (MessagePack, Protobuf) +* **Testing frameworks** — Approved testing tools per language + +== Contributing to the Roadmap + +To propose additions or changes to this roadmap: + +1. **Discuss first** — Open a Discussion to gauge interest and gather feedback +2. **Create an Issue** — Document the specific proposal with rationale +3. **Submit a PR** — If approved, update this ROADMAP.adoc and relevant templates + +== Non-Goals + +This repository does *not* aim to provide: + +* Executable code or libraries (standards only) +* Project-specific configurations +* Runtime dependencies +* Opinionated application architectures + +--- + +_Last updated: 2025-12_