refactor(root): move root artefacts to their canonical locations

.github/CONTRIBUTING.md

@@ -0,0 +1,108 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <6759885+hyperpolymath@users.noreply.github.com>
+-->
+
+# Contributing — filesoup
+
+## Audience
+
+Developers working **on** `filesoup`. For consumers (people calling or
+depending on it) see <a href="./usage.adoc" class="adoc">usage</a>.
+
+## Local-dev setup
+
+Prerequisites — the minimum versions and where to get them:
+
+- `<tool` `1>` v\`\<version\>\` — `<install` `instruction>`.
+
+- `<tool` `2>` v\`\<version\>\` — `<install` `instruction>`.
+
+- 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/<topic>` (for AI agents) or
+    `<initials>/<topic>` (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` `<num>` `--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-<slug>.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`.

.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 }}"

.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:

.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/")

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:

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]

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"