docs/github-push-safety.md

NaturalCAD GitHub Push Safety Plan

Goal

Keep iteration fast while preventing secret leakage and noisy runtime artifacts from being pushed.

Branch strategy

• main stays deployable.
• Do work in short-lived branches: feat/*, fix/*, chore/*, sec/*.
• Open PRs for any change touching security/auth/secrets/runtime infra.

Required pre-push checks

Run before every push:

./scripts/prepush-check.sh

What it blocks:

• tracked .env files
• tracked runtime logs (artifacts/logs/*.jsonl)
• tracked virtualenv content
• staged diff lines that look like tokens/secrets

Secrets policy

• Never commit credentials to repo files.
• Keep runtime secrets in platform secret stores only:
  • Hugging Face Space secrets (NATURALCAD_API_KEY)
  • Modal secrets (OPENROUTER_API_KEY, NATURALCAD_API_KEY, Supabase keys)
• If a key is exposed, rotate immediately and force-push removal only after rotation.

Commit hygiene

• Keep commits scoped (one concern per commit).
• Avoid mixing docs + infra + security changes in one commit when possible.
• Use clear commit tags:
  • sec: for security hardening
  • infra: for deployment/runtime wiring
  • docs: for docs only

PR checklist

• No secrets or tokens in diff
• No .env or runtime logs tracked
• .gitignore still protects artifacts/logs
• Local smoke test completed (at least one prompt)
• If security-related, include threat + mitigation note in PR description

Release cadence

• Batch low-risk docs/UI changes.
• Ship security and infra fixes quickly in small PRs.
• Tag stable checkpoints for team testing (example: alpha-2026-04-18-1).