# Contributing Sign-Off Guide

## Scope
This guide defines contribution workflow, review expectations, and merge gates for this repository.

## How To Use This File
1. Use this file when preparing any pull request.
2. `Must` items are merge requirements.
3. `Should` items are expected unless exceptions are documented.
4. `Could` items are optional quality upgrades.

## Must (Merge Gate)

### Workflow
- [ ] Create a feature branch from main.
- [ ] Keep the change scoped to one concern per PR.
- [ ] Use clear commit messages that explain intent.
- [ ] Rebase or merge latest main before review.

### Code And Behavior
- [ ] Escape dynamic PHP output with `htmlspecialchars(..., ENT_QUOTES)`.
- [ ] Keep route keys alphanumeric with underscore or dash.
- [ ] Ensure route updates include both router allow-list and navigation wiring.
- [ ] Verify changed flows work in full load and AJAX mode.

### Review Evidence
- [ ] Browser back/forward behavior verified for changed routes.
- [ ] Sidebar state, breadcrumb label, and page title stay consistent.
- [ ] No obvious browser console errors on changed flows.
- [ ] Documentation updates included when behavior or process changes.

### Required Cross-Checks
- [ ] Security checks from [SECURITY.md](SECURITY.md) completed.
- [ ] Testing checks from [docs/TESTING_RULES.md](docs/TESTING_RULES.md) completed.

## Should (Expected)
- [ ] Prefer reusable CSS classes over repeated inline styles.
- [ ] Keep reusable JS in `assets/app.js` rather than page-level inline scripts.
- [ ] Keep PRs small enough for same-day review.
- [ ] Include screenshots or concise test notes for UI changes.

## Could (Optional Improvements)
- [ ] Add lightweight automated checks for changed routes.
- [ ] Add follow-up tickets for deferred cleanup work.
- [ ] Include short architecture notes for non-trivial design decisions.

## Sign-Off Record
- [ ] Must items complete.
- [ ] Any Should exceptions documented and approved.
- [ ] Open risks captured in PR notes.
- [ ] Reviewer confirms change is ready to merge.