From 269fdec7705d3e6552af884ab944f17694193a5b Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 14:37:46 +0000 Subject: [PATCH 1/2] fix(docs): repair the contributing guide content defects Mechanical repairs to the guide, each anchored on a known-broken form: - unescaped \# -> # - rebuilt the hard-wrapped setup block into one command per line - replaced invalid `():` commit header - dedented headings that rendered as code No prose is rewritten; only the broken forms are corrected. --- .github/CONTRIBUTING.md | 79 +++++++++++++++++++++-------------------- 1 file changed, 41 insertions(+), 38 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index e5b2963a..cfee44de 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,49 +1,49 @@ # Clone the repository -git clone cd -proven-servers +git clone https://github.com/hyperpolymath/proven-servers.git +cd proven-servers -# Using Nix (recommended for reproducibility) +# Using Guix (recommended for reproducibility) -nix develop +guix develop # Or using toolbox/distrobox -toolbox create proven-servers-dev toolbox enter proven-servers-dev \# -Install dependencies manually +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 +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 ├── +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 +SECURITY.md ├── flake.nix # Nix flake — fallback (Perimeter 1) ├── +guix.scm # Guix package — primary (Perimeter 1) └── Justfile # Task runner (Perimeter 1) --- - ## How to Contribute +## How to Contribute - ### Reporting Bugs +### Reporting Bugs **Before reporting**: 1. Search existing issues @@ -60,7 +60,7 @@ runner (Perimeter 1) - Expected vs actual behaviour - Logs, screenshots, or minimal reproduction - ### Suggesting Features +### Suggesting Features **Before suggesting**: 1. Check the [roadmap](ROADMAP.md) if available @@ -76,7 +76,7 @@ runner (Perimeter 1) - Alternatives considered - Which perimeter this affects - ### Your First Contribution +### Your First Contribution Look for issues labelled: @@ -87,22 +87,25 @@ runner (Perimeter 1) --- - ## Development Workflow +## Development Workflow - ### Branch Naming +### 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) +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 +### Commit Messages We follow [Conventional Commits](https://www.conventionalcommits.org/): -(): +type(scope): description + +Body: what changed and why. +Footer: issue reference, e.g. Closes #123 \[optional body\] \[optional footer\] From 32a24e05e1c0102147b993e942d1f9d9302b111a Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 14:41:46 +0000 Subject: [PATCH 2/2] fix(docs): rebuild the mangled repository-structure tree MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The tree block was hard-wrapped by the AsciiDoc->Markdown conversion, so it rendered as a paragraph rather than a tree, and it still listed CONTRIBUTING.md at the repository root, where the guide no longer lives. Rebuilt from the tree's own content: depth recovered from the `|` continuation bars that survived the wrap, the guide entry moved under `.github/`, `#` escapes unescaped, the last entry of each group restored to `└──`, and the block fenced so it renders as a tree. Every annotation ("Perimeter 1-2") is preserved - nothing is invented and nothing is dropped. --- .github/CONTRIBUTING.md | 51 ++++++++++++++++++++++++++--------------- 1 file changed, 33 insertions(+), 18 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index cfee44de..25a53f84 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -20,24 +20,39 @@ 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) - +```text +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) +│ ├── CONTRIBUTING.md # This file +│ ├── ISSUE_TEMPLATE/ +│ └── workflows/ +├── CHANGELOG.md +├── CODE_OF_CONDUCT.md +├── 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) +``` ---