flowCreate.solutions

SDLC Governance (Backend Standard)

This document defines the minimum SDLC governance bar for Flow Create Solutions backend repositories.

Goal: make change delivery predictable for humans and non-ambiguous for AI agents (so they don’t invent process).

Branching strategy (default)

Standard: trunk-based development.

  • Protected default branch: main
  • No direct pushes to main
  • Work happens on short-lived branches (e.g., feature/<topic>, fix/<topic>)
  • All changes land via Pull Request (PR)

Pull Request (PR) expectations

Every PR must include:

  • Scope: what changed (high level) and why
  • User impact: what users/operators will notice (or “none”)
  • Risk: what could break; blast radius
  • Verification: what was run/checked (tests, manual steps, etc.)
  • Docs: link to any docs updated (or explain why none were needed)

PR size rule

Rule: prefer small PRs that can be reviewed in <30 minutes.

  • Split refactors from behavior changes when feasible.
  • Avoid “drive-by” changes unrelated to the PR objective.

Code review standards

Reviewer requirements

Minimum: at least 1 approval for merge.

Solo maintainer rule: self-approval is allowed. The purpose is to enforce the review checklist and Definition of Done consistently, even when the reviewer and author are the same person.

Escalate review (require explicit approval from a tech lead/owner, when the project has multiple maintainers) when a change:

  • touches authentication/authorization
  • changes tenant isolation boundaries
  • modifies rate limiting
  • affects data access patterns in ways that could leak data or degrade performance
  • changes migration behavior (and follow the migration ownership policy)

Review checklist (what reviewers should look for)

  • Correctness: behavior matches intent and edge cases are handled
  • Security: validation, authz, tenant boundaries, safe defaults
  • Testing: new behavior is covered by tests; tests are not brittle
  • Consistency: follows module structure and conventions
  • Observability: failures are logged appropriately (without leaking secrets)
  • Docs: project docs updated if running/operating/debugging changed

CI gates (required checks)

Rule: PRs must not be merged unless required checks pass.

Minimum required checks for backend repos:

  • Format: black
  • Lint: flake8
  • Type-check: mypy
  • Tests: pytest

Baseline security automation for Python backends:

  • Dependabot: dependency update PRs (SCA workflow)
  • pip-audit: CI dependency vulnerability check (SCA)
  • bandit: CI “SAST-lite” static analysis for common Python issues
  • gitleaks: CI secrets scanning

Current policy: recommended until teams have them wired into CI reliably; then promote to required. See: Security → Security Automation (docs/backend/01_security/security_automation.md).

When CI is allowed to be “yellow”

Not allowed for required checks. If a check is required, it must be green.

If you need an exception (e.g., a flaky test), you must:

  • create an issue/task to fix it
  • document the temporary exception in the project repo (not here)
  • timebox the exception

Definition of Done (DoD)

A change is “done” when:

  • Code follows standards and module structure
  • Security posture is preserved (validation/authz/tenant isolation/rate limiting)
  • Tests are added/updated for new behavior
  • Docs are updated if behavior or operations changed
  • CI is green on required checks

Release strategy (generic)

These standards do not mandate deployment tooling, but do mandate clarity:

  • Each project must document how changes move from main → development/staging → production.
  • Each project must document rollback procedure at the repo level.

Guidance for AI agents

Agents must:

  • follow the repo’s AGENTS.md
  • keep PRs scoped and avoid unrelated changes
  • not bypass required checks or “hand-wave” verification
  • escalate ambiguous process decisions to the project lead

Required PR template (repo-level)

Rule: every repo must include a lightweight PR template to keep PRs consistent and enforce the checklist (even for solo work).

Canonical location: .github/pull_request_template.md

Template (copy/paste)

## Summary
- What changed and why?

## Risk
- What could break? Blast radius?

## Verification
- [ ] black / formatter
- [ ] flake8 / linter
- [ ] mypy / type-check
- [ ] pytest
- [ ] Manual smoke test (if applicable): <steps>

## Security
- [ ] Auth/authz/tenant isolation unchanged or intentionally updated
- [ ] No secrets/logging leaks introduced

## Docs
- [ ] Docs updated (or not needed): <link/reason>