timmy-home/CONTRIBUTING.md

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.