# Contributing to YPMS

Hard rules — mirrored from OWC's `CONTRIBUTING.md` because the two systems share a stack, an ownership model, and an ISSO. If a rule feels wrong for YPMS, propose an amendment in a PR to this file, don't quietly break it.

## Repository conventions

1. **Migrations are immutable once merged.** Add a new Alembic revision, never edit `0001_baseline.py` or its successors. If a schema change requires undoing an older migration, the fix is a new revision, not a rewrite. Every migration is a paper trail an auditor can walk.

2. **Don't add domain logic to `src/ypms/framework/` or `src/ypms/security/`.** Those are reused by every entity; entity-specific code belongs in `src/ypms/<entity>/`. If a framework enhancement is genuinely needed, propose it in its own PR with a written reason.

3. **Every state-mutating route emits an audit row.** Enforced by `CRUDService` and the router factory once the framework lands. Don't write handlers that bypass either.

4. **501 stubs still fire RBAC + audit.** Deferred actions must route through `require_permission` and emit an audit event. Permission gaps surface at Phase 0 review, not at feature-completion.

5. **Tests required.** `src/ypms/framework/` and `src/ypms/security/` need ≥ 80% coverage. Everything else: at least one happy-path test.

6. **No `--no-verify`, `# noqa`, or `# type: ignore` without an inline comment naming the specific reason.** If you need to silence a check, say why in the code.

7. **Sensitive fields never in logs.** SSN, banking, tokens, passwords, encryption keys — route through `sanitize_for_log` before emitting or don't emit. See `src/ypms/logging.py`.

8. **No commits attributed to a person who didn't write them.** Set `user.name` and `user.email` in `git config` to yourself before committing. Co-author trailers are welcome and encouraged for pairing.

## Change control

- Every substantive change ties to a POA&M ID, a phase-plan milestone, or an issue. Include the reference in the PR description.
- `PHASE{N}_PLAN.md` is authoritative for the current phase's scope. Older plans lose to the current one on conflict.
- Cross-phase work needs a written scope-conflict note before it lands.

## Security review

- Any change touching auth, RBAC, encryption, or audit gets a second reviewer.
- Changes to `src/ypms/security/` require the ISSO's approval (currently Chris Tonjes).
- Additions to the RBAC seed require the same review as code changes — permissions are policy in this codebase.

## PR checklist

- [ ] Tests pass locally (`pytest`).
- [ ] Coverage doesn't drop below 80% on `framework/` or `security/`.
- [ ] `ruff check`, `mypy` clean.
- [ ] SAST (`bandit`) and SCA (`pip-audit`) clean, or documented waivers.
- [ ] Migration added (if schema changed); no edits to older migrations.
- [ ] Any new endpoint has RBAC + audit + a test.
- [ ] Any new sensitive field routes through the app-layer encryption helpers.
- [ ] `docs/nist-mapping.md` updated if the change wires a new NIST control.
- [ ] POA&M item updated if the change closes or advances one.
- [ ] Commit message names the phase milestone or POA&M ID it advances.

## Merging

- Squash-merge is the default. Merge commit messages should read like release notes for that PR.
- Force-pushes to `main` are not allowed. Force-pushes to feature branches during review are fine.
- CI must be green.