Skip to content

Commit 6def578

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
authored
Add comprehensive README and development roadmap (#4)
- 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 Co-authored-by: Claude <noreply@anthropic.com>
1 parent 68be488 commit 6def578

2 files changed

Lines changed: 245 additions & 4 deletions

File tree

‎README.adoc‎

Lines changed: 125 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,133 @@
1-
= Standards
1+
= Hyperpolymath Standards
22
:toc: auto
3+
:toc-placement!:
4+
:icons: font
35

4-
Organization-wide standards and specifications for the Hyperpolymath ecosystem.
6+
Organization-wide standards, specifications, and governance templates for the Hyperpolymath ecosystem.
7+
8+
toc::[]
59

610
== Overview
711

8-
Canonical standards, specifications, and documentation governing all Hyperpolymath projects.
12+
This repository serves as the canonical source for policies, templates, and specifications governing all Hyperpolymath projects. It provides:
13+
14+
* **Language Policy** — Which languages and tools are permitted across the ecosystem
15+
* **Governance Templates** — Reusable CODE_OF_CONDUCT, CONTRIBUTING, and SECURITY documents
16+
* **Licensing Framework** — Dual MIT/AGPL-3.0-or-later with Palimpsest philosophical principles
17+
* **Infrastructure** — Multi-forge synchronization and CI/CD workflows
18+
19+
== Contents
20+
21+
=== Language Policy
22+
23+
The link:.claude/CLAUDE.md[Hyperpolymath Language Policy] defines the technology stack permitted across all projects:
24+
25+
[cols="1,2,2", options="header"]
26+
|===
27+
|Category |Allowed |Banned
28+
29+
|**Primary Languages**
30+
|ReScript, Rust, Gleam
31+
|TypeScript, Go, Java/Kotlin
32+
33+
|**Runtime**
34+
|Deno
35+
|Node.js, npm, Bun, pnpm, yarn
36+
37+
|**Mobile**
38+
|Tauri 2.0+, Dioxus
39+
|React Native, Flutter/Dart, Swift, Kotlin
40+
41+
|**Config**
42+
|Nickel, Guile Scheme
43+
|—
44+
45+
|**Special Purpose**
46+
|Python (SaltStack only), Julia (batch), OCaml (AffineScript), Ada (safety-critical)
47+
|Python (general)
48+
|===
49+
50+
*Rationale:* Preference for FOSS tools with independent governance (no Big Tech dependencies), type safety, and Rust-first mobile development.
51+
52+
=== Governance Templates
53+
54+
Reusable templates with `{{PLACEHOLDER}}` values for consistent project governance:
55+
56+
* `CODE_OF_CONDUCT.md` — Based on Contributor Covenant 2.1 with perimeter-based enforcement
57+
* `CONTRIBUTING.md` — Development workflow, branch naming, commit conventions
58+
* `SECURITY.md` — Vulnerability reporting, disclosure policy, safe harbour provisions
59+
60+
=== Palimpsest Principles
61+
62+
The licensing framework includes a non-binding philosophical overlay encouraging:
63+
64+
* **Consent-based digital interaction** — Explicit permission for data use
65+
* **Transparent AI training practices** — Opt-in rather than opt-out
66+
* **Preservation of metadata and attribution** — Maintaining creative lineage
67+
* **Protection of narrative intent** — Respecting cultural context
68+
69+
See: https://github.com/hyperpolymath/palimpsest-license[Palimpsest License]
70+
71+
=== Infrastructure
72+
73+
* **Instant Forge Sync** — GitHub Actions workflow triggering propagation to all forges on push/release
74+
* **CodeQL Analysis** — Automated security scanning
75+
* **Issue Templates** — Standardized bug reports, feature requests, documentation issues, questions
76+
77+
== Usage
78+
79+
=== For New Hyperpolymath Projects
80+
81+
1. Copy templates to your repository
82+
2. Replace all `{{PLACEHOLDER}}` values
83+
3. Add the language policy to `.claude/CLAUDE.md`
84+
4. Configure forge sync (requires `FARM_DISPATCH_TOKEN`)
85+
86+
=== For Contributors
87+
88+
* Read the link:.claude/CLAUDE.md[Language Policy] before proposing code
89+
* Follow the template in `CONTRIBUTING.md` for your project
90+
* Report security issues per `SECURITY.md`
91+
92+
== Repository Structure
93+
94+
[source]
95+
----
96+
standards/
97+
├── .claude/
98+
│ └── CLAUDE.md # Language policy
99+
├── .github/
100+
│ ├── ISSUE_TEMPLATE/ # Bug, feature, docs, question templates
101+
│ ├── workflows/ # CI/CD workflows
102+
│ ├── FUNDING.yml # Sponsorship links
103+
│ └── dependabot.yml # Dependency updates
104+
├── CODE_OF_CONDUCT.md # Template
105+
├── CONTRIBUTING.md # Template
106+
├── SECURITY.md # Template
107+
├── LICENSE.txt # MIT OR AGPL-3.0-or-later + Palimpsest
108+
├── ROADMAP.adoc # Development roadmap
109+
└── README.adoc # This file
110+
----
111+
112+
== Related Projects
113+
114+
* https://github.com/hyperpolymath/palimpsest-license[Palimpsest License] — Consent-based licensing framework
115+
* https://github.com/hyperpolymath[Hyperpolymath Organization] — All ecosystem projects
9116

10117
== License
11118

12-
AGPL-3.0-or-later
119+
Dual-licensed under MIT OR AGPL-3.0-or-later (your choice).
120+
121+
See link:LICENSE.txt[LICENSE.txt] for full terms and Palimpsest philosophical overlay.
122+
123+
== Contributing
124+
125+
This is a standards repository. To propose changes:
126+
127+
1. Open a Discussion for major policy changes
128+
2. Submit an Issue for template improvements
129+
3. PRs welcome for typos, clarifications, and infrastructure fixes
130+
131+
---
132+
133+
_Canonical standards for the Hyperpolymath ecosystem._

‎ROADMAP.adoc‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
= Hyperpolymath Standards Roadmap
2+
:toc: auto
3+
:icons: font
4+
5+
Development roadmap for the Hyperpolymath standards and specifications repository.
6+
7+
== Current State
8+
9+
=== Implemented
10+
11+
[cols="1,3,1", options="header"]
12+
|===
13+
|Component |Description |Status
14+
15+
|**Language Policy**
16+
|Comprehensive allowed/banned language specification in `.claude/CLAUDE.md`
17+
|Complete
18+
19+
|**License Framework**
20+
|Dual MIT/AGPL-3.0-or-later with Palimpsest philosophical overlay
21+
|Complete
22+
23+
|**Governance Templates**
24+
|CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md with placeholder system
25+
|Complete
26+
27+
|**Issue Templates**
28+
|Bug report, feature request, documentation, question templates
29+
|Complete
30+
31+
|**Forge Sync**
32+
|Instant propagation workflow to multiple forges
33+
|Complete
34+
35+
|**Security Scanning**
36+
|CodeQL workflow integration
37+
|Complete
38+
|===
39+
40+
== Planned Development
41+
42+
=== Phase 1: Template Expansion
43+
44+
* [ ] **GOVERNANCE.md template** — Decision-making processes, roles, voting procedures
45+
* [ ] **MAINTAINERS.md template** — Maintainer list format with contact and responsibility areas
46+
* [ ] **CHANGELOG.md template** — Standardized changelog format (Keep a Changelog compliant)
47+
* [ ] **ADR template** — Architecture Decision Records format for technical decisions
48+
* [ ] **RFC template** — Request for Comments process for major proposals
49+
50+
=== Phase 2: Tooling Specifications
51+
52+
* [ ] **justfile standard** — Common task runner commands across projects
53+
* [ ] **flake.nix template** — Standardized Nix flake structure
54+
* [ ] **guix.scm template** — Guix package definition template
55+
* [ ] **deno.json template** — Deno configuration with import maps
56+
* [ ] **.editorconfig** — Consistent editor settings across projects
57+
58+
=== Phase 3: Documentation Standards
59+
60+
* [ ] **API documentation standard** — Required sections, format, examples
61+
* [ ] **README structure guide** — Minimum required sections for project READMEs
62+
* [ ] **Diagram conventions** — Preferred formats (Mermaid, PlantUML, D2)
63+
* [ ] **Versioning policy** — SemVer interpretation and pre-release conventions
64+
65+
=== Phase 4: Security & Compliance
66+
67+
* [ ] **Dependency policy** — Allowed sources, pinning requirements, audit procedures
68+
* [ ] **Cryptography standards** — Approved algorithms, key management practices
69+
* [ ] **SBOM requirements** — Software Bill of Materials generation and format
70+
* [ ] **Signing policy** — Commit signing, release signing, key distribution
71+
72+
=== Phase 5: Ecosystem Integration
73+
74+
* [ ] **Project template repository** — Cookiecutter/copier template for new projects
75+
* [ ] **Compliance checker** — Automated validation of projects against standards
76+
* [ ] **Badge system** — Visual indicators of standards compliance
77+
* [ ] **Migration guides** — Transitioning existing projects to Hyperpolymath standards
78+
79+
== Conceptual Work
80+
81+
=== Palimpsest License Development
82+
83+
The Palimpsest philosophical overlay referenced in `LICENSE.txt` represents ongoing conceptual work on:
84+
85+
* **Consent-based data use** — Framework for explicit permission in digital contexts
86+
* **AI training transparency** — Standards for disclosing training data sources
87+
* **Attribution preservation** — Technical and legal mechanisms for creative lineage
88+
* **Narrative intent protection** — Safeguarding cultural and contextual meaning
89+
90+
See: https://github.com/hyperpolymath/palimpsest-license[palimpsest-license repository]
91+
92+
=== Language Policy Evolution
93+
94+
The language policy may expand to include:
95+
96+
* **WebAssembly guidelines** — WASM compilation targets and toolchains
97+
* **Database preferences** — SQLite, PostgreSQL, SurrealDB recommendations
98+
* **Protocol specifications** — Preferred serialization (MessagePack, Protobuf)
99+
* **Testing frameworks** — Approved testing tools per language
100+
101+
== Contributing to the Roadmap
102+
103+
To propose additions or changes to this roadmap:
104+
105+
1. **Discuss first** — Open a Discussion to gauge interest and gather feedback
106+
2. **Create an Issue** — Document the specific proposal with rationale
107+
3. **Submit a PR** — If approved, update this ROADMAP.adoc and relevant templates
108+
109+
== Non-Goals
110+
111+
This repository does *not* aim to provide:
112+
113+
* Executable code or libraries (standards only)
114+
* Project-specific configurations
115+
* Runtime dependencies
116+
* Opinionated application architectures
117+
118+
---
119+
120+
_Last updated: 2025-12_

0 commit comments

Comments
 (0)