Problem
Hermes WebUI has contributor-facing contracts in docs/CONTRACTS.md, subsystem RFCs, and UI/UX guidance, but the current process still lets a PR change product-contract semantics by editing tests or renderer behavior without explicitly declaring it as a contract change.
That creates a failure mode where CI turns green while the product direction silently shifts.
Expected behavior
For any PR that changes a public contract, contract-indexed docs, or tests that encode product semantics:
- the PR body should include a
Contract Routing section naming the touched contract family;
- if the PR intentionally changes an existing contract, the PR body should include a
Contract Change section;
- the corresponding docs and tests should move together, instead of tests silently redefining behavior;
- release batches should call out contract-affecting PRs instead of treating them as ordinary low-risk code churn.
Why this matters
Contracts are meant to stop contributors and agents from accidentally changing product direction while fixing a local symptom. If the contract only lives as advisory prose, a later PR can update tests in the opposite direction and make the new behavior look correct because CI passes.
Proposed scope
Add contributor guidance and a lightweight static regression test that pins the process rule:
CONTRIBUTING.md explains contract-affecting PRs and release-batch callouts.
docs/CONTRACTS.md explains the Contract Routing / Contract Change expectations and says contract tests must not be inverted without matching docs.
- A focused test asserts the public docs contain the required review-gate terms.
- Changelog records the contributor-process guardrail.
Non-goals
- No GitHub Actions policy engine in this issue.
- No new PR template requirement in this issue.
- No retroactive relabeling of old PRs.
Problem
Hermes WebUI has contributor-facing contracts in
docs/CONTRACTS.md, subsystem RFCs, and UI/UX guidance, but the current process still lets a PR change product-contract semantics by editing tests or renderer behavior without explicitly declaring it as a contract change.That creates a failure mode where CI turns green while the product direction silently shifts.
Expected behavior
For any PR that changes a public contract, contract-indexed docs, or tests that encode product semantics:
Contract Routingsection naming the touched contract family;Contract Changesection;Why this matters
Contracts are meant to stop contributors and agents from accidentally changing product direction while fixing a local symptom. If the contract only lives as advisory prose, a later PR can update tests in the opposite direction and make the new behavior look correct because CI passes.
Proposed scope
Add contributor guidance and a lightweight static regression test that pins the process rule:
CONTRIBUTING.mdexplains contract-affecting PRs and release-batch callouts.docs/CONTRACTS.mdexplains theContract Routing/Contract Changeexpectations and says contract tests must not be inverted without matching docs.Non-goals