From 0b4cad44f1bb7bb296d09a612e4631c663ae776f Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 09:13:08 +0000 Subject: [PATCH] refactor(root): move root artefacts to their canonical locations Applies the estate root-shape rollout: files that are not root-level by necessity move to where their tooling and the estate canon expect them, and every reference to them is updated in the same change. * .machine_readable/root-allow.txt * build/guix.scm (from guix.scm) -> build/guix.scm * docs/testing-and-bench-strategy.adoc * .github/CONTRIBUTING.md (new) * CONTRIBUTING.adoc (deleted) * MAINTAINERS.adoc * README.adoc * docs/accessibility/README.adoc Verified with `git apply --check` against current main before committing; no behaviour change intended, the Justfile entry points keep working. --- .github/CONTRIBUTING.md | 35 ++++++++++++++++++++++++++++ .machine_readable/root-allow.txt | 1 + CONTRIBUTING.adoc | 26 --------------------- MAINTAINERS.adoc | 2 +- README.adoc | 4 ++-- docs/accessibility/README.adoc | 2 +- docs/testing-and-bench-strategy.adoc | 2 +- guix.scm | 28 ---------------------- 8 files changed, 41 insertions(+), 59 deletions(-) create mode 100644 .github/CONTRIBUTING.md delete mode 100644 CONTRIBUTING.adoc delete mode 100644 guix.scm diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 00000000..1ba330ac --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,35 @@ +# Contributing to ephapax + +This document explains how to contribute to the project. 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 +verified stack or extensions. \* **Documentation:** Enhancing AsciiDoc +manuals or AI manifests. \* **Testing:** Adding property-based tests or +formal proofs. + +## Getting Started + +1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` to + understand the repository structure. + +2. **Environment:** Use `guix` `develop` or `direnv` `allow` to set up + your tools (Idris2, Zig, Rust). + +3. **Task Runner:** Use `just` to see available commands (`just` + `--list`). + +## Contribution Policies + +For detailed rules on branch naming, commit messages, and the PR +process, please refer to the machine-readable metadata in +.machine_readable/. + +## Code of Conduct + +All contributors are expected to adhere to our ethical standards. See +CODE_OF_CONDUCT for details. diff --git a/.machine_readable/root-allow.txt b/.machine_readable/root-allow.txt index 25e49a48..efa51790 100644 --- a/.machine_readable/root-allow.txt +++ b/.machine_readable/root-allow.txt @@ -1,2 +1,3 @@ .hypatia-ignore CLAUDE.md +build/ # build orchestration: guix.scm relocated here (canon 1.2.1 guix-primary template_ref = "build/") diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc deleted file mode 100644 index 88496619..00000000 --- a/CONTRIBUTING.adoc +++ /dev/null @@ -1,26 +0,0 @@ -= Contributing to ephapax -:toc: preamble -:icons: font - -This document explains how to contribute to the project. 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 verified stack or extensions. -* **Documentation:** Enhancing AsciiDoc manuals or AI manifests. -* **Testing:** Adding property-based tests or formal proofs. - -== Getting Started - -1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` to understand the repository structure. -2. **Environment:** Use `guix develop` or `direnv allow` to set up your tools (Idris2, Zig, Rust). -3. **Task Runner:** Use `just` to see available commands (`just --list`). - -== Contribution Policies - -For detailed rules on branch naming, commit messages, and the PR process, please refer to the machine-readable metadata in link:.machine_readable/[.machine_readable/]. - -== Code of Conduct - -All contributors are expected to adhere to our ethical standards. See link:CODE_OF_CONDUCT.md[CODE_OF_CONDUCT.md] for details. diff --git a/MAINTAINERS.adoc b/MAINTAINERS.adoc index daf8a789..97edfcd1 100644 --- a/MAINTAINERS.adoc +++ b/MAINTAINERS.adoc @@ -62,4 +62,4 @@ For questions about project governance: * link:GOVERNANCE.adoc[Governance Model] * link:CODE_OF_CONDUCT.md[Code of Conduct] -* link:CONTRIBUTING.adoc[Contributing Guide] +* link:.github/CONTRIBUTING.md[Contributing Guide] diff --git a/README.adoc b/README.adoc index ceb07952..c81b1be0 100644 --- a/README.adoc +++ b/README.adoc @@ -707,7 +707,7 @@ generics, effects, traits, comptime, contracts) lives on | link:spec/[spec/] | Language specification + grammar EBNF. -| link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] +| link:.github/CONTRIBUTING.md[.github/CONTRIBUTING.md] | Contribution guide. | link:CODE_OF_CONDUCT.md[CODE_OF_CONDUCT.md] @@ -764,7 +764,7 @@ comparison against ten of these. Contributions welcome. Please see: -* link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] — getting started +* link:.github/CONTRIBUTING.md[.github/CONTRIBUTING.md] — getting started * link:CODE_OF_CONDUCT.md[CODE_OF_CONDUCT.md] — community standards The highest-leverage open work, in priority order: diff --git a/docs/accessibility/README.adoc b/docs/accessibility/README.adoc index 5bfe4761..149078fa 100644 --- a/docs/accessibility/README.adoc +++ b/docs/accessibility/README.adoc @@ -244,7 +244,7 @@ Burble is committed to: * Supporting screen readers and other assistive technologies * Continuous improvement based on user feedback -We welcome contributions to improve accessibility. See our link:../CONTRIBUTING.adoc[Contributing Guide] for details. +We welcome contributions to improve accessibility. See our link:../../.github/CONTRIBUTING.md[Contributing Guide] for details. == Related Documents diff --git a/docs/testing-and-bench-strategy.adoc b/docs/testing-and-bench-strategy.adoc index 9a40c8e7..dc5c1b7d 100644 --- a/docs/testing-and-bench-strategy.adoc +++ b/docs/testing-and-bench-strategy.adoc @@ -218,7 +218,7 @@ This layer keeps the four-layer-proof / dyadic-grammar / typed-wasm-seam machine *P2P.* contractile source → `contractile.just` byte-equality (catches generator/source drift); status-gate ↔ live `cargo test --list` + Coq admit grep ↔ `TEST-NEEDS.md`/`PROOF-NEEDS.md`; `pixi` tasks ↔ Justfile recipes (flag the lint asymmetry: pixi runs `clippy -D warnings`, Justfile has none); `reuse lint` ↔ LICENSES/ tree (would FAIL today: PMPL referenced but no `LICENSES/PMPL-*.txt`). -*E2E.* Clean-room repro (`pixi run build && pixi run test`; `guix shell -f guix.scm -- cargo build` — flag that `guix.scm` has `(source #f)` so it only provisions a shell, *not a reproducible build*); doc-truth `just status-gate` (exit 0 with counts matching docs; mutate a stray `Admitted` → red); governance PR E2E (drop SPDX header / add unpinned action / bump version without CHANGELOG → each gate fires); `validate-wasm` corpus floor. +*E2E.* Clean-room repro (`pixi run build && pixi run test`; `guix shell -f build/guix.scm -- cargo build` — flag that `guix.scm` has `(source #f)` so it only provisions a shell, *not a reproducible build*); doc-truth `just status-gate` (exit 0 with counts matching docs; mutate a stray `Admitted` → red); governance PR E2E (drop SPDX header / add unpinned action / bump version without CHANGELOG → each gate fires); `validate-wasm` corpus floor. *endpoint.* `reuse lint` exit code (SBOM-consumable attestation); scorecard MIN_SCORE=5 (*but the SARIF score-parse currently defaults to 0 via a `// 0` fallback — a false sense of coverage the test must expose*); status-gate markers exactly-one occurrence; Containerfile pinning contract; `boj-build` trigger payload (currently *malformed JSON*, unbalanced quotes/braces, `continue-on-error: true` swallows failures). diff --git a/guix.scm b/guix.scm deleted file mode 100644 index 5c7075c0..00000000 --- a/guix.scm +++ /dev/null @@ -1,28 +0,0 @@ -;; SPDX-License-Identifier: MPL-2.0 -;; Guix development environment. -;; Usage: guix shell -D -f guix.scm - -(use-modules (guix packages) - (guix build-system gnu) - (guix licenses) - (gnu packages base) - (gnu packages bash) - (gnu packages base) - (gnu packages java) - (gnu packages rust) - (gnu packages cmake) - (gnu packages zig) - (gnu packages golang) - (gnu packages node) - (gnu packages python)) - -(package - (name "ephapax") - (version "0.1.0") - (source #f) - (build-system gnu-build-system) - (inputs (list coreutils bash make openjdk rust cmake zig go node python)) - (synopsis "ephapax") - (description "ephapax — part of the hyperpolymath ecosystem.") - (home-page "https://github.com/hyperpolymath/ephapax") - (license ((@@ (guix licenses) license) "MPL-2.0" "https://github.com/hyperpolymath/palimpsest-license")))