From d5aad965e7b0d5839dc4823a385c54280db04427 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:53:17 +0100 Subject: [PATCH] refactor: migrate repository documentation from Markdown to AsciiDoc --- CODE_OF_CONDUCT.adoc | 24 ++++ CODE_OF_CONDUCT.md | 27 ----- CONTRIBUTING.adoc | 71 ++++++++++++ CONTRIBUTING.md | 66 ----------- SECURITY.adoc | 25 +++++ SECURITY.md | 22 ---- TEST-NEEDS.adoc | 37 ++++++ TEST-NEEDS.md | 32 ------ TOPOLOGY.md => TOPOLOGY.adoc | 27 +++-- .../{TOPOLOGY.md => TOPOLOGY.adoc} | 105 ++++++++++-------- llm-warmup-dev.adoc | 19 ++++ llm-warmup-dev.md | 17 --- llm-warmup-user.adoc | 19 ++++ llm-warmup-user.md | 17 --- 14 files changed, 272 insertions(+), 236 deletions(-) create mode 100644 CODE_OF_CONDUCT.adoc delete mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.adoc delete mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.adoc delete mode 100644 SECURITY.md create mode 100644 TEST-NEEDS.adoc delete mode 100644 TEST-NEEDS.md rename TOPOLOGY.md => TOPOLOGY.adoc (64%) rename docs/architecture/{TOPOLOGY.md => TOPOLOGY.adoc} (59%) create mode 100644 llm-warmup-dev.adoc delete mode 100644 llm-warmup-dev.md create mode 100644 llm-warmup-user.adoc delete mode 100644 llm-warmup-user.md diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..858f44f --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,71 @@ +== Contributing + +Thank you for your interest in contributing! We follow a "`Dual-Track`" +architecture where human-readable documentation lives in the root and +machine-readable policies live in `+.machine_readable/+`. + +=== How to Contribute + +We welcome contributions in many forms: + +* *Code:* Improving the core stack or extensions +* *Documentation:* Enhancing docs or AI manifests +* *Testing:* Adding property-based tests or formal proofs +* *Bug reports:* Filing clear, reproducible issues + +=== Getting Started + +[arabic] +. *Read the AI Manifest:* Start with `+0-AI-MANIFEST.a2ml+` (if present) +to understand the repository structure. +. *Environment:* Use `+nix develop+` or `+direnv allow+` to set up your +tools. +. *Task Runner:* Use `+just+` to see available commands +(`+just --list+`). + +=== Development Workflow + +==== Branch Naming + +.... +docs/short-description # Documentation +test/what-added # Test additions +feat/short-description # New features +fix/issue-number-description # Bug fixes +refactor/what-changed # Code improvements +security/what-fixed # Security fixes +.... + +==== Commit Messages + +We follow https://www.conventionalcommits.org/[Conventional Commits]: + +.... +(): + +[optional body] + +[optional footer] +.... + +Types: `+feat+`, `+fix+`, `+docs+`, `+test+`, `+refactor+`, `+ci+`, +`+chore+`, `+security+` + +=== Reporting Bugs + +Before reporting: 1. Search existing issues 2. Check if it’s already +fixed in `+main+` + +When reporting, include: - Clear, descriptive title - Environment +details (OS, versions, toolchain) - Steps to reproduce - Expected vs +actual behaviour + +=== Code of Conduct + +All contributors are expected to adhere to our +link:CODE_OF_CONDUCT.md[Code of Conduct]. + +=== License + +By contributing, you agree that your contributions will be licensed +under the same license as the project (see LICENSE). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 80ecdac..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,66 +0,0 @@ - -# Contributing - -Thank you for your interest in contributing! We follow a "Dual-Track" architecture where human-readable documentation lives in the root and machine-readable policies live in `.machine_readable/`. - -## How to Contribute - -We welcome contributions in many forms: - -- **Code:** Improving the core stack or extensions -- **Documentation:** Enhancing docs or AI manifests -- **Testing:** Adding property-based tests or formal proofs -- **Bug reports:** Filing clear, reproducible issues - -## Getting Started - -1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` (if present) to understand the repository structure. -2. **Environment:** Use `nix develop` or `direnv allow` to set up your tools. -3. **Task Runner:** Use `just` to see available commands (`just --list`). - -## Development Workflow - -### Branch Naming - -``` -docs/short-description # Documentation -test/what-added # Test additions -feat/short-description # New features -fix/issue-number-description # Bug fixes -refactor/what-changed # Code improvements -security/what-fixed # Security fixes -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): - -``` -(): - -[optional body] - -[optional footer] -``` - -Types: `feat`, `fix`, `docs`, `test`, `refactor`, `ci`, `chore`, `security` - -## Reporting Bugs - -Before reporting: -1. Search existing issues -2. Check if it's already fixed in `main` - -When reporting, include: -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour - -## Code of Conduct - -All contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). - -## License - -By contributing, you agree that your contributions will be licensed under the same license as the project (see [LICENSE](LICENSE)). diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..db806fc --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,25 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|0.1.x |✅ +|=== + +=== Reporting a Vulnerability + +Please report security vulnerabilities to: j.d.a.jewell@open.ac.uk + +Do NOT open a public issue for security vulnerabilities. + +=== Response Time + +We aim to respond within 48 hours and provide a fix within 7 days for +critical issues. + +=== Scope + +This policy covers the wokelangiser CLI tool and its generated +artifacts. diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index f0af861..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,22 +0,0 @@ - -# Security Policy - -## Supported Versions - -| Version | Supported | -|---------|-----------| -| 0.1.x | ✅ | - -## Reporting a Vulnerability - -Please report security vulnerabilities to: j.d.a.jewell@open.ac.uk - -Do NOT open a public issue for security vulnerabilities. - -## Response Time - -We aim to respond within 48 hours and provide a fix within 7 days for critical issues. - -## Scope - -This policy covers the wokelangiser CLI tool and its generated artifacts. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..086e3d3 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,37 @@ +== TEST-NEEDS.md — wokelangiser + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current Test State + +[width="100%",cols="42%,29%,29%",options="header",] +|=== +|Category |Count |Notes +|Integration tests (Rust) |2 |Dual compiled binaries (debug + release) + +|Verification tests |Unit-level |`+verification/tests/+` directory +present + +|FFI tests |Present |`+src/interface/ffi/test/+` +|=== + +=== What’s Covered + +* [x] Dual integration test builds +* [x] FFI verification layer +* [x] Cargo test harness + +=== Still Missing (for CRG B+) + +* [ ] Wokelang syntax parsing tests +* [ ] Language semantics tests +* [ ] Fuzzing for language edge cases +* [ ] Performance benchmarks +* [ ] Cross-platform compilation tests + +=== Run Tests + +[source,bash] +---- +cd /var/mnt/eclipse/repos/wokelangiser && cargo test +---- diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 3e3d684..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,32 +0,0 @@ - -# TEST-NEEDS.md — wokelangiser - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current Test State - -| Category | Count | Notes | -|----------|-------|-------| -| Integration tests (Rust) | 2 | Dual compiled binaries (debug + release) | -| Verification tests | Unit-level | `verification/tests/` directory present | -| FFI tests | Present | `src/interface/ffi/test/` | - -## What's Covered - -- [x] Dual integration test builds -- [x] FFI verification layer -- [x] Cargo test harness - -## Still Missing (for CRG B+) - -- [ ] Wokelang syntax parsing tests -- [ ] Language semantics tests -- [ ] Fuzzing for language edge cases -- [ ] Performance benchmarks -- [ ] Cross-platform compilation tests - -## Run Tests - -```bash -cd /var/mnt/eclipse/repos/wokelangiser && cargo test -``` diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 64% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 13b7ca8..6d5e06b 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,14 +1,19 @@ - - -# TOPOLOGY.md — wokelangiser +== TOPOLOGY.md — wokelangiser -## Purpose +=== Purpose -wokelangiser adds consent patterns, accessibility compliance (WCAG/ARIA), and internationalisation to existing code via WokeLang. Given a `wokelangiser.toml` manifest describing target modules and compliance requirements, it generates consent gate wrappers, accessibility audit reports, and i18n locale files. wokelangiser targets any codebase whose authors want to systematically address user rights, accessibility standards, and i18n readiness without manually threading these concerns through every module. +wokelangiser adds consent patterns, accessibility compliance +(WCAG/ARIA), and internationalisation to existing code via WokeLang. +Given a `+wokelangiser.toml+` manifest describing target modules and +compliance requirements, it generates consent gate wrappers, +accessibility audit reports, and i18n locale files. wokelangiser targets +any codebase whose authors want to systematically address user rights, +accessibility standards, and i18n readiness without manually threading +these concerns through every module. -## Module Map +=== Module Map -``` +.... wokelangiser/ ├── src/ │ ├── main.rs # CLI entry point (clap): init, validate, generate, build, run, info @@ -20,11 +25,11 @@ wokelangiser/ ├── verification/ # Proof harnesses ├── container/ # Stapeln container ecosystem └── .machine_readable/ # A2ML metadata -``` +.... -## Data Flow +=== Data Flow -``` +.... wokelangiser.toml manifest │ ┌────▼────┐ @@ -40,4 +45,4 @@ wokelangiser.toml manifest │ Codegen │ emit generated/wokelangiser/ (consent gates, WCAG/ARIA a11y report, │ │ i18n locale files) └─────────┘ -``` +.... diff --git a/docs/architecture/TOPOLOGY.md b/docs/architecture/TOPOLOGY.adoc similarity index 59% rename from docs/architecture/TOPOLOGY.md rename to docs/architecture/TOPOLOGY.adoc index 4bd744f..92aa8d3 100644 --- a/docs/architecture/TOPOLOGY.md +++ b/docs/architecture/TOPOLOGY.adoc @@ -1,17 +1,15 @@ - - +== Wokelangiser Topology -# Wokelangiser Topology +=== Overview -## Overview +Wokelangiser transforms existing code into consent-aware, accessible, +internationalised, and culturally sensitive software by injecting +WokeLang decorator patterns at the source level. It follows the standard +hyperpolymath -iser architecture. -Wokelangiser transforms existing code into consent-aware, accessible, internationalised, -and culturally sensitive software by injecting WokeLang decorator patterns at the source -level. It follows the standard hyperpolymath -iser architecture. +=== Data Flow -## Data Flow - -``` +.... wokelangiser.toml (manifest) | v @@ -74,11 +72,11 @@ wokelangiser.toml (manifest) v [Generated] src/interface/generated/abi/ C headers auto-generated from Zig exports -``` +.... -## Module Dependency Graph +=== Module Dependency Graph -``` +.... Wokelangiser.ABI.Types ^ ^ | | @@ -89,46 +87,65 @@ Wokelangiser.ABI.Layout Wokelangiser.ABI.Foreign | v wokelangiser (Rust CLI) -``` +.... + +=== Key Struct Layouts (FFI Boundary) + +[width="100%",cols="28%,7%,8%,57%",options="header",] +|=== +|Struct |Size |Align |Fields +|ConsentRecord |24B |8 |consent_type(u32), state(u32), timestamp(u64), +subject_id(u64) -## Key Struct Layouts (FFI Boundary) +|AccessibilityRecord |32B |8 |wcag_level(u32), focus_order(u32), +contrast_ratio(u32), _pad(u32), aria_label_ptr(u64), role_ptr(u64) -| Struct | Size | Align | Fields | -|-----------------------|------|-------|-------------------------------------------------| -| ConsentRecord | 24B | 8 | consent_type(u32), state(u32), timestamp(u64), subject_id(u64) | -| AccessibilityRecord | 32B | 8 | wcag_level(u32), focus_order(u32), contrast_ratio(u32), _pad(u32), aria_label_ptr(u64), role_ptr(u64) | -| I18nRecord | 24B | 8 | hook_type(u32), format_kind(u32), locale_tag_ptr(u64), source_ptr(u64) | +|I18nRecord |24B |8 |hook_type(u32), format_kind(u32), +locale_tag_ptr(u64), source_ptr(u64) +|=== -## Consent State Machine +=== Consent State Machine -``` +.... Pending --GrantConsent--> Granted --ActivateConsent--> Active --RevokeActive--> Revoked | ^ +----------RevokeGranted-----------------------------+ -``` +.... -All transitions are encoded as `ValidTransition` proofs in `Types.idr`. -Invalid transitions (e.g. Pending -> Active, Revoked -> anything) are -rejected at the type level. +All transitions are encoded as `+ValidTransition+` proofs in +`+Types.idr+`. Invalid transitions (e.g. Pending -> Active, Revoked -> +anything) are rejected at the type level. -## WCAG Contrast Thresholds +=== WCAG Contrast Thresholds -| Level | Minimum Ratio | Encoded Value | -|-------|---------------|---------------| -| A | none | 0 | -| AA | 4.5:1 | 450 | -| AAA | 7.0:1 | 700 | +[cols=",,",options="header",] +|=== +|Level |Minimum Ratio |Encoded Value +|A |none |0 +|AA |4.5:1 |450 +|AAA |7.0:1 |700 +|=== Contrast ratio calculated using WCAG 2.2 relative luminance algorithm -(sRGB linearisation + weighted sum) in `wokelangiser_contrast_ratio`. - -## Integration Points - -| System | Role | -|--------------|---------------------------------------------------| -| iseriser | Meta-framework that generated this scaffold | -| proven | Shared Idris2 verified library (consent proofs) | -| PanLL | Consent dashboard + accessibility audit panels | -| BoJ-server | Cartridge for automated accessibility scanning | -| VeriSimDB | Consent audit trail persistence | -| WokeLang | The specialist language wokelangiser bridges *other* code to (injects WokeLang's consent/accessibility patterns at the source level). Standalone repo: hyperpolymath/wokelang — you don't run wokelangiser on WokeLang itself | +(sRGB linearisation + weighted sum) in `+wokelangiser_contrast_ratio+`. + +=== Integration Points + +[width="100%",cols="22%,78%",options="header",] +|=== +|System |Role +|iseriser |Meta-framework that generated this scaffold + +|proven |Shared Idris2 verified library (consent proofs) + +|PanLL |Consent dashboard + accessibility audit panels + +|BoJ-server |Cartridge for automated accessibility scanning + +|VeriSimDB |Consent audit trail persistence + +|WokeLang |The specialist language wokelangiser bridges _other_ code to +(injects WokeLang’s consent/accessibility patterns at the source level). +Standalone repo: hyperpolymath/wokelang — you don’t run wokelangiser on +WokeLang itself +|=== diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..2ea4ee8 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — wokelangiser (Developer) + +=== What is wokelangiser? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md deleted file mode 100644 index 5fbb90f..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,17 +0,0 @@ - -# LLM Warmup — wokelangiser (Developer) - -## What is wokelangiser? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..ba3546f --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — wokelangiser (User) + +=== What is wokelangiser? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index 0ef5e0a..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,17 +0,0 @@ - -# LLM Warmup — wokelangiser (User) - -## What is wokelangiser? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture