From 87f5f4234c3d68a06b7049b5b0410db2ef5e7d65 Mon Sep 17 00:00:00 2001
From: Alexander Whitestone <alexpaynex@gmail.com>
Date: Sat, 28 Mar 2026 10:02:27 -0400
Subject: [PATCH] docs: codify merge proof standard

---
 CONTRIBUTING.md                 | 57 +++++++++++++++++++++++++++++++++
 README.md                       |  9 ++++++
 tests/test_proof_policy_docs.py | 17 ++++++++++
 3 files changed, 83 insertions(+)
 create mode 100644 CONTRIBUTING.md
 create mode 100644 tests/test_proof_policy_docs.py

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..1572c459
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,57 @@
+# Contributing to timmy-config
+
+## Proof Standard
+
+This is a hard rule.
+
+- visual changes require screenshot proof
+- do not commit screenshots or binary media to Gitea backup unless explicitly required
+- CLI/verifiable changes must cite the exact command output, log path, or world-state proof showing acceptance criteria were met
+- config-only changes are not fully accepted when the real acceptance bar is live runtime behavior
+- no proof, no merge
+
+## How to satisfy the rule
+
+### Visual changes
+Examples:
+- skin updates
+- terminal UI layout changes
+- browser-facing output
+- dashboard/panel changes
+
+Required proof:
+- attach screenshot proof to the PR or issue discussion
+- keep the screenshot outside the repo unless explicitly asked to commit it
+- name what the screenshot proves
+
+### CLI / harness / operational changes
+Examples:
+- scripts
+- config wiring
+- heartbeat behavior
+- model routing
+- export pipelines
+
+Required proof:
+- cite the exact command used
+- paste the relevant output, or
+- cite the exact log path / world-state artifact that proves the change
+
+Good:
+- `python3 -m pytest tests/test_x.py -q` → `2 passed`
+- `~/.timmy/timmy-config/logs/huey.log`
+- `~/.hermes/model_health.json`
+
+Bad:
+- "looks right"
+- "compiled"
+- "should work now"
+
+## Default merge gate
+
+Every PR should make it obvious:
+1. what changed
+2. what acceptance criteria were targeted
+3. what evidence proves those criteria were met
+
+If that evidence is missing, the PR is not done.
diff --git a/README.md b/README.md
index 4e3205a9..415bfe30 100644
--- a/README.md
+++ b/README.md
@@ -54,6 +54,15 @@ pip install huey
 huey_consumer.py tasks.huey -w 2 -k thread
 ```
 
+## Proof Standard
+
+This repo uses a hard proof rule for merges.
+
+- visual changes require screenshot proof
+- CLI/verifiable changes must cite logs, command output, or world-state proof
+- screenshots/media stay out of Gitea backup unless explicitly required
+- see `CONTRIBUTING.md` for the merge gate
+
 ## Deploy
 
 ```bash
diff --git a/tests/test_proof_policy_docs.py b/tests/test_proof_policy_docs.py
new file mode 100644
index 00000000..2839d84d
--- /dev/null
+++ b/tests/test_proof_policy_docs.py
@@ -0,0 +1,17 @@
+from pathlib import Path
+
+
+def test_contributing_sets_hard_proof_rule() -> None:
+    doc = Path("CONTRIBUTING.md").read_text()
+
+    assert "visual changes require screenshot proof" in doc
+    assert "do not commit screenshots or binary media to Gitea backup" in doc
+    assert "CLI/verifiable changes must cite the exact command output, log path, or world-state proof" in doc
+    assert "no proof, no merge" in doc
+
+
+def test_readme_points_to_proof_standard() -> None:
+    readme = Path("README.md").read_text()
+
+    assert "Proof Standard" in readme
+    assert "CONTRIBUTING.md" in readme