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.

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

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