Skip to content

Process gap: contract-changing PRs need an explicit review gate #2959

@franksong2702

Description

@franksong2702

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions