the pipeline · commits

Commit discipline

Every commit follows the Conventional Commits format. This is not a stylistic preference — it makes the changelog automatic, the intent traceable, and the reviewer's job possible without a conversation.

# Conventional commit format
type(scope): short description — STORY-05

# Types:
feat       — new behaviour the user or system can perform
fix        — corrects a defect
refactor   — restructures code without changing behaviour
test       — adds or updates tests only
chore      — tooling, config, dependencies
docs       — documentation only

# Examples:
feat(exam-grading): add idempotency guard on double submit — STORY-05
fix(grade-sync): handle null EMS response on first publish — STORY-12
test(exam-grading): add concurrent-submit edge case — STORY-05

The story reference in every commit is what makes the trace possible. When a bug surfaces in production, you find every commit that touched the relevant story. When the changelog generates, it groups by type and scope automatically.

The pipeline — a chain of catches

This is where meaning is verified automatically. The pipeline is not a deployment mechanism. It is a systematic check that the code implements the understanding correctly at every level. A failing stage tells you which level of the chain has a gap — and that information is more valuable than just knowing the build broke.

Stage 0          Stage 1          Stage 2          Stage 3
Pre-commit  →    Lint & Types  →  Unit Tests   →   Contract
Format, lint,     Domain language,  Scenario-level    Epic boundary
secrets scan      type errors       gaps              gaps

   →    Stage 4    →    Stage 5    →    Stage 6
        Visual           Security         Staging
        Design drift     SAST, deps,      Full-stack
                         integrity        integration

Stage 0 runs before the commit leaves the developer's machine — formatting, linting, and a secrets scan that catches API keys, passwords, and tokens before they enter the repository. Stage 5 is the security gate: static analysis for known vulnerability patterns, dependency audit against published CVEs, and integrity checks that confirm no build artifact was tampered with.

Next — Migration discipline →