From bca8bf035068f2e7482c8673179ba2661391a73b Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 09:15: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. * .github/hooks/validate-a2ml.sh (from .githooks/validate-a2ml.sh) -> .github/hooks/validate-a2ml.sh * .github/hooks/validate-k9.sh (from .githooks/validate-k9.sh) -> .github/hooks/validate-k9.sh * .github/workflows/dogfood-gate.yml * .machine_readable/contractiles/Justfile * .machine_readable/root-allow.txt * Justfile * build/guix.scm (from guix.scm) -> build/guix.scm * .github/CONTRIBUTING.md (new) * CONTRIBUTING.adoc (deleted) * RSR_COMPLIANCE.adoc * scripts/verify-rsr.sh Verified with `git apply --check` against current main before committing; no behaviour change intended, the Justfile entry points keep working. --- .github/CONTRIBUTING.md | 108 ++++++++++++++++++ {.githooks => .github/hooks}/validate-a2ml.sh | 0 {.githooks => .github/hooks}/validate-k9.sh | 0 .github/workflows/dogfood-gate.yml | 4 +- .machine_readable/contractiles/Justfile | 4 +- .machine_readable/root-allow.txt | 1 + CONTRIBUTING.adoc | 108 ------------------ Justfile | 4 +- RSR_COMPLIANCE.adoc | 2 +- guix.scm | 28 ----- scripts/verify-rsr.sh | 4 +- 11 files changed, 118 insertions(+), 145 deletions(-) create mode 100644 .github/CONTRIBUTING.md rename {.githooks => .github/hooks}/validate-a2ml.sh (100%) rename {.githooks => .github/hooks}/validate-k9.sh (100%) 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 0000000..38532e3 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,108 @@ + + +# Contributing — filesoup + +## Audience + +Developers working **on** `filesoup`. For consumers (people calling or +depending on it) see usage. + +## Local-dev setup + +Prerequisites — the minimum versions and where to get them: + +- `` v\`\\` — ``. + +- `` v\`\\` — ``. + +- GPG signing key configured (estate policy — all commits must be + signed). See + [standards/docs/secure-coding-training.md](https://github.com/hyperpolymath/standards/blob/main/docs/secure-coding-training.md). + +One-shot setup: + +``` bash +git clone git@github.com:hyperpolymath/filesoup.git +cd filesoup +just setup # installs deps, sets up hooks +just test # runs the full test suite +``` + +## Running tests + +- **Unit**: `just` `test-unit` — fast, no I/O. + +- **Integration**: `just` `test-int` — uses real services (database, + HTTP, etc.). Estate policy: prefer real over mocked (see + `feedback_integration_tests_real_db` in maintainer’s memory). + +- **Property**: `just` `test-prop` — randomised, slower; budget + documented in `docs/proof-debt.md` if applicable. + +- **Full**: `just` `test` — runs all of the above. + +## Code style + +We enforce style via CI (governance-reusable.yml from +hyperpolymath/standards). Locally: + +``` bash +just fmt # auto-format +just lint # static checks +``` + +- All commits must be **GPG-signed** (CI enforces; see + [standards](https://github.com/hyperpolymath/standards)). + +- All source files must carry an **SPDX-License-Identifier** header (CI + enforces). + +- Conventional commits — `feat`, `fix`, `chore`, `refactor`, `docs`, + `test`, `ci`, `revert` (CHANGELOG is auto-generated from these via + [`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml)). + +## Branching & PR workflow + +1. Branch off `main` as `claude/` (for AI agents) or + `/` (for humans). + +2. Make focused, narrow commits — one logical change per commit. + +3. Open a PR against `main`. + +4. **Enable auto-merge immediately** on every PR you open (`gh` `pr` + `merge` `` `--auto` `--squash`) — estate standing policy (see + standards#196 audit and policies). + +5. CI must be green. The PR auto-merges when checks pass + reviews + land. + +## Adding a new dependency + +1. State the **why** in the PR body — what does this dependency unlock? + +2. Check provenance (maintained, audited, no malicious history). + +3. Pin to a SHA, not a tag. + +4. Update `docs/architecture.adoc#Dependencies`. + +## Adding an ADR + +When you make a non-obvious design decision, write it down: + +1. Copy `docs/decisions/0001-template.adoc` → `0002-.adoc`. + +2. Fill in: Context, Decision, Consequences, Alternatives. + +3. Link the ADR from the README or relevant code as a comment. + +## Reporting issues + +- Bugs in `filesoup`: file at `hyperpolymath/filesoup/issues`. + +- Estate-wide concerns (policy, conventions, CI): file at + `hyperpolymath/standards/issues`. diff --git a/.githooks/validate-a2ml.sh b/.github/hooks/validate-a2ml.sh similarity index 100% rename from .githooks/validate-a2ml.sh rename to .github/hooks/validate-a2ml.sh diff --git a/.githooks/validate-k9.sh b/.github/hooks/validate-k9.sh similarity index 100% rename from .githooks/validate-k9.sh rename to .github/hooks/validate-k9.sh diff --git a/.github/workflows/dogfood-gate.yml b/.github/workflows/dogfood-gate.yml index c29d6d5..f26da48 100644 --- a/.github/workflows/dogfood-gate.yml +++ b/.github/workflows/dogfood-gate.yml @@ -40,7 +40,7 @@ jobs: - name: Validate A2ML manifests if: steps.detect.outputs.count > 0 - run: bash .githooks/validate-a2ml.sh + run: bash .github/hooks/validate-a2ml.sh - name: Write summary run: | A2ML_COUNT="${{ steps.detect.outputs.count }}" @@ -85,7 +85,7 @@ jobs: - name: Validate K9 contracts if: steps.detect.outputs.k9_count > 0 - run: bash .githooks/validate-k9.sh + run: bash .github/hooks/validate-k9.sh - name: Write summary run: | K9_COUNT="${{ steps.detect.outputs.k9_count }}" diff --git a/.machine_readable/contractiles/Justfile b/.machine_readable/contractiles/Justfile index 0c2598a..57bd596 100644 --- a/.machine_readable/contractiles/Justfile +++ b/.machine_readable/contractiles/Justfile @@ -369,11 +369,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 Guix development shell (fallback) guix-shell: diff --git a/.machine_readable/root-allow.txt b/.machine_readable/root-allow.txt index ceb2b98..3b3fccb 100644 --- a/.machine_readable/root-allow.txt +++ b/.machine_readable/root-allow.txt @@ -1 +1,2 @@ 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 3fe8661..0000000 --- a/CONTRIBUTING.adoc +++ /dev/null @@ -1,108 +0,0 @@ -== Clone the repository - -git clone https://github.com/hyperpolymath/filesoup.git cd filesoup - -== Using Guix (recommended for reproducibility) - -guix develop - -== Or using toolbox/distrobox - -toolbox create filesoup-dev toolbox enter filesoup-dev # Install -dependencies manually - -== Verify setup - -just check # or: cargo check / mix compile / etc. just test # Run test -suite - -.... - -### Repository Structure -.... - -filesoup/ ├── 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) ├── .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.guix # Guix flake (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/filesoup/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/filesoup/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/filesoup/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/filesoup/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 0c2598a..57bd596 100644 --- a/Justfile +++ b/Justfile @@ -369,11 +369,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 Guix development shell (fallback) guix-shell: diff --git a/RSR_COMPLIANCE.adoc b/RSR_COMPLIANCE.adoc index c762c25..b5809b4 100644 --- a/RSR_COMPLIANCE.adoc +++ b/RSR_COMPLIANCE.adoc @@ -69,5 +69,5 @@ None - fully compliant == References * link:https://github.com/hyperpolymath/RSR-template-repo[RSR Template Repository] -* link:../CONTRIBUTING.adoc[Contributing Guidelines] +* link:.github/CONTRIBUTING.md[Contributing Guidelines] * link:../CODE_OF_CONDUCT.adoc[Code of Conduct] diff --git a/guix.scm b/guix.scm deleted file mode 100644 index bcb0020..0000000 --- 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 "filesoup") - (version "0.1.0") - (source #f) - (build-system gnu-build-system) - (inputs (list coreutils bash make openjdk rust cmake zig go node python)) - (synopsis "filesoup") - (description "filesoup — part of the hyperpolymath ecosystem.") - (home-page "https://github.com/hyperpolymath/filesoup") - (license ((@@ (guix licenses) license) "MPL-2.0" "https://github.com/hyperpolymath/palimpsest-license"))) diff --git a/scripts/verify-rsr.sh b/scripts/verify-rsr.sh index 5b5f618..1d8b17c 100755 --- a/scripts/verify-rsr.sh +++ b/scripts/verify-rsr.sh @@ -72,7 +72,7 @@ echo "📚 RSR Category 4: Documentation" check "README.adoc exists" "[ -f README.adoc ]" check "LICENSE files exist (triple licensed)" "[ -f LICENSE-MIT ] && [ -f LICENSE-APACHE ] && [ -f LICENSE ]" check "CHANGELOG.adoc exists" "[ -f CHANGELOG.adoc ]" -check "CONTRIBUTING.adoc exists" "[ -f CONTRIBUTING.adoc ]" +check "../.github/CONTRIBUTING.md exists" "[ -f ../.github/CONTRIBUTING.md ]" check "CODE_OF_CONDUCT.adoc exists" "[ -f CODE_OF_CONDUCT.adoc ]" check "SECURITY.adoc exists" "[ -f SECURITY.adoc ]" check "MAINTAINERS.adoc exists" "[ -f MAINTAINERS.adoc ]" @@ -105,7 +105,7 @@ echo "" echo "🤝 RSR Category 8: TPCF (Tri-Perimeter Contribution Framework)" check "TPCF documented" "[ -f docs/TPCF.adoc ]" check "Perimeter 3 (Community Sandbox) open" "grep -q 'Community Sandbox' docs/TPCF.adoc" -check "Contribution guidelines clear" "grep -q 'TPCF\|perimeter' CONTRIBUTING.adoc || grep -q 'contribution' CONTRIBUTING.adoc" +check "Contribution guidelines clear" "grep -q 'TPCF\|perimeter' ../.github/CONTRIBUTING.md || grep -q 'contribution' ../.github/CONTRIBUTING.md" echo "" echo "🔍 RSR Category 9: Code Quality"