From a483a1f405299005a785519fe0b7c0cb58f285e6 Mon Sep 17 00:00:00 2001
From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com>
Date: Thu, 1 Oct 2026 06:59:56 +0100
Subject: [PATCH 1/2] docs: add Signed commits section to CONTRIBUTING

Owner ruling D218. See docs/SIGNING-POLICY.adoc in hyperpolymath/standards.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WRvDivYwLSeVCJUrfjic3f
---
 .github/CONTRIBUTING.md | 17 +++++++++++++++++
 CONTRIBUTING.adoc       | 17 +++++++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index fa3b587..fd50e17 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -69,3 +69,20 @@ GitHub-required community-health files stay Markdown: `SECURITY.md`,
 
 4.  Security issues: follow `SECURITY.md` — report privately, never in a
     public issue.
+
+## Signed commits
+
+Every commit that reaches the default branch must be signed; a ruleset refuses
+unsigned pushes. Estate policy:
+[SIGNING-POLICY](https://github.com/hyperpolymath/standards/blob/main/docs/SIGNING-POLICY.adoc).
+
+- **People and interactive agents** sign with an SSH key registered on GitHub
+  as a *signing* key (`gpg.format=ssh`, `user.signingkey=<key>.pub`,
+  `commit.gpgsign=true`). The committer email must be verified on that account.
+- **Apps, bots and workflows** never `git push` local commits. They write
+  through the API (`createCommitOnBranch` or the estate `signed-push` action)
+  so that GitHub signs each commit.
+- Merge PRs with **squash**. The ruleset checks every commit on the PR branch,
+  not just the result, so one unsigned commit blocks the merge. Re-create such a
+  branch with signed commits (`git cherry-pick -S`) and open a new PR.
+  Rebase-merge replays commits unsigned and is disabled.
diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc
index 2880ff9..17f2a25 100644
--- a/CONTRIBUTING.adoc
+++ b/CONTRIBUTING.adoc
@@ -56,3 +56,20 @@ This root document exists because the estate docs gate
 `CONTRIBUTING.md`, `CONTRIBUTING.adoc`, or `3-practice/CONTRIBUTING.adoc`
 at the repository root. Estate documentation policy: AsciiDoc by default —
 see `hyperpolymath/standards`.
+
+== Signed commits
+
+Every commit that reaches the default branch must be signed; a ruleset refuses
+unsigned pushes. Estate policy:
+https://github.com/hyperpolymath/standards/blob/main/docs/SIGNING-POLICY.adoc[SIGNING-POLICY].
+
+* **People and interactive agents** sign with an SSH key registered on GitHub
+  as a *signing* key (`gpg.format=ssh`, `user.signingkey=<key>.pub`,
+  `commit.gpgsign=true`). The committer email must be verified on that account.
+* **Apps, bots and workflows** never `git push` local commits. They write
+  through the API (`createCommitOnBranch` or the estate `signed-push` action)
+  so that GitHub signs each commit.
+* Merge PRs with **squash**. The ruleset checks every commit on the PR branch,
+  not just the result, so one unsigned commit blocks the merge. Re-create such a
+  branch with signed commits (`git cherry-pick -S`) and open a new PR.
+  Rebase-merge replays commits unsigned and is disabled.

From e9a71f56db6cbb1101f77c3b101d4d6c447bedf4 Mon Sep 17 00:00:00 2001
From: "coderabbitai[bot]"
 <136622811+coderabbitai[bot]@users.noreply.github.com>
Date: Thu, 1 Oct 2026 14:19:59 +0000
Subject: [PATCH 2/2] docs(contributing): recommend updating existing PR
 branches with signed commits

---
 .github/CONTRIBUTING.md | 5 +++--
 CONTRIBUTING.adoc       | 5 +++--
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index fd50e17..b5e1e0e 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -83,6 +83,7 @@ unsigned pushes. Estate policy:
   through the API (`createCommitOnBranch` or the estate `signed-push` action)
   so that GitHub signs each commit.
 - Merge PRs with **squash**. The ruleset checks every commit on the PR branch,
-  not just the result, so one unsigned commit blocks the merge. Re-create such a
-  branch with signed commits (`git cherry-pick -S`) and open a new PR.
+  not just the result, so one unsigned commit blocks the merge. Re-create the
+  branch with signed commits (`git cherry-pick -S`) and update the existing PR
+  branch. Open a new PR only if repository controls prevent updating that branch.
   Rebase-merge replays commits unsigned and is disabled.
diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc
index 17f2a25..2b4034e 100644
--- a/CONTRIBUTING.adoc
+++ b/CONTRIBUTING.adoc
@@ -70,6 +70,7 @@ https://github.com/hyperpolymath/standards/blob/main/docs/SIGNING-POLICY.adoc[SI
   through the API (`createCommitOnBranch` or the estate `signed-push` action)
   so that GitHub signs each commit.
 * Merge PRs with **squash**. The ruleset checks every commit on the PR branch,
-  not just the result, so one unsigned commit blocks the merge. Re-create such a
-  branch with signed commits (`git cherry-pick -S`) and open a new PR.
+  not just the result, so one unsigned commit blocks the merge. Re-create the
+  branch with signed commits (`git cherry-pick -S`) and update the existing PR
+  branch. Open a new PR only if repository controls prevent updating that branch.
   Rebase-merge replays commits unsigned and is disabled.