From 32ef65ca67b3278f32433920e2ea2f115b17cb15 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:46:39 +0100 Subject: [PATCH] refactor: migrate repository documentation from Markdown to AsciiDoc --- ARCHITECTURE.adoc | 48 ++++++++++++ ARCHITECTURE.md | 47 ------------ CHANGELOG.adoc | 37 +++++++++ CHANGELOG.md | 36 --------- CONTRIBUTING.adoc | 75 ++++++++++++++++++ CONTRIBUTING.md | 72 ----------------- GOVERNANCE.adoc | 183 +++++++++----------------------------------- GOVERNANCE.md | 60 --------------- session/README.adoc | 45 +++++++++++ session/README.md | 46 ----------- 10 files changed, 243 insertions(+), 406 deletions(-) create mode 100644 ARCHITECTURE.adoc delete mode 100644 ARCHITECTURE.md create mode 100644 CHANGELOG.adoc delete mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.adoc delete mode 100644 CONTRIBUTING.md delete mode 100644 GOVERNANCE.md create mode 100644 session/README.adoc delete mode 100644 session/README.md diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 0000000..ba79c15 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,37 @@ +== Changelog + +All notable changes to this project will be documented in this file. + +The format is based on https://keepachangelog.com/en/1.1.0/[Keep a +Changelog], and this project adheres to +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Added + +* Instantiated this repository as *systemet — Equality Theory* +(`+system+` + `+ET+`), the stratified type theory the `+anytype+` kernel +implements. +* Authored `+README.adoc+` and `+EXPLAINME.adoc+` for the theory: the +five layers, the L1 equality-is-conversion cut, the three gates +(Totality/Structural/Polarity), roles-as-tropes, and TEA-erasure as an +open proof obligation. +* Instantiated identity descriptiles (CLADE/ECOSYSTEM/ANCHOR/STATE/META) +and the AFFIRMATION honesty snapshot with the systemet identity and an +honest status (theory specified; proofs OPEN; no compiler here). + +==== Changed + +* Split the theory out of the earlier combined "`EveryType`" draft. The +over-claiming "`EveryType`" name is retired; the kernel half now lives +in the `+anytype+` repo and this repo holds the theory. + +==== Notes + +* `+uuid+` is a PROVISIONAL deterministic UUIDv5 of the forge URL; +`+clade+` is PROVISIONAL. Both must be confirmed/registered in +`+gv-clade-index+`. +* `+CLAUDE.md+` is generated from the descriptiles — run +`+just claude-md+` to refresh it where `+nickel+`/`+just+` are +available. diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 364e199..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,36 +0,0 @@ - -# Changelog - -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - - - - -## [Unreleased] - -### Added -- Instantiated this repository as **systemet — Equality Theory** (`system` + `ET`), - the stratified type theory the `anytype` kernel implements. -- Authored `README.adoc` and `EXPLAINME.adoc` for the theory: the five layers, the - L1 equality-is-conversion cut, the three gates (Totality/Structural/Polarity), - roles-as-tropes, and TEA-erasure as an open proof obligation. -- Instantiated identity descriptiles (CLADE/ECOSYSTEM/ANCHOR/STATE/META) and the - AFFIRMATION honesty snapshot with the systemet identity and an honest status - (theory specified; proofs OPEN; no compiler here). - -### Changed -- Split the theory out of the earlier combined "EveryType" draft. The over-claiming - "EveryType" name is retired; the kernel half now lives in the `anytype` repo and - this repo holds the theory. - -### Notes -- `uuid` is a PROVISIONAL deterministic UUIDv5 of the forge URL; `clade` is - PROVISIONAL. Both must be confirmed/registered in `gv-clade-index`. -- `CLAUDE.md` is generated from the descriptiles — run `just claude-md` to refresh - it where `nickel`/`just` are available. diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..74de51d --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,75 @@ +== Contributing to systemet + +Thanks for your interest. This repository follows the Hyperpolymath +estate standards defined in +https://github.com/hyperpolymath/standards[hyperpolymath/standards]. + +=== Licence + +This project is licensed under *MPL-2.0*. By contributing you agree that +your contributions are licensed under the same terms. Every source file +carries an `+SPDX-License-Identifier+` header; keep it when editing, and +add one to any new file. + +=== Development environment + +A pinned dev shell is provided: + +[source,sh] +---- +nix develop # toolchain: just +---- + +Estate policy is Guix primary / Nix fallback; this repo currently ships +the Nix fallback. A `+guix.scm+` is welcome if you prefer the primary +tier. + +=== Build and test + +This repo uses https://just.systems[`+just+`] (the estate uses +Justfiles, never Makefiles). Recipes available here: + +[source,sh] +---- +just # list recipes +just fmt # format +just fmt-check # check formatting +just lint # lint +just test-all # run the full suite +just doctor # environment diagnostics +---- + +=== Machine-readable artefacts + +This repo carries `+.machine_readable/+` A2ML files (`+STATE.a2ml+`, +`+META.a2ml+`, `+ECOSYSTEM.a2ml+`, `+AGENTIC.a2ml+`, `+NEUROSYM.a2ml+`, +`+PLAYBOOK.a2ml+`). If your change alters project state, architecture, +or operational steps, update the corresponding file in the same PR — CI +validates them. + +=== Language policy + +The estate restricts which languages may be used. In particular Python, +Go, TypeScript, ReScript, V-lang, Java/Kotlin, Swift and Makefiles are +*not* accepted in new code; AffineScript, Rust/SPARK, Zig, Deno, Gleam, +Elixir, Haskell, Idris2, Agda, Julia and OCaml are. CI enforces this, so +check the policy in `+hyperpolymath/standards+` before introducing a new +language. + +=== Documentation format + +Docs are AsciiDoc (`+.adoc+`) by default, including `+README.adoc+`. The +GitHub-required community-health files stay Markdown: `+SECURITY.md+`, +`+CONTRIBUTING.md+`, `+CODE_OF_CONDUCT.md+`, `+CHANGELOG.md+`. Do not +add a `+.md+` duplicate of a doc that already exists as `+.adoc+`. + +=== Pull requests + +[arabic] +. Branch from `+main+` — do not push to `+main+` directly; branch +protection requires review and passing checks. +. Keep the change focused, and explain _why_ in the PR body. +. Make sure governance CI is green. It checks documentation presence, +packaging policy, secrets, licence consistency and workflow security. +. Security issues: follow `+SECURITY.md+` — report privately, never in a +public issue. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 149489f..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,72 +0,0 @@ - - - -# Contributing to systemet - -Thanks for your interest. This repository follows the Hyperpolymath estate -standards defined in [hyperpolymath/standards](https://github.com/hyperpolymath/standards). - -## Licence - -This project is licensed under **MPL-2.0**. By contributing you agree that -your contributions are licensed under the same terms. Every source file -carries an `SPDX-License-Identifier` header; keep it when editing, and add -one to any new file. - -## Development environment - -A pinned dev shell is provided: - -```sh -nix develop # toolchain: just -``` - -Estate policy is Guix primary / Nix fallback; this repo currently ships the -Nix fallback. A `guix.scm` is welcome if you prefer the primary tier. - -## Build and test - -This repo uses [`just`](https://just.systems) (the estate uses Justfiles, -never Makefiles). Recipes available here: - -```sh -just # list recipes -just fmt # format -just fmt-check # check formatting -just lint # lint -just test-all # run the full suite -just doctor # environment diagnostics -``` - -## Machine-readable artefacts - -This repo carries `.machine_readable/` A2ML files (`STATE.a2ml`, -`META.a2ml`, `ECOSYSTEM.a2ml`, `AGENTIC.a2ml`, `NEUROSYM.a2ml`, -`PLAYBOOK.a2ml`). If your change alters project state, architecture, or -operational steps, update the corresponding file in the same PR — CI -validates them. - -## Language policy - -The estate restricts which languages may be used. In particular Python, Go, -TypeScript, ReScript, V-lang, Java/Kotlin, Swift and Makefiles are **not** -accepted in new code; AffineScript, Rust/SPARK, Zig, Deno, Gleam, Elixir, -Haskell, Idris2, Agda, Julia and OCaml are. CI enforces this, so check the -policy in `hyperpolymath/standards` before introducing a new language. - -## Documentation format - -Docs are AsciiDoc (`.adoc`) by default, including `README.adoc`. The -GitHub-required community-health files stay Markdown: `SECURITY.md`, -`CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `CHANGELOG.md`. Do not add a `.md` -duplicate of a doc that already exists as `.adoc`. - -## Pull requests - -1. Branch from `main` — do not push to `main` directly; branch protection - requires review and passing checks. -2. Keep the change focused, and explain *why* in the PR body. -3. Make sure governance CI is green. It checks documentation presence, - packaging policy, secrets, licence consistency and workflow security. -4. Security issues: follow `SECURITY.md` — report privately, never in a - public issue. diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc index 2cef0a0..9b836fb 100644 --- a/GOVERNANCE.adoc +++ b/GOVERNANCE.adoc @@ -1,167 +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 **Benevolent Dictator (BDFL) Governance Model**: +=== Roles and Responsibilities -* A single champion (@hyperpolymath) holds the project's vision and final - decision authority, while actively welcoming contributions and delegating. -* *Current reality:* the project is presently staffed by a sole maintainer. - That is a staffing fact, not a closed door — contributions are welcome and - reviewed, and authority is delegable to anyone who demonstrably carries the - project's essence. "If someone can do it better, let them"; the model only - insists the essence always has a champion. -* 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/6a2/ - -| **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:.github/CODE_OF_CONDUCT.md[Code of Conduct] -* link:.github/CONTRIBUTING.md[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/session/README.adoc b/session/README.adoc new file mode 100644 index 0000000..d14a6d7 --- /dev/null +++ b/session/README.adoc @@ -0,0 +1,45 @@ +== Session Bindings (Thin Local Layer) + +This directory provides local integration for central session-management +standards. + +Authoritative protocols live in: + +* `+../standards/session-management-standards/+` (or +`+$SESSION_STANDARDS_DIR+`) + +This repo keeps only thin bindings: + +* `+dispatch.sh+` maps canonical commands to central protocol paths. +* `+custom-checks.k9+` defines repo-local policy checks. +* `+local-hooks.sh+` provides optional repo-specific hook behavior. + +=== Canonical Commands + +* `+intake repo +` +* `+checkpoint change +` +* `+verify maintenance +` +* `+verify substantial +` +* `+verify release +` +* `+close planned +` +* `+close urgent +` +* `+recover repo +` +* `+handover full +` +* `+handover split +` +* `+handover model +` +* `+handover human +` + +=== Justfile Aliases + +Run `+just session-help+` to list aliases, then use recipes such as: + +* `+just intake-repo path=.+` +* `+just checkpoint-change path=.+` +* `+just verify-maintenance path=.+` +* `+just close-planned path=.+` +* `+just handover-model path=.+` + +=== Runtime Artifacts + +Runtime files are generated per repository in `+.session/+` and are not +canonical standards text. diff --git a/session/README.md b/session/README.md deleted file mode 100644 index af5c8d0..0000000 --- a/session/README.md +++ /dev/null @@ -1,46 +0,0 @@ - -# Session Bindings (Thin Local Layer) - -This directory provides local integration for central session-management standards. - -Authoritative protocols live in: - -- `../standards/session-management-standards/` (or `$SESSION_STANDARDS_DIR`) - -This repo keeps only thin bindings: - -- `dispatch.sh` maps canonical commands to central protocol paths. -- `custom-checks.k9` defines repo-local policy checks. -- `local-hooks.sh` provides optional repo-specific hook behavior. - -## Canonical Commands - -- `intake repo ` -- `checkpoint change ` -- `verify maintenance ` -- `verify substantial ` -- `verify release ` -- `close planned ` -- `close urgent ` -- `recover repo ` -- `handover full ` -- `handover split ` -- `handover model ` -- `handover human ` - -## Justfile Aliases - -Run `just session-help` to list aliases, then use recipes such as: - -- `just intake-repo path=.` -- `just checkpoint-change path=.` -- `just verify-maintenance path=.` -- `just close-planned path=.` -- `just handover-model path=.` - -## Runtime Artifacts - -Runtime files are generated per repository in `.session/` and are not canonical standards text.