From d616123f79a55293fa9765ee92d88b77fffaad6c Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:34:30 +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.md => SECURITY.adoc | 21 ++++++----- TEST-NEEDS.adoc | 36 ++++++++++++++++++ TEST-NEEDS.md | 30 --------------- TOPOLOGY.md => TOPOLOGY.adoc | 73 ++++++++++++++++++++---------------- llm-warmup-dev.adoc | 19 ++++++++++ llm-warmup-dev.md | 16 -------- llm-warmup-user.adoc | 19 ++++++++++ llm-warmup-user.md | 16 -------- 12 files changed, 222 insertions(+), 196 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 rename SECURITY.md => SECURITY.adoc (58%) create mode 100644 TEST-NEEDS.adoc delete mode 100644 TEST-NEEDS.md rename TOPOLOGY.md => TOPOLOGY.adoc (76%) 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.md b/SECURITY.adoc similarity index 58% rename from SECURITY.md rename to SECURITY.adoc index 9e3d7cc..b414911 100644 --- a/SECURITY.md +++ b/SECURITY.adoc @@ -1,21 +1,24 @@ -# Security Policy +== Security Policy -## Supported Versions +=== Supported Versions -| Version | Supported | -|---------|-----------| -| 0.1.x | ✅ | +[cols=",",options="header",] +|=== +|Version |Supported +|0.1.x |✅ +|=== -## Reporting a Vulnerability +=== 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 +=== Response Time -We aim to respond within 48 hours and provide a fix within 7 days for critical issues. +We aim to respond within 48 hours and provide a fix within 7 days for +critical issues. -## Scope +=== Scope This policy covers the phronesiser CLI tool and its generated artifacts. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..fb0cfd9 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,36 @@ +== TEST-NEEDS.md — phronesiser + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current Test State + +[width="100%",cols="42%,29%,29%",options="header",] +|=== +|Category |Count |Notes +|Integration tests (Rust) |1 |`+tests/integration_test.rs+` + +|Verification tests |Unit-level |`+verification/tests/+` directory +present + +|FFI tests |Present |`+src/interface/ffi/test/+` +|=== + +=== What’s Covered + +* [x] Integration test framework +* [x] FFI verification layer +* [x] Aspect-based test organization + +=== Still Missing (for CRG B+) + +* [ ] Property-based testing +* [ ] Fuzzing targets +* [ ] Performance benchmarks +* [ ] Multi-backend test matrix + +=== Run Tests + +[source,bash] +---- +cd /var/mnt/eclipse/repos/phronesiser && cargo test +---- diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 509d41c..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,30 +0,0 @@ -# TEST-NEEDS.md — phronesiser - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current Test State - -| Category | Count | Notes | -|----------|-------|-------| -| Integration tests (Rust) | 1 | `tests/integration_test.rs` | -| Verification tests | Unit-level | `verification/tests/` directory present | -| FFI tests | Present | `src/interface/ffi/test/` | - -## What's Covered - -- [x] Integration test framework -- [x] FFI verification layer -- [x] Aspect-based test organization - -## Still Missing (for CRG B+) - -- [ ] Property-based testing -- [ ] Fuzzing targets -- [ ] Performance benchmarks -- [ ] Multi-backend test matrix - -## Run Tests - -```bash -cd /var/mnt/eclipse/repos/phronesiser && cargo test -``` diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 76% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index aff14db..c8a3c6d 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,16 +1,15 @@ - - -# TOPOLOGY.md — Phronesiser +== TOPOLOGY.md — Phronesiser -## Purpose +=== Purpose -Phronesiser adds provably safe ethical constraints to AI agent decision-making -via Phronesis deontic logic. It compiles agent behaviour specifications into -formally verified constraint sets enforced at runtime with full audit trails. +Phronesiser adds provably safe ethical constraints to AI agent +decision-making via Phronesis deontic logic. It compiles agent behaviour +specifications into formally verified constraint sets enforced at +runtime with full audit trails. -## Module Map +=== Module Map -``` +.... phronesiser/ ├── src/ │ ├── main.rs # CLI entry point (clap subcommands) @@ -63,11 +62,11 @@ phronesiser/ ├── Justfile # Task runner ├── Containerfile # OCI build (Chainguard base) └── LICENSE # MPL-2.0 -``` +.... -## Data Flow +=== Data Flow -``` +.... phronesiser.toml User defines constraints (deontic rules, value hierarchies, │ harm prevention boundaries) ▼ @@ -88,27 +87,37 @@ phronesiser.toml User defines constraints (deontic rules, value hierarc ▼ Audit Trail Structured logs: permitted/denied/escalated with formal justification -``` +.... -## Key Types (Idris2 ABI) +=== Key Types (Idris2 ABI) -| Type | Purpose | -|------|---------| -| `DeonticModality` | Obligation, Permission, Prohibition | -| `EthicalConstraint` | Named constraint with modality, scope, and formal proposition | -| `ValueAlignment` | Partially ordered value hierarchy | -| `HarmPrevention` | Severity-classified harm boundary | -| `AuditDecision` | Decidable proof: Permitted, Denied, or Escalated | -| `ConstraintSet` | Composable collection of ethical constraints | +[width="100%",cols="40%,60%",options="header",] +|=== +|Type |Purpose +|`+DeonticModality+` |Obligation, Permission, Prohibition -## Integration Points +|`+EthicalConstraint+` |Named constraint with modality, scope, and +formal proposition -| System | Relationship | -|--------|-------------| -| **iseriser** | Meta-framework; generates -iser scaffolding | -| **proven** | Shared Idris2 verified library | -| **typell** | Type theory engine | -| **PanLL** | Constraint visualisation panels | -| **BoJ-server** | Constraint management cartridge | -| **VeriSimDB** | Audit trail backing store | -| **Hypatia** | Neurosymbolic CI/CD scanning | +|`+ValueAlignment+` |Partially ordered value hierarchy + +|`+HarmPrevention+` |Severity-classified harm boundary + +|`+AuditDecision+` |Decidable proof: Permitted, Denied, or Escalated + +|`+ConstraintSet+` |Composable collection of ethical constraints +|=== + +=== Integration Points + +[cols=",",options="header",] +|=== +|System |Relationship +|*iseriser* |Meta-framework; generates -iser scaffolding +|*proven* |Shared Idris2 verified library +|*typell* |Type theory engine +|*PanLL* |Constraint visualisation panels +|*BoJ-server* |Constraint management cartridge +|*VeriSimDB* |Audit trail backing store +|*Hypatia* |Neurosymbolic CI/CD scanning +|=== diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..687b1a2 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — phronesiser (Developer) + +=== What is phronesiser? + +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 afa2b26..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — phronesiser (Developer) - -## What is phronesiser? -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..14487e6 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — phronesiser (User) + +=== What is phronesiser? + +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 4024196..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — phronesiser (User) - -## What is phronesiser? -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