From d3cef1417a9a26b6e1db4cd29ca7e51a712012b0 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 09:35:14 +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. * .envrc * .machine_readable/contractiles/Justfile * Justfile * QUICKSTART-MAINTAINER.adoc * RSR_OUTLINE.adoc * build/guix.scm (from guix.scm) -> build/guix.scm * .github/CONTRIBUTING.md (new) * CONTRIBUTING.adoc (deleted) * docs/accessibility/README.adoc Verified with `git apply --check` against current main before committing; no behaviour change intended, the Justfile entry points keep working. --- .envrc | 4 +- .github/CONTRIBUTING.md | 108 ++++++++++++++++++++++ .machine_readable/contractiles/Justfile | 4 +- CONTRIBUTING.adoc | 114 ------------------------ Justfile | 4 +- QUICKSTART-MAINTAINER.adoc | 2 +- RSR_OUTLINE.adoc | 2 +- docs/accessibility/README.adoc | 2 +- guix.scm | 71 --------------- 9 files changed, 117 insertions(+), 194 deletions(-) create mode 100644 .github/CONTRIBUTING.md delete mode 100644 CONTRIBUTING.adoc delete mode 100644 guix.scm diff --git a/.envrc b/.envrc index 80897d0f..ee790501 100644 --- a/.envrc +++ b/.envrc @@ -7,8 +7,8 @@ if has asdf; then use asdf fi -# Load Guix shell if guix.scm exists -if has guix && [ -f guix.scm ]; then +# Load Guix shell if build/guix.scm exists +if has guix && [ -f build/guix.scm ]; then use guix fi diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 00000000..e5b2963a --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,108 @@ +# Clone the repository + +git clone cd +proven-servers + +# Using Nix (recommended for reproducibility) + +nix develop + +# Or using toolbox/distrobox + +toolbox create proven-servers-dev toolbox enter proven-servers-dev \# +Install dependencies manually + +# Verify setup + +just check \# or: cargo check / mix compile / etc. just test \# Run test +suite + + + ### Repository Structure + +proven-servers/ ├── 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) ├── .machine_readable/ \# ALL +machine-readable content (Perimeter 1) │ ├── \*.a2ml \# State files +(STATE, META, ECOSYSTEM, etc.) │ ├── bot_directives/ \# Bot configs │ +└── contractiles/ \# Policy contracts (k9, dust, lust, must, trust) ├── +.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.nix \# Nix flake — fallback (Perimeter 1) ├── +guix.scm \# Guix package — primary (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/proven-servers/labels/good%20first%20issue) — Simple Perimeter 3 tasks + - [`help wanted`](https://github.com/hyperpolymath/proven-servers/labels/help%20wanted) — Community help needed + - [`documentation`](https://github.com/hyperpolymath/proven-servers/labels/documentation) — Docs improvements + - [`perimeter-3`](https://github.com/hyperpolymath/proven-servers/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/.machine_readable/contractiles/Justfile b/.machine_readable/contractiles/Justfile index f3aeafa5..b9a407c8 100644 --- a/.machine_readable/contractiles/Justfile +++ b/.machine_readable/contractiles/Justfile @@ -785,11 +785,11 @@ state-phase: # Enter Guix development shell (primary) guix-shell: - guix shell -D -f guix.scm + guix shell -D -f build/guix.scm # Build with Guix guix-build: - guix build -f guix.scm + guix build -f build/guix.scm # Enter Nix development shell (fallback) nix-shell: diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc deleted file mode 100644 index b297eee3..00000000 --- a/CONTRIBUTING.adoc +++ /dev/null @@ -1,114 +0,0 @@ -== Clone the repository - -git clone https://github.com/hyperpolymath/proven-servers.git cd -proven-servers - -== Using Nix (recommended for reproducibility) - -nix develop - -== Or using toolbox/distrobox - -toolbox create proven-servers-dev toolbox enter proven-servers-dev # -Install dependencies manually - -== Verify setup - -just check # or: cargo check / mix compile / etc. just test # Run test -suite - -.... - -### Repository Structure -.... - -proven-servers/ ├── 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) ├── .machine_readable/ # ALL -machine-readable content (Perimeter 1) │ ├── *.a2ml # State files -(STATE, META, ECOSYSTEM, etc.) │ ├── bot_directives/ # Bot configs │ └── -contractiles/ # Policy contracts (k9, dust, lust, must, trust) ├── -.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.nix # Nix flake — fallback (Perimeter 1) ├── -guix.scm # Guix package — primary (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/proven-servers/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/proven-servers/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/proven-servers/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/proven-servers/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/Justfile b/Justfile index f3aeafa5..b9a407c8 100644 --- a/Justfile +++ b/Justfile @@ -785,11 +785,11 @@ state-phase: # Enter Guix development shell (primary) guix-shell: - guix shell -D -f guix.scm + guix shell -D -f build/guix.scm # Build with Guix guix-build: - guix build -f guix.scm + guix build -f build/guix.scm # Enter Nix development shell (fallback) nix-shell: diff --git a/QUICKSTART-MAINTAINER.adoc b/QUICKSTART-MAINTAINER.adoc index df17f341..27627862 100644 --- a/QUICKSTART-MAINTAINER.adoc +++ b/QUICKSTART-MAINTAINER.adoc @@ -32,7 +32,7 @@ Output: `{{BUILD_OUTPUT_PATH}}` [source,bash] ---- -guix build -f guix.scm +guix build -f build/guix.scm ---- === Nix diff --git a/RSR_OUTLINE.adoc b/RSR_OUTLINE.adoc index 79b316ce..24fdffbf 100644 --- a/RSR_OUTLINE.adoc +++ b/RSR_OUTLINE.adoc @@ -37,7 +37,7 @@ git init just init # Enter development environment -guix shell -D -f guix.scm +guix shell -D -f build/guix.scm # Validate compliance just validate-rsr diff --git a/docs/accessibility/README.adoc b/docs/accessibility/README.adoc index de588344..5ce46337 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/guix.scm b/guix.scm deleted file mode 100644 index 48495423..00000000 --- a/guix.scm +++ /dev/null @@ -1,71 +0,0 @@ -;; SPDX-License-Identifier: MPL-2.0 -;; Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -;; -;; Guix package definition for proven-servers -;; -;; Usage: -;; guix shell -D -f guix.scm # Enter development shell -;; guix build -f guix.scm # Build package -;; -;; TODO: Replace proven-servers and customize inputs for your language/stack. -;; See: https://guix.gnu.org/manual/en/html_node/Defining-Packages.html - -(use-modules (guix packages) - (guix gexp) - (guix git-download) - (guix build-system gnu) - (guix licenses) - (gnu packages base)) - -(package - (name "proven-servers") - (version "0.1.0") - (source (local-file "." "source" - #:recursive? #t - #:select? (lambda (file stat) - (not (string-contains file ".git"))))) - (build-system gnu-build-system) - (arguments - '(#:phases - (modify-phases %standard-phases - ;; TODO: Customize build phases for your project - ;; Examples for common stacks: - ;; - ;; Rust: - ;; (replace 'build (lambda _ (invoke "cargo" "build" "--release"))) - ;; (replace 'check (lambda _ (invoke "cargo" "test"))) - ;; - ;; Elixir: - ;; (replace 'build (lambda _ (invoke "mix" "compile"))) - ;; (replace 'check (lambda _ (invoke "mix" "test"))) - ;; - ;; Zig: - ;; (replace 'build (lambda _ (invoke "zig" "build"))) - ;; (replace 'check (lambda _ (invoke "zig" "build" "test"))) - (delete 'configure) - (delete 'build) - (delete 'check) - (replace 'install - (lambda* (#:key outputs #:allow-other-keys) - (let ((out (assoc-ref outputs "out"))) - (mkdir-p (string-append out "/share/doc")) - (copy-file "README.adoc" - (string-append out "/share/doc/README.adoc")))))))) - (native-inputs - (list - ;; TODO: Add build-time dependencies - ;; Examples: - ;; rust (gnu packages rust) - ;; elixir (gnu packages elixir) - ;; zig (gnu packages zig) - )) - (inputs - (list - ;; TODO: Add runtime dependencies - )) - (home-page "https://github.com/hyperpolymath/proven-servers") - (synopsis "Formally verified server components with dependent-type proofs") - (description "RSR-compliant project. See README.adoc for details.") - (license (list - ;; MPL-2.0 extends MPL-2.0 - mpl2.0)))