YPMS/CONTRIBUTING.md

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. Every revision's SHA-256 is pinned in migrations/IMMUTABLE.sha256 — add a line with each new migration; a test fails if a pinned file changes. Migrations never import app code.

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, the router factory, and the stub router. Don't write handlers that bypass them.

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, # type: ignore, # nosec, or gitleaks:allow without an inline comment naming the specific reason. Suppressions are per-finding, never blanket. Don't lower a CI gate to get green.

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.

9. Reads of sensitive PII emit pii_read. Any GET, list, or history route returning SSN-bearing, banking, FERPA, CFSA, or immigration data calls framework.pii_audit after RBAC passes (NIST AU-14).

10. Encrypted columns go through security.column_crypto and into __audit_redact__. Otherwise their ciphertext lands in audit_log and version_history. Sensitive values are write-only on the model and masked in the read schema.

11. Every mapped table declares a retention policy. The app refuses to start otherwise. Don't invent durations — use a retention_classes.py class, or an unset one citing the POA&M item that owns the decision.

12. New model modules go in src/ypms/models.py. Alembic, the retention job, and the tests all read that one list.

13. Changes to vendored OWC code need a written reason in the module docstring and get added to the "Upstream to OWC" list in the current phase status doc.

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), SCA (pip-audit --strict .), and secret scan (gitleaks) clean, or per-finding waivers with reasons.
• Migration added (if schema changed) and pinned in migrations/IMMUTABLE.sha256; no edits to older migrations.
• New tables have a retention policy; new model modules are in src/ypms/models.py.
• Any new endpoint has RBAC + audit + a test; PII reads emit pii_read.
• 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 (Gitea Actions, .gitea/workflows/ci.yml) must be green.