Create roadmap and README documentation

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._

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_