From 0855751ad000d7b6df766874ff425ef7c99b448c Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:00:51 +0100 Subject: [PATCH] refactor: migrate repository documentation from Markdown to AsciiDoc --- .meta/REQUIRED-FILES.adoc | 58 ++++ .meta/REQUIRED-FILES.md | 57 ---- ABI-FFI-README.md => ABI-FFI-README.adoc | 244 ++++++++-------- CHANGELOG.adoc | 52 ++++ CHANGELOG.md | 48 ---- CODE_OF_CONDUCT.adoc | 339 +++++++++++++++++++++++ CODE_OF_CONDUCT.md | 331 ---------------------- CONTRIBUTING.adoc | 115 +++++++- CONTRIBUTING.md | 120 -------- GOVERNANCE.adoc | 178 +++--------- GOVERNANCE.md | 60 ---- README.adoc | 178 ++++++++++++ README.md | 190 ------------- REQUIRES_INITIALISATION.adoc | 82 ++++++ REQUIRES_INITIALISATION.md | 77 ----- SECURITY.adoc | 56 ++++ SECURITY.md | 52 ---- content/about.adoc | 19 ++ content/about.md | 21 -- content/index.adoc | 15 + content/index.md | 23 -- content/posts/hello-world.adoc | 17 ++ content/posts/hello-world.md | 26 -- docs/tech-debt-2026-05-26.adoc | 71 +++++ docs/tech-debt-2026-05-26.md | 56 ---- site/index.adoc | 20 ++ site/index.md | 29 -- test-features/input/test.adoc | 21 ++ test-features/input/test.md | 40 --- 29 files changed, 1199 insertions(+), 1396 deletions(-) create mode 100644 .meta/REQUIRED-FILES.adoc delete mode 100644 .meta/REQUIRED-FILES.md rename ABI-FFI-README.md => ABI-FFI-README.adoc (74%) create mode 100644 CHANGELOG.adoc delete mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.adoc delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 GOVERNANCE.md create mode 100644 README.adoc delete mode 100644 README.md create mode 100644 REQUIRES_INITIALISATION.adoc delete mode 100644 REQUIRES_INITIALISATION.md create mode 100644 SECURITY.adoc delete mode 100644 SECURITY.md create mode 100644 content/about.adoc delete mode 100644 content/about.md create mode 100644 content/index.adoc delete mode 100644 content/index.md create mode 100644 content/posts/hello-world.adoc delete mode 100644 content/posts/hello-world.md create mode 100644 docs/tech-debt-2026-05-26.adoc delete mode 100644 docs/tech-debt-2026-05-26.md create mode 100644 site/index.adoc delete mode 100644 site/index.md create mode 100644 test-features/input/test.adoc delete mode 100644 test-features/input/test.md diff --git a/.meta/REQUIRED-FILES.adoc b/.meta/REQUIRED-FILES.adoc new file mode 100644 index 0000000..3a85933 --- /dev/null +++ b/.meta/REQUIRED-FILES.adoc @@ -0,0 +1,58 @@ +== Required Repository Files + +The following files *MUST* be present and kept up-to-date in every +repository: + +=== Mandatory Dotfiles + +[cols=",",options="header",] +|=== +|File |Purpose +|`+.gitignore+` |Exclude build artifacts, secrets, and temp files +|`+.gitattributes+` |Enforce LF line endings and diff settings +|`+.editorconfig+` |Consistent editor settings across IDEs +|`+.tool-versions+` |asdf version pinning for reproducible builds +|=== + +=== Mandatory SCM Files + +[cols=",",options="header",] +|=== +|File |Purpose +|`+META.scm+` |Architecture decisions, development practices +|`+STATE.scm+` |Project state, phase, milestones +|`+ECOSYSTEM.scm+` |Ecosystem positioning, related projects +|`+PLAYBOOK.scm+` |Executable plans, procedures +|`+AGENTIC.scm+` |AI agent operational gating +|`+NEUROSYM.scm+` |Symbolic semantics, proof obligations +|=== + +=== Build System + +[cols=",",options="header",] +|=== +|File |Purpose +|`+justfile+` |Task runner (replaces Makefile) +|`+Mustfile+` |Deployment state contract +|=== + +*IMPORTANT*: Makefiles are FORBIDDEN. Use `+just+` for all tasks. + +=== Validation + +These files are checked by: - CI workflow validation - Pre-commit hooks +(when configured) - Repository standardization scripts + +=== Updates + +When updating these files: 1. Use templates from `+rsr-template-repo+` +as reference 2. Ensure SPDX license header is present 3. Test changes +locally before pushing 4. Keep language-specific sections relevant to +the repo + +=== See Also + +* https://github.com/hyperpolymath/rhodium-standard-repositories[RSR +(Rhodium Standard Repositories)] +* https://github.com/hyperpolymath/mustfile[Mustfile Specification] +* https://github.com/hyperpolymath/meta-scm[SCM Format Family] diff --git a/.meta/REQUIRED-FILES.md b/.meta/REQUIRED-FILES.md deleted file mode 100644 index 106daa9..0000000 --- a/.meta/REQUIRED-FILES.md +++ /dev/null @@ -1,57 +0,0 @@ - -# Required Repository Files - -The following files **MUST** be present and kept up-to-date in every repository: - -## Mandatory Dotfiles - -| File | Purpose | -|------|---------| -| `.gitignore` | Exclude build artifacts, secrets, and temp files | -| `.gitattributes` | Enforce LF line endings and diff settings | -| `.editorconfig` | Consistent editor settings across IDEs | -| `.tool-versions` | asdf version pinning for reproducible builds | - -## Mandatory SCM Files - -| File | Purpose | -|------|---------| -| `META.scm` | Architecture decisions, development practices | -| `STATE.scm` | Project state, phase, milestones | -| `ECOSYSTEM.scm` | Ecosystem positioning, related projects | -| `PLAYBOOK.scm` | Executable plans, procedures | -| `AGENTIC.scm` | AI agent operational gating | -| `NEUROSYM.scm` | Symbolic semantics, proof obligations | - -## Build System - -| File | Purpose | -|------|---------| -| `justfile` | Task runner (replaces Makefile) | -| `Mustfile` | Deployment state contract | - -**IMPORTANT**: Makefiles are FORBIDDEN. Use `just` for all tasks. - -## Validation - -These files are checked by: -- CI workflow validation -- Pre-commit hooks (when configured) -- Repository standardization scripts - -## Updates - -When updating these files: -1. Use templates from `rsr-template-repo` as reference -2. Ensure SPDX license header is present -3. Test changes locally before pushing -4. Keep language-specific sections relevant to the repo - -## See Also - -- [RSR (Rhodium Standard Repositories)](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [Mustfile Specification](https://github.com/hyperpolymath/mustfile) -- [SCM Format Family](https://github.com/hyperpolymath/meta-scm) diff --git a/ABI-FFI-README.md b/ABI-FFI-README.adoc similarity index 74% rename from ABI-FFI-README.md rename to ABI-FFI-README.adoc index 139924f..0aa0836 100644 --- a/ABI-FFI-README.md +++ b/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 ~}} -# CASKET_SSG ABI/FFI Documentation +== CASKET_SSG 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, AffineScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -81,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── affinescript/ └── 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/{{project}}.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 "{{project}}.h" int main() { @@ -241,16 +253,19 @@ int main() { {{project}}_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -l{{project}} -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import CASKET_SSG.ABI.Foreign main : IO () @@ -263,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "{{project}}")] extern "C" { fn {{project}}_init() -> *mut std::ffi::c_void; @@ -286,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" 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/{{project}}.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/{{project}}.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/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 0000000..07441e4 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,52 @@ +== Changelog + +All notable changes to `+casket-ssg+` 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(casket-ssg): extract Haskell SSG from archived polystack + +==== Fixed + +* fix(ci): unblock PR queue — bad action SHA pins + .res fixture +exemption (#13) +* fix(ci): sync hypatia-scan.yml to canonical (413: +env.HOME+Phase-2+SARIF) (#5) +* fix(ci): adopt canonical hypatia-scan.yml (env.HOME/scanner-layout + +Comment-step gate) (#3) + +==== Documentation + +* docs(readme): add SPDX header, OSSF and GWF badges + +==== CI + +* ci(release): swap retired macos-13 runner for macos-15-intel (#10) +* ci(release): swap retired macos-13 runner for macos-15-intel (#9) +* ci(release): swap retired macos-13 runner for macos-15-intel (#8) +* ci: bump actions/upload-artifact SHA to current v4 (#2) +* ci(secret-scanner): drop duplicate –fail from trufflehog extra_args +(#1) + +=== 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 ba36531..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,48 +0,0 @@ - -# Changelog - -All notable changes to `casket-ssg` 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(casket-ssg): extract Haskell SSG from archived polystack - -### Fixed - -- fix(ci): unblock PR queue — bad action SHA pins + .res fixture exemption (#13) -- fix(ci): sync hypatia-scan.yml to canonical (413: env.HOME+Phase-2+SARIF) (#5) -- fix(ci): adopt canonical hypatia-scan.yml (env.HOME/scanner-layout + Comment-step gate) (#3) - -### Documentation - -- docs(readme): add SPDX header, OSSF and GWF badges - -### CI - -- ci(release): swap retired macos-13 runner for macos-15-intel (#10) -- ci(release): swap retired macos-13 runner for macos-15-intel (#9) -- ci(release): swap retired macos-13 runner for macos-15-intel (#8) -- ci: bump actions/upload-artifact SHA to current v4 (#2) -- ci(secret-scanner): drop duplicate --fail from trufflehog extra_args (#1) - -## 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..701ef79 --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +Polystack 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, colour, 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. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |j.d.a.jewell@open.ac.uk |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *\{\{RESPONSE_TIME}}* +. The \{\{CONDUCT_TEAM}} will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a \{\{CONDUCT_TEAM}} member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The \{\{CONDUCT_TEAM}} will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. 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. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. 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. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, 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. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* j.d.a.jewell@open.ac.uk with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different \{\{CONDUCT_TEAM}} member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://github.com/hyperpolymath/polystack/discussions[Discussion] (for +general questions) +* Email j.d.a.jewell@open.ac.uk (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index e52ff79..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,331 +0,0 @@ - -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in Polystack 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, colour, 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. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | j.d.a.jewell@open.ac.uk | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. 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. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. 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. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, 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. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** j.d.a.jewell@open.ac.uk with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://github.com/hyperpolymath/polystack/discussions) (for general questions) -- Email j.d.a.jewell@open.ac.uk (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index e9b1993..5dbdb9b 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -1,21 +1,108 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Contributing Guide +== Clone the repository -== Getting Started +git clone https://github.com/hyperpolymath/polystack.git cd polystack -1. Fork the repository -2. Create a feature branch from `main` -3. Sign off commits (`git commit -s`) -4. Submit a pull request +== Using Guix (recommended for reproducibility) -== Commit Guidelines +guix develop -* Conventional commits: `type(scope): description` -* Sign all commits (DCO required) -* Atomic, focused commits +== Or using toolbox/distrobox -== License +toolbox create polystack-dev toolbox enter polystack-dev # Install +dependencies manually -Contributions licensed under project license. +== Verify setup +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +polystack/ ├── 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.guix # Guix +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/polystack/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/polystack/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/polystack/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/polystack/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 9b8ea68..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/polystack.git -cd polystack - -# Using Guix (recommended for reproducibility) -guix develop - -# Or using toolbox/distrobox -toolbox create polystack-dev -toolbox enter polystack-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -polystack/ -├── 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.guix # Guix 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/polystack/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/polystack/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/polystack/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/polystack/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 index f893c5c..9b836fb 100644 --- a/GOVERNANCE.adoc +++ b/GOVERNANCE.adoc @@ -1,162 +1,60 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell -= Governance Model -:toc: preamble +== Governance -This document describes the governance model for this repository. +=== Overview -== Overview +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. -This repository follows a **Sole Maintainer Governance Model**: +=== Roles and Responsibilities -* Single maintainer (@hyperpolymath) has full authority over the project -* All contributions are welcome and reviewed by the maintainer -* Decisions are made transparently through GitHub issues and discussions -* The project adheres to the hyperpolymath estate policies where applicable +==== Maintainers -== Core Principles +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 -[cols="1,2"] -|=== -| Principle | Description +==== Contributors -| **Benevolent Dictatorship** | Maintainer has final decision authority but seeks community input +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 -| **Meritocracy** | Contributions are judged on technical merit, not contributor identity +=== Decision Making -| **Transparency** | All significant decisions are documented publicly +==== Minor Changes -| **Consensus-Seeking** | Maintainer prefers consensus but will decide when necessary +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates -| **Open Contribution** | Anyone can contribute via fork and pull request +==== Major Changes -|=== +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers -== Roles and Permissions +==== Breaking Changes -[cols="1,2,2"] -|=== -| Role | Permissions | Assignment +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide -| **Maintainer** | Write access, merge rights, admin | @hyperpolymath -| **Contributors** | Read access, fork, submit PRs | All GitHub users -| **Users** | Use the software, report issues | All GitHub users +=== Code of Conduct -|=== +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. -== Decision Making Framework +=== Communication -=== Routine Decisions +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions -* Bug fixes -* Documentation improvements -* Minor feature additions -* Dependency updates +=== Licensing -**Process**: Maintainer reviews and merges PRs that meet quality standards. +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. -=== Significant Changes +''''' -* New major features -* API changes -* Architecture modifications -* Breaking changes - -**Process**: -. Open issue describing the change -. Discuss with community (minimum 72 hours) -. Maintainer makes final decision -. Document rationale in issue/PR - -=== Structural Decisions - -* Repository purpose/renaming -* License changes -* Ownership transfer -* Deprecation/archival - -**Process**: -. Extended discussion (minimum 1 week) -. Maintainer makes final decision -. Document in CHANGELOG and governance docs - -== Contribution Lifecycle - -[cols="1,2"] -|=== -| Stage | Process - -| **Ideation** | Open issue, discuss feasibility - -| **Development** | Fork, implement, test thoroughly - -| **Review** | Submit PR, maintainer reviews within 7 days - -| **Merge** | Maintainer merges or requests changes - -| **Release** | Maintainer publishes according to project conventions - -|=== - -== Conflict Resolution - -In case of disagreements: - -. Discuss in the relevant GitHub issue or PR -. Provide technical justification for positions -. Maintainer mediates and makes final decision -. Decision is documented and can be revisited later - -== Project Policies - -This repository adheres to hyperpolymath estate-wide policies: - -* **License**: MPL-2.0 for code, CC-BY-SA-4.0 for prose (per standards/LICENCE-POLICY.adoc) -* **Code of Conduct**: Follows hyperpolymath CODE_OF_CONDUCT.md -* **Security**: Follows hyperpolymath SECURITY.md -* **Contributing**: Follows hyperpolymath CONTRIBUTING.adoc conventions - -== Repository-Specific Conventions - -[cols="1,2"] -|=== -| Convention | Description - -| **Signing** | All commits must be signed (SSH or GPG) - -| **SPDX Headers** | All source files must have SPDX license identifiers - -| **Contractiles** | Mustfile, Trustfile, Intendfile, Adjustfile in root - -| **Machine Readable** | META.a2ml in .machine_readable/descriptiles/ - -| **CI/CD** | GitHub Actions workflows in .github/workflows/ - -|=== - -== Governance Evolution - -As the project grows, this governance model may evolve: - -* **Adding Co-Maintainers**: When contribution volume warrants it -* **Forming a Team**: For complex multi-maintainer projects -* **Adopting TPCF**: For large, multi-repository projects (see rhodium-standard-repositories) - -Changes to this document require the same process as Significant Changes above. - -== See Also - -* link:MAINTAINERS.adoc[Maintainers] -* link:CODE_OF_CONDUCT.md[Code of Conduct] -* link:CONTRIBUTING.adoc[Contributing Guide] -* link:https://github.com/hyperpolymath/standards/blob/main/LICENCE-POLICY.adoc[Estate License Policy] -* link:https://github.com/hyperpolymath/standards[rhodium-standard-repositories (TPCF)] - -== Changelog - -[cols="1,1,1"] -|=== -| Date | Change | By - -| 2026-06-07 | Initial governance model established | @hyperpolymath -|=== +_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/README.adoc b/README.adoc new file mode 100644 index 0000000..dc9c3dd --- /dev/null +++ b/README.adoc @@ -0,0 +1,178 @@ +https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/casket-ssg[image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity[OpenSSF +Best Practices]] +https://github.com/hyperpolymath/casket-ssg/blob/main/LICENSE[image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[License: +MPL-2.0]] +image:https://img.shields.io/badge/a11y-WCAG--aware_by_default-success[Accessibility] +https://github.com/hyperpolymath/poly-ssg[image:https://img.shields.io/badge/part_of-poly--ssg-indigo[poly-ssg]] +https://github.com/hyperpolymath/rhodium-standard-repositories[image:https://img.shields.io/badge/RSR-compliant-gold[RSR +Compliant]] + +*An accessibility-first, metadata-driven static site generator.* +Markdown in, an accessible website out — WCAG-aware output _by default_, +plus a metadata layer (*Gnosis*) that renders pages from typed project +data. The Haskell member of +https://github.com/hyperpolymath/poly-ssg[poly-ssg]. + +____ +[!NOTE] *Status: alpha.* The `+build+` / `+clean+` pipeline works and +generates real sites. Items marked _Planned_ below are not yet +implemented. The engine’s direction — demote Pandoc, adopt a Djot prose +core + `+a2ml+` typed content on the +https://github.com/hyperpolymath/boj-server[boj] substrate — is recorded +in link:docs/decisions/ADR-0001-content-engine.adoc[ADR-0001]. +Architecture & invariants: link:EXPLAINME.adoc[EXPLAINME]. +____ + +[[toc]] + +== Example + +A minimal site is a tree of Markdown with front-matter: + +.... +content/ +├── index.md +└── posts/ + └── 2026-06-23-hello.md +.... + +[source,markdown] +---- +--- +title: Hello, world +date: 2026-06-23 +tags: [intro] +description: A first page built with casket. +--- +# Hello + +Markdown with **rich** formatting, tables, footnotes and highlighted code. +---- + +Build it: + +[source,bash] +---- +casket-ssg build ./content ./_site +---- + +You get an *accessible* `+_site/+` with no configuration: + +* `+index.html+` and `+posts/2026-06-23-hello/index.html+` rendered +through an accessible default theme (skip link, labelled landmarks, +light/dark `+color-scheme+`), with table headers auto-scoped for WCAG +1.3.1; +* a date-sorted collection index for `+posts/+`, and per-tag pages under +`+/tags/+`; +* `+sitemap.xml+` and an Atom `+feed.xml+`. + +No Node, no npm, no required config file. + +== Installation + +casket is not yet on Hackage — build from source (GHC 9.4+, Cabal 3 or +Stack 2): + +[source,bash] +---- +git clone https://github.com/hyperpolymath/casket-ssg +cd casket-ssg +stack build # or: cabal build +stack run casket-ssg -- --version # or put the built binary on PATH +---- + +CLI: + +[source,bash] +---- +casket-ssg build [output-dir] # default output: _site +casket-ssg build --drafts # include draft: true pages (or CASKET_DRAFTS=1) +casket-ssg build --no-clean-urls # emit foo.html, not foo/index.html +casket-ssg clean [output-dir] +casket-ssg --version +---- + +== What makes it different + +Accessibility by construction + +The default theme is accessible by default, casket rewrites Pandoc table +headers to add `+scope="col"+`, and the Gnosis `+FlexiText+` type makes +*empty alt-text a constructor error* — generated badges cannot ship +without alt text. Accessibility is a property of the engine, not a +checklist for the author. + +Metadata-driven (Gnosis) + +An optional layer renders pages from a typed metadata context: +`+(:placeholder)+` substitution, `+{{#if}}+` / `+{{#for}}+` conditionals +and loops (DAX), and Shields.io badges generated from typed values — +sourced from the repo’s `+.machine_readable/descriptiles/+` data. + +Verified & agent-native — the trajectory + +casket is heading toward typed `+a2ml+` content (build fails on +malformed data), a formally-verifiable Djot core, and a verified agent +surface as a https://github.com/hyperpolymath/boj-server[boj] cartridge +rather than an embedded MCP server. See +link:docs/decisions/ADR-0001-content-engine.adoc[ADR-0001]. + +Permissively licensed + +*MPL-2.0* — build proprietary or differently-licensed sites on top, +unlike copyleft alternatives. + +== Features + +*Implemented* + +* Recursive multi-page build mirroring the source tree +* Front-matter: `+title+`, `+date+`, `+description+`, `+layout+`, +`+draft+`, `+tags+`, `+slug+`, plus arbitrary keys as `+{{key}}+` +template vars +* Rich Markdown via Pandoc — anchors, pipe tables, fenced/highlighted +code, footnotes, task lists, strikethrough, smart punctuation +* File templates with per-page `+layout+`, partials (`+{{>+` +`+name}}+`), `+{{nav}}+`, `+{macro}+`, `+{{site.*}}+` (from +`+site.conf+`) +* Collections (date-sorted directory index) and per-tag pages +(`+/tags//+`) +* `+sitemap.xml+` + Atom `+feed.xml+` +* Accessible default theme + automatic `+scope="col"+` on table headers +* Gnosis layer — `+(:placeholder)+`, `+{{#if}}+`/`+{{#for}}+` (DAX), +`+FlexiText+` badges +* Clean URLs, toggleable + +*Planned* (do not assume these work today — see ADR-0001) + +* `+init+` scaffolding and a `+serve+` / live-reload dev server +* Incremental rebuilds; asset fingerprinting +* `+a2ml+`-native typed content + the Djot core; Pandoc relegated to an +importer +* `+boj+` cartridge registration; `+llms.txt+` / per-page machine views + +== Documentation + +* link:EXPLAINME.adoc[EXPLAINME] — architecture & invariants (developer +deep-dive) +* link:docs/decisions/ADR-0001-content-engine.adoc[ADR-0001] — +content-engine direction +* link:CONTRIBUTING.adoc[Contributing] · +link:GOVERNANCE.adoc[Governance] + +== Where it fits + +* https://github.com/hyperpolymath/poly-ssg[*poly-ssg*] — the family of +language-native SSGs casket belongs to, unified via MCP. +* https://github.com/hyperpolymath/ddraig-ssg[*ddraig*] — the +dependently-typed (Idris2) sibling; casket’s "`proven twin`" (casket +validates, ddraig proves). +* https://github.com/hyperpolymath/boj-server[*boj-server*] — the +estate’s verified MCP/capability server casket plugs into as a +cartridge. + +== Requirements + +* GHC 9.4+ (CI builds with 9.4.8), Cabal 3.0+ or Stack 2.0+ +* Pandoc (current library dependency; see ADR-0001 for the planned move +off it) + +== License + +Code: *MPL-2.0* (LICENSE). Prose documentation: `+CC-BY-SA-4.0+`. diff --git a/README.md b/README.md deleted file mode 100644 index b6a511c..0000000 --- a/README.md +++ /dev/null @@ -1,190 +0,0 @@ - - -[![OpenSSF Best Practices](https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity)](https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/casket-ssg) -[![License: MPL-2.0](https://img.shields.io/badge/License-MPL_2.0-blue.svg)](https://github.com/hyperpolymath/casket-ssg/blob/main/LICENSE) -![Accessibility](https://img.shields.io/badge/a11y-WCAG--aware_by_default-success) -[![poly-ssg](https://img.shields.io/badge/part_of-poly--ssg-indigo)](https://github.com/hyperpolymath/poly-ssg) -[![RSR Compliant](https://img.shields.io/badge/RSR-compliant-gold)](https://github.com/hyperpolymath/rhodium-standard-repositories) - -**An accessibility-first, metadata-driven static site generator.** -Markdown in, an accessible website out — WCAG-aware output *by default*, -plus a metadata layer (**Gnosis**) that renders pages from typed project -data. The Haskell member of -[poly-ssg](https://github.com/hyperpolymath/poly-ssg). - -> [!NOTE] -> **Status: alpha.** The `build` / `clean` pipeline works and generates -> real sites. Items marked *Planned* below are not yet implemented. The -> engine’s direction — demote Pandoc, adopt a Djot prose core + `a2ml` -> typed content on the -> [boj](https://github.com/hyperpolymath/boj-server) substrate — is -> recorded in [ADR-0001](docs/decisions/ADR-0001-content-engine.adoc). -> Architecture & invariants: [EXPLAINME](EXPLAINME.adoc). - -
- -
- -# Example - -A minimal site is a tree of Markdown with front-matter: - - content/ - ├── index.md - └── posts/ - └── 2026-06-23-hello.md - -```markdown ---- -title: Hello, world -date: 2026-06-23 -tags: [intro] -description: A first page built with casket. ---- -# Hello - -Markdown with **rich** formatting, tables, footnotes and highlighted code. -``` - -Build it: - -```bash -casket-ssg build ./content ./_site -``` - -You get an **accessible** `_site/` with no configuration: - -- `index.html` and `posts/2026-06-23-hello/index.html` rendered through - an accessible default theme (skip link, labelled landmarks, light/dark - `color-scheme`), with table headers auto-scoped for WCAG 1.3.1; - -- a date-sorted collection index for `posts/`, and per-tag pages under - `/tags/`; - -- `sitemap.xml` and an Atom `feed.xml`. - -No Node, no npm, no required config file. - -# Installation - -casket is not yet on Hackage — build from source (GHC 9.4+, Cabal 3 or -Stack 2): - -```bash -git clone https://github.com/hyperpolymath/casket-ssg -cd casket-ssg -stack build # or: cabal build -stack run casket-ssg -- --version # or put the built binary on PATH -``` - -CLI: - -```bash -casket-ssg build [output-dir] # default output: _site -casket-ssg build --drafts # include draft: true pages (or CASKET_DRAFTS=1) -casket-ssg build --no-clean-urls # emit foo.html, not foo/index.html -casket-ssg clean [output-dir] -casket-ssg --version -``` - -# What makes it different - -Accessibility by construction -The default theme is accessible by default, casket rewrites Pandoc table -headers to add `scope="col"`, and the Gnosis `FlexiText` type makes -**empty alt-text a constructor error** — generated badges cannot ship -without alt text. Accessibility is a property of the engine, not a -checklist for the author. - -Metadata-driven (Gnosis) -An optional layer renders pages from a typed metadata context: -`(:placeholder)` substitution, `{{#if}}` / `{{#for}}` conditionals and -loops (DAX), and Shields.io badges generated from typed values — sourced -from the repo’s `.machine_readable/descriptiles/` data. - -Verified & agent-native — the trajectory -casket is heading toward typed `a2ml` content (build fails on malformed -data), a formally-verifiable Djot core, and a verified agent surface as -a [boj](https://github.com/hyperpolymath/boj-server) cartridge rather -than an embedded MCP server. See -[ADR-0001](docs/decisions/ADR-0001-content-engine.adoc). - -Permissively licensed -**MPL-2.0** — build proprietary or differently-licensed sites on top, -unlike copyleft alternatives. - -# Features - -**Implemented** - -- Recursive multi-page build mirroring the source tree - -- Front-matter: `title`, `date`, `description`, `layout`, `draft`, - `tags`, `slug`, plus arbitrary keys as `{{key}}` template vars - -- Rich Markdown via Pandoc — anchors, pipe tables, fenced/highlighted - code, footnotes, task lists, strikethrough, smart punctuation - -- File templates with per-page `layout`, partials (`{{>` `name}}`), - `{{nav}}`, `{macro}`, `{{site.*}}` (from `site.conf`) - -- Collections (date-sorted directory index) and per-tag pages - (`/tags//`) - -- `sitemap.xml` + Atom `feed.xml` - -- Accessible default theme + automatic `scope="col"` on table headers - -- Gnosis layer — `(:placeholder)`, `{{#if}}`/`{{#for}}` (DAX), - `FlexiText` badges - -- Clean URLs, toggleable - -**Planned** (do not assume these work today — see ADR-0001) - -- `init` scaffolding and a `serve` / live-reload dev server - -- Incremental rebuilds; asset fingerprinting - -- `a2ml`-native typed content + the Djot core; Pandoc relegated to an - importer - -- `boj` cartridge registration; `llms.txt` / per-page machine views - -# Documentation - -- [EXPLAINME](EXPLAINME.adoc) — architecture & invariants (developer - deep-dive) - -- [ADR-0001](docs/decisions/ADR-0001-content-engine.adoc) — - content-engine direction - -- [Contributing](CONTRIBUTING.adoc) · [Governance](GOVERNANCE.adoc) - -# Where it fits - -- [**poly-ssg**](https://github.com/hyperpolymath/poly-ssg) — the family - of language-native SSGs casket belongs to, unified via MCP. - -- [**ddraig**](https://github.com/hyperpolymath/ddraig-ssg) — the - dependently-typed (Idris2) sibling; casket’s "proven twin" (casket - validates, ddraig proves). - -- [**boj-server**](https://github.com/hyperpolymath/boj-server) — the - estate’s verified MCP/capability server casket plugs into as a - cartridge. - -# Requirements - -- GHC 9.4+ (CI builds with 9.4.8), Cabal 3.0+ or Stack 2.0+ - -- Pandoc (current library dependency; see ADR-0001 for the planned move - off it) - -# License - -Code: **MPL-2.0** ([LICENSE](LICENSE)). Prose documentation: -`CC-BY-SA-4.0`. diff --git a/REQUIRES_INITIALISATION.adoc b/REQUIRES_INITIALISATION.adoc new file mode 100644 index 0000000..d5548de --- /dev/null +++ b/REQUIRES_INITIALISATION.adoc @@ -0,0 +1,82 @@ +== REQUIRES INITIALISATION + +*This repository is not finished being set up.* 4 substitution token(s) +across 4 file(s) still have no value. + +=== Why this is not already done + +This repo was created from `+hyperpolymath/rsr-template-repo+`. The mint +(`+just repo-init+`) fills every token that has a single mechanical +answer — owner, repo, author, dates, licence, branch — and it has done +so here. + +The tokens below are the ones it _deliberately cannot_ answer. They need +a decision or a fact that exists only in your head: what this project is +for, what command builds it, which port the service listens on, whether +a PGP key is held at all. The template’s own token vocabulary says as +much — you cannot sensibly answer "`required invariants`" in a +thirty-second bootstrap. + +They were left *visibly unfilled on purpose*. The alternatives were both +worse: inventing plausible values would put confident falsehoods into a +security policy and an architecture document, and silently deleting the +sections would hide the fact that a decision is owed. A visible gap is +honest; a fabricated answer is not. + +=== Do not delete this file until every item below is resolved + +This file is the only marker that the work is outstanding. Deleting it +early does not finish the setup, it just conceals it — and the next +person or agent to arrive will reasonably assume the repo is complete. + +* *If you are a person:* delete this file yourself once the last item is +done. +* *If you are an agent:* resolve what you legitimately can, leave the +rest, and delete this file only when no token below remains anywhere in +the tree. Do not delete it to make a gate go green. + +Re-running the estate top-up tool will remove this file automatically +once nothing is outstanding, so the safest way to finish is to fix the +tokens and let the check confirm it. + +=== What is needed, and where it goes + +==== `+{{ARGS}}+` + +Arguments for the justfile recipe this appears in. + +Appears in: + +* `+.machine_readable/contractiles/Justfile+` +* `+Justfile+` + +==== `+{{CONDUCT_TEAM}}+` + +Name of the conduct body. If there is no committee, rewrite the sentence +rather than substituting a plural noun into '`a \{\{CONDUCT_TEAM}} +member`'. + +Appears in: + +* `+CODE_OF_CONDUCT.md+` + +==== `+{{KEY}}+` + +Appears in: + +* `+docs/guides/templates-and-theming.adoc+` + +==== `+{{RESPONSE_TIME}}+` + +Initial-response SLA for a security or conduct report. Promise only what +a solo maintainer can actually meet. + +Appears in: + +* `+CODE_OF_CONDUCT.md+` + +''''' + +Generated by the estate top-up pass. Rationale and the governing rulings +are in `+hyperpolymath/standards+`; the token vocabulary is +`+.machine_readable/ai/PLACEHOLDERS.adoc+` in `+rsr-template-repo+`. diff --git a/REQUIRES_INITIALISATION.md b/REQUIRES_INITIALISATION.md deleted file mode 100644 index 5de54df..0000000 --- a/REQUIRES_INITIALISATION.md +++ /dev/null @@ -1,77 +0,0 @@ - - -# REQUIRES INITIALISATION - -**This repository is not finished being set up.** 4 substitution token(s) across 4 file(s) still have no value. - -## Why this is not already done - -This repo was created from `hyperpolymath/rsr-template-repo`. The mint -(`just repo-init`) fills every token that has a single mechanical answer — -owner, repo, author, dates, licence, branch — and it has done so here. - -The tokens below are the ones it *deliberately cannot* answer. They need a -decision or a fact that exists only in your head: what this project is for, -what command builds it, which port the service listens on, whether a PGP key -is held at all. The template's own token vocabulary says as much — you cannot -sensibly answer "required invariants" in a thirty-second bootstrap. - -They were left **visibly unfilled on purpose**. The alternatives were both -worse: inventing plausible values would put confident falsehoods into a -security policy and an architecture document, and silently deleting the -sections would hide the fact that a decision is owed. A visible gap is -honest; a fabricated answer is not. - -## Do not delete this file until every item below is resolved - -This file is the only marker that the work is outstanding. Deleting it early -does not finish the setup, it just conceals it — and the next person or agent -to arrive will reasonably assume the repo is complete. - -- **If you are a person:** delete this file yourself once the last item is done. -- **If you are an agent:** resolve what you legitimately can, leave the rest, - and delete this file only when no token below remains anywhere in the tree. - Do not delete it to make a gate go green. - -Re-running the estate top-up tool will remove this file automatically once -nothing is outstanding, so the safest way to finish is to fix the tokens and -let the check confirm it. - -## What is needed, and where it goes - -### `{{ARGS}}` - -Arguments for the justfile recipe this appears in. - -Appears in: - -- `.machine_readable/contractiles/Justfile` -- `Justfile` - -### `{{CONDUCT_TEAM}}` - -Name of the conduct body. If there is no committee, rewrite the sentence rather than substituting a plural noun into 'a {{CONDUCT_TEAM}} member'. - -Appears in: - -- `CODE_OF_CONDUCT.md` - -### `{{KEY}}` - -Appears in: - -- `docs/guides/templates-and-theming.adoc` - -### `{{RESPONSE_TIME}}` - -Initial-response SLA for a security or conduct report. Promise only what a solo maintainer can actually meet. - -Appears in: - -- `CODE_OF_CONDUCT.md` - ---- - -Generated by the estate top-up pass. Rationale and the governing rulings are -in `hyperpolymath/standards`; the token vocabulary is -`.machine_readable/ai/PLACEHOLDERS.adoc` in `rsr-template-repo`. diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..9626070 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,56 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|1.0.x |:white_check_mark: +|< 1.0 |:x: +|=== + +=== Reporting a Vulnerability + +If you discover a security vulnerability, please report it responsibly: + +[arabic] +. *DO NOT* open a public GitHub issue +. Email: [Your security contact] +. Include vulnerability details, reproduction steps, and potential +impact + +==== Response Timeline + +* Initial response: 48 hours +* Status update: 7 days +* Fix timeline based on severity: +** Critical: 7-14 days +** High: 14-30 days +** Medium: 30-60 days + +=== Security Measures + +==== Code Quality + +* ✅ CodeQL security scanning +* ✅ Dependency review on PRs +* ✅ SBOM generation +* ✅ License compliance + +==== Supply Chain + +* ✅ SHA-pinned GitHub Actions +* ✅ Minimal workflow permissions +* ✅ Dependabot updates + +==== Runtime Safety + +* ✅ Type-safe Haskell +* ✅ Tri-Guard sanitization +* ✅ FlexiText accessibility +* ✅ Input validation + +=== Security Advisories + +Published at: +https://github.com/hyperpolymath/casket-ssg/security/advisories diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index f1c0c81..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,52 +0,0 @@ - -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| 1.0.x | :white_check_mark: | -| < 1.0 | :x: | - -## Reporting a Vulnerability - -If you discover a security vulnerability, please report it responsibly: - -1. **DO NOT** open a public GitHub issue -2. Email: [Your security contact] -3. Include vulnerability details, reproduction steps, and potential impact - -### Response Timeline - -- Initial response: 48 hours -- Status update: 7 days -- Fix timeline based on severity: - - Critical: 7-14 days - - High: 14-30 days - - Medium: 30-60 days - -## Security Measures - -### Code Quality -- ✅ CodeQL security scanning -- ✅ Dependency review on PRs -- ✅ SBOM generation -- ✅ License compliance - -### Supply Chain -- ✅ SHA-pinned GitHub Actions -- ✅ Minimal workflow permissions -- ✅ Dependabot updates - -### Runtime Safety -- ✅ Type-safe Haskell -- ✅ Tri-Guard sanitization -- ✅ FlexiText accessibility -- ✅ Input validation - -## Security Advisories - -Published at: https://github.com/hyperpolymath/casket-ssg/security/advisories diff --git a/content/about.adoc b/content/about.adoc new file mode 100644 index 0000000..aa15bcd --- /dev/null +++ b/content/about.adoc @@ -0,0 +1,19 @@ +== About casket-ssg + +casket-ssg is part of the poly-ssg ecosystem, demonstrating static site +generation in Haskell. + +=== Why Haskell? + +Haskell’s strong type system catches errors at compile time, ensuring +reliable transformations from markdown to HTML. Its lazy evaluation and +powerful abstractions like monads make handling file I/O elegant. +Libraries like Pandoc (written in Haskell) demonstrate the language’s +natural fit for document processing. + +=== Learn More + +* https://github.com/hyperpolymath/poly-ssg-mcp[poly-ssg-mcp] - The +unified MCP adapter +* https://github.com/hyperpolymath/poly-ssg[poly-ssg] - Polyglot SSG +framework diff --git a/content/about.md b/content/about.md deleted file mode 100644 index d1e7fbd..0000000 --- a/content/about.md +++ /dev/null @@ -1,21 +0,0 @@ - ---- -title: About -date: 2025-01-18 ---- - -# About casket-ssg - -casket-ssg is part of the poly-ssg ecosystem, demonstrating static site generation in Haskell. - -## Why Haskell? - -Haskell's strong type system catches errors at compile time, ensuring reliable transformations from markdown to HTML. Its lazy evaluation and powerful abstractions like monads make handling file I/O elegant. Libraries like Pandoc (written in Haskell) demonstrate the language's natural fit for document processing. - -## Learn More - -- [poly-ssg-mcp](https://github.com/hyperpolymath/poly-ssg-mcp) - The unified MCP adapter -- [poly-ssg](https://github.com/hyperpolymath/poly-ssg) - Polyglot SSG framework diff --git a/content/index.adoc b/content/index.adoc new file mode 100644 index 0000000..f9b1cf9 --- /dev/null +++ b/content/index.adoc @@ -0,0 +1,15 @@ +== Welcome to casket-ssg + +This is a sample site built with *casket-ssg*, a Haskell-powered static +site generator. + +=== Features + +* Fast builds +* Simple configuration +* Markdown support +* Clean HTML output + +=== Getting Started + +Check out the link:/about[documentation] to learn more. diff --git a/content/index.md b/content/index.md deleted file mode 100644 index 770548c..0000000 --- a/content/index.md +++ /dev/null @@ -1,23 +0,0 @@ - ---- -title: Welcome -date: 2025-01-18 ---- - -# Welcome to casket-ssg - -This is a sample site built with **casket-ssg**, a Haskell-powered static site generator. - -## Features - -- Fast builds -- Simple configuration -- Markdown support -- Clean HTML output - -## Getting Started - -Check out the [documentation](/about) to learn more. diff --git a/content/posts/hello-world.adoc b/content/posts/hello-world.adoc new file mode 100644 index 0000000..ebd58b7 --- /dev/null +++ b/content/posts/hello-world.adoc @@ -0,0 +1,17 @@ +== Hello, World! + +This is the first post on my casket-ssg site. + +=== Code Example + +Here’s a simple example in Haskell: + +[source,haskell] +---- +module Main where + +main :: IO () +main = putStrLn "Hello, World!" +---- + +Happy building! diff --git a/content/posts/hello-world.md b/content/posts/hello-world.md deleted file mode 100644 index 73d9316..0000000 --- a/content/posts/hello-world.md +++ /dev/null @@ -1,26 +0,0 @@ - ---- -title: Hello World -date: 2025-01-18 -draft: false ---- - -# Hello, World! - -This is the first post on my casket-ssg site. - -## Code Example - -Here's a simple example in Haskell: - -```haskell -module Main where - -main :: IO () -main = putStrLn "Hello, World!" -``` - -Happy building! diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..8ebb332 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,71 @@ +== Tech-Debt Audit — casket-ssg — 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:* `+MEDIUM+`. + +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 + +No proof-bearing files (`+*.v+`, `+*.lean+`, `+*.agda+`, `+*.idr+`, +`+*.idr2+`, `+*.fst+`, `+*.dfy+`, `+*.tla+`, `+*.ads+`, `+*.adb+`) found +in this repo. + +*Recommended next move:* none. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+MPL-2.0+` +|Body classifier |`+MPL-some+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |87 +|`+docs/+` files |1 +|`+docs/+` LoC |36 +|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 +87 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 4119244..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,56 +0,0 @@ - -# Tech-Debt Audit — casket-ssg — 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:** `MEDIUM`. - -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 - -No proof-bearing files (`*.v`, `*.lean`, `*.agda`, `*.idr`, `*.idr2`, `*.fst`, `*.dfy`, `*.tla`, `*.ads`, `*.adb`) found in this repo. - -**Recommended next move:** none. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `MPL-2.0` | -| Body classifier | `MPL-some` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 87 | -| `docs/` files | 1 | -| `docs/` LoC | 36 | -| 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 87 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/site/index.adoc b/site/index.adoc new file mode 100644 index 0000000..5d9cdae --- /dev/null +++ b/site/index.adoc @@ -0,0 +1,20 @@ +== casket-ssg + +*Pure functional static site generator in Haskell.* + +=== Features + +* Frontmatter parsing (YAML-style) +* Markdown to HTML conversion +* Mustache-style templates +* Draft post support + +=== Usage + +.... +casket-ssg build [output-dir] +.... + +=== License + +MPL-2.0 diff --git a/site/index.md b/site/index.md deleted file mode 100644 index 6e3158b..0000000 --- a/site/index.md +++ /dev/null @@ -1,29 +0,0 @@ - ---- -title: casket-ssg -date: 2025-01-03 ---- - -# casket-ssg - -**Pure functional static site generator in Haskell.** - -## Features - -- Frontmatter parsing (YAML-style) -- Markdown to HTML conversion -- Mustache-style templates -- Draft post support - -## Usage - -``` -casket-ssg build [output-dir] -``` - -## License - -MPL-2.0 diff --git a/test-features/input/test.adoc b/test-features/input/test.adoc new file mode 100644 index 0000000..456baea --- /dev/null +++ b/test-features/input/test.adoc @@ -0,0 +1,21 @@ +== (:title | capitalize) + +*Author:* (:author) *Project:* (:name) *Version:* (:version) + +=== Download Count Test (Filter) + +Downloads: *(:downloads | thousands-separator)* + +=== Loop Iteration Test + +Tags: \{\{#for tag in tags}} - (:tag | uppercase) \{\{/for}} + +=== Conditional Test + +\{\{#if phase == beta}} ⚠️ This project is in *beta* phase. \{\{/if}} + +=== All Features Working! + +This page tests: 1. ✅ Frontmatter parsing (title, author, date) 2. ✅ +Filter syntax (| capitalize, | thousands-separator, | uppercase) 3. ✅ +Loop iteration (\{\{#for}}) 4. ✅ Conditional rendering (\{\{#if}}) diff --git a/test-features/input/test.md b/test-features/input/test.md deleted file mode 100644 index e3eaf1b..0000000 --- a/test-features/input/test.md +++ /dev/null @@ -1,40 +0,0 @@ - ---- -title: DAX Feature Test Page -author: Test Suite -date: 2026-01-24 ---- - -# (:title | capitalize) - -**Author:** (:author) -**Project:** (:name) -**Version:** (:version) - -## Download Count Test (Filter) - -Downloads: **(:downloads | thousands-separator)** - -## Loop Iteration Test - -Tags: -{{#for tag in tags}} -- (:tag | uppercase) -{{/for}} - -## Conditional Test - -{{#if phase == beta}} -⚠️ This project is in **beta** phase. -{{/if}} - -## All Features Working! - -This page tests: -1. ✅ Frontmatter parsing (title, author, date) -2. ✅ Filter syntax (| capitalize, | thousands-separator, | uppercase) -3. ✅ Loop iteration ({{#for}}) -4. ✅ Conditional rendering ({{#if}})