From 812c576a7b0fa718e4c43efe57707b6b8ad252a9 Mon Sep 17 00:00:00 2001
From: Timmy Time <timmy@Alexanderwhitestone.ai>
Date: Sat, 28 Mar 2026 14:03:39 +0000
Subject: [PATCH] docs: codify merge proof standard (#32)

---
 CONTRIBUTING.md                 | 55 +++++++++++++++++++++++++++++++++
 OPERATIONS.md                   |  6 ++++
 tests/test_proof_policy_docs.py | 17 ++++++++++
 3 files changed, 78 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 0000000..a53f405
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,55 @@
+# Contributing to timmy-home
+
+## Proof Standard
+
+This is a hard rule.
+
+- visual changes require screenshot proof
+- keep screenshots and binary media out of Gitea backup unless explicitly required
+- CLI/verifiable changes must reference the exact command output, log path, or observable state that proves acceptance criteria were met
+- compile-only validation is not enough when stronger runtime or world-state proof is available
+- no proof, no merge
+
+## How to satisfy the rule
+
+### Visual changes
+Examples:
+- browser UI
+- dashboards
+- render/layout changes
+- skins or visible presentation changes landed through this workspace
+
+Required proof:
+- provide screenshot proof
+- store screenshots outside the repo by default
+- explain what the screenshot proves
+
+### CLI / docs / scripts / harness-adjacent changes
+Examples:
+- scripts under `scripts/`
+- training/export utilities
+- report generators
+- operational documentation that claims a system behavior is true
+
+Required proof:
+- cite the exact command used, and its output, or
+- cite the exact log path, artifact path, or observable world-state proving the claim
+
+Good:
+- `python3 -m pytest tests/test_x.py -q` → `2 passed`
+- `/Users/apayne/.timmy/reports/...`
+- `/Users/apayne/.timmy/heartbeat/...`
+
+Bad:
+- "looks correct"
+- "compiled fine"
+- "should be working"
+
+## Merge gate
+
+A PR is only ready when the reader can answer:
+1. what changed
+2. what acceptance criteria were targeted
+3. what proof demonstrates those criteria were met
+
+If the proof is absent, the work is not ready to merge.
diff --git a/OPERATIONS.md b/OPERATIONS.md
index 99b3be6..96c2999 100644
--- a/OPERATIONS.md
+++ b/OPERATIONS.md
@@ -41,3 +41,9 @@ ps aux | grep -E "claude-loop|gemini-loop|timmy-orchestrator" | grep -v grep
 - Health Monitor: every 5m, haiku (not opus!)
 - DPO export / training support jobs: explicit model, explicit task, no hidden defaults
 - All crons MUST specify model explicitly. Never inherit default.
+
+## Proof Standard
+- visual changes require screenshot proof
+- keep screenshots and binary media out of Gitea backup unless explicitly required
+- CLI/verifiable changes must reference the exact command output, log path, or observable state proving the claim
+- see `CONTRIBUTING.md` for the merge gate
diff --git a/tests/test_proof_policy_docs.py b/tests/test_proof_policy_docs.py
new file mode 100644
index 0000000..9c09cb8
--- /dev/null
+++ b/tests/test_proof_policy_docs.py
@@ -0,0 +1,17 @@
+from pathlib import Path
+
+
+def test_contributing_sets_workspace_proof_rule() -> None:
+    doc = Path("CONTRIBUTING.md").read_text()
+
+    assert "visual changes require screenshot proof" in doc
+    assert "keep screenshots and binary media out of Gitea backup" in doc
+    assert "CLI/verifiable changes must reference the exact command output, log path, or observable state" in doc
+    assert "no proof, no merge" in doc
+
+
+def test_operations_mentions_proof_standard() -> None:
+    ops = Path("OPERATIONS.md").read_text()
+
+    assert "Proof Standard" in ops
+    assert "CONTRIBUTING.md" in ops