Git Commit — Conventional Commits for SDD

Format

<type>[optional scope]: <description>

[optional body]

[optional footer]

References: Conventional Commits and How to Write a Git Commit Message.

Commit Types

Mapping to SDD Artifacts

Breaking Changes

# ! marker after type/scope
feat!: remove deprecated endpoint

# Or BREAKING CHANGE footer
feat(api): allow extensible configuration

BREAKING CHANGE: behavior of the `extends` key changed

Workflow

1. Analyze Diff

# If there are staged files, use staged diff
git diff --staged --stat
git diff --staged

# If nothing is staged, use working tree
git diff --stat
git diff

# Check overall status
git status --porcelain

Determine from the diff:

• Type: What kind of change is this? (see table above)
• Scope: Which module/area was affected? (e.g., auth, api, docs, spec)
• Description: One-line summary of what changed

2. Group and Stage (if needed)

If the diff contains logically distinct changes, group them into separate commits:

# Group by logical area
git add src/auth/*.ts          # commit 1: feat(auth)
git add tests/auth/*.test.ts   # commit 2: test(auth)
git add docs/features/login/   # commit 3: docs(login)

Principle: one commit = one coherent logical change.

If all changes are part of the same logical unit, stage everything:

git add -A

3. Pre-Commit Checks

Before committing, verify:

# Does .gitignore exist?
test -f .gitignore && echo "OK" || echo "⚠ .gitignore missing"

# No secrets being committed?
git diff --staged --name-only | grep -iE '\.(env|pem|key|credentials|secret)' && echo "⚠ POSSIBLE SECRET" || echo "OK"

Never commit: .env, private keys, tokens, credentials, credentials.json.

3b. Integration Branch Guard

Before committing, check if the current branch is the integration branch:

CURRENT_BRANCH=$(git branch --show-current)

Resolve the integration branch in this order:

1. Integration Branch from .memory/git-config.md (if it exists)
2. Repository default branch via git symbolic-ref refs/remotes/origin/HEAD
3. Fallback: match against main, master, or develop

If the current branch matches the integration branch:

You are about to commit directly to `[branch]`. Direct commits to the integration branch bypass code review and are difficult to revert safely.

[B] Create a feature branch first (recommended)
[C] Continue on [branch] (I understand the risks)

If the user chooses [B]:

After switching, continue the commit flow on the new branch.

If the user chooses [C], proceed with the commit. Log the override in the reasoning log (if active).

Never commit to the integration branch without explicit user confirmation.

…