From 0d42ce57498697df2f8725c9cbf7619512be1c4a Mon Sep 17 00:00:00 2001
From: arena-agent <arena-agent@users.noreply.github.com>
Date: Sun, 20 Sep 2026 02:05:00 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20root=20CONTRIBUTING.adoc=20=E2=80=94=20?=
 =?UTF-8?q?satisfy=20the=20estate=20docs=20gate?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The estate docs gate (hyperpolymath/standards scripts/check-docs-presence.sh,
run by the Governance reusable) requires CONTRIBUTING at the repository root
(CONTRIBUTING.md | CONTRIBUTING.adoc | 3-practice/CONTRIBUTING.adoc); its
grace cutoff 2026-08-21 has armed, so Governance's docs step fails without it.

Adds a root CONTRIBUTING.adoc following the estate norm (AsciiDoc by
default; 32 of 40 sampled estate repos already carry one). Content covers
setup, branch naming, and Conventional Commits per estate conventions.
---
 CONTRIBUTING.adoc | 58 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 CONTRIBUTING.adoc

diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc
new file mode 100644
index 0000000..6af10e1
--- /dev/null
+++ b/CONTRIBUTING.adoc
@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: CC-BY-SA-4.0
+// SPDX-FileCopyrightText: Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+= Contributing — AcceleratorGate.jl
+:toc: left
+
+Contributions to `AcceleratorGate.jl` follow the Hyperpolymath estate conventions:
+AsciiDoc for documentation, Conventional Commits, and real (not mocked)
+integration tests where the estate policy applies.
+
+== Local-dev setup
+
+This repository ships a `Justfile`; `just` lists the available recipes.
+
+[source,bash]
+----
+git clone git@github.com:hyperpolymath/AcceleratorGate.jl.git
+cd AcceleratorGate.jl
+just            # lists the available recipes
+----
+
+== Reporting bugs and suggesting features
+
+* Search existing issues first; check whether `main` already fixes the problem.
+* Use the issue templates where present; include environment details,
+  steps to reproduce, and expected vs actual behaviour.
+
+== Branch naming
+
+[source,text]
+----
+docs/short-description       # Documentation
+test/what-added              # Test additions
+feat/short-description       # New features
+fix/issue-number-description # Bug fixes
+refactor/what-changed        # Code improvements
+security/what-fixed          # Security fixes
+----
+
+== Commit messages
+
+We follow https://www.conventionalcommits.org/[Conventional Commits]:
+
+[source,text]
+----
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+----
+
+== Cross-references
+
+This root document exists because the estate docs gate
+(`hyperpolymath/standards` `scripts/check-docs-presence.sh`) requires
+`CONTRIBUTING.md`, `CONTRIBUTING.adoc`, or `3-practice/CONTRIBUTING.adoc`
+at the repository root. Estate documentation policy: AsciiDoc by default —
+see `hyperpolymath/standards`.