Commit Message Standard

Purpose

Standardize git commit messages as structured knowledge artifacts with full traceability to framework decisions, solutions, patterns, standards, goals, and trade-offs

Examples

Rules

CMT-001: Commit message MUST have three sections separated by blank lines — header, body, trailers

Git tooling (log --oneline, GitHub PR list) uses the first line as summary. Body provides context. Trailers provide structured metadata parseable by git interpret-trailers and git log %(trailers).

Verification: git log --format='%s%n%n%b' shows clean separation

CMT-002: Header MUST be a single line, max 72 characters

Git log, GitHub, and terminal tools truncate at 72 chars. Long headers are unreadable in oneline format. The header is a SUMMARY, not a description.

Verification: git log --oneline | awk '{print length}' — all under 72

CMT-003: Body MUST wrap at 72 characters per line

Git log displays body as-is. Unwrapped lines overflow terminals and are hard to read in git log, email patches, and code review tools.

Verification: Visual inspection in git log

CMT-010: Header MUST follow Conventional Commits format: <type>(<scope>): <subject>

Conventional Commits v1.0.0 is the industry standard for structured commit headers. Enables automated changelog generation, semantic versioning, and git log filtering by type.

CMT-011: Type MUST be one of: feat (new capability), fix (bug repair), refactor (restructure without behavior change), docs (documentation only), test (test additions/changes), chore (tooling/config/dependencies), perf (performance improvement), ci (CI/CD changes), build (build system), revert (revert previous commit)

Fixed type vocabulary enables filtering (git log --grep='^feat'), automated changelog sections, and semantic version bumping (feat=minor, fix=patch, BREAKING CHANGE=major).

Verification: git log --oneline | grep -v '^[a-f0-9]* (feat|fix|refactor|...)'

CMT-012: Scope MUST identify the framework domain or component affected. Valid scopes: decisions, framework, knowledge, governance, sbx-web, sbx-api, sbx-cli, infrastructure, persistence, agents, adapters, packages, git, docker, sessions

Scopes map to the 5-section navigation taxonomy (Decision #0055) and framework domains. Enables filtering commits by area: git log --grep='^feat(sbx-web)' shows all web UI features.

Verification: Scope matches registered list or is a package/project name

CMT-013: Subject MUST use imperative mood, no period, start lowercase after colon+space

Imperative mood ("add feature" not "added feature") reads as a command — "this commit will: add feature". Git's own generated messages use imperative (Merge branch, Revert "..."). Consistency.

Verification: Visual inspection — verb form, no trailing period

CMT-014: Subject MAY include a decision or milestone reference inline when it is the PRIMARY topic

For decision/milestone commits, the ID in the subject enables quick scanning: git log --oneline --grep='#0070'. Only include when the commit IS the decision/milestone — not for tangential references.

Verification: Decision ID format: #NNNN. Milestone format: M{N}

CMT-020: Body MUST explain PURPOSE — why this change exists, what goal or problem it addresses

The diff shows WHAT changed. Only the human (or agent) knows WHY. Purpose connects implementation to motivation. Without it, future readers must reverse-engineer intent from code changes.

Verification: Body contains explicit purpose/motivation statement

CMT-021: Body SHOULD describe APPROACH — what strategy was chosen and how it was implemented

When multiple approaches exist, documenting the chosen one helps future readers understand the reasoning without re-researching. Especially important for non-obvious solutions.

Verification: Body describes the approach for non-trivial changes

CMT-022: Body SHOULD document TRADE-OFFS for significant changes — what was gained vs what was accepted

Every design choice has trade-offs. Documenting them prevents future developers from "improving" code without understanding why the current approach was chosen. Maps to the pattern protocol's trade_offs field.

Verification: Body mentions trade-offs for architectural/design changes

CMT-023: Body MUST NOT duplicate the diff — explain what and why, not how line-by-line

The diff is always available via git show. Restating "changed X to Y on line N" wastes space and becomes stale if the commit is rebased. Focus on intent, not mechanics.

Verification: Body does not repeat file-level changes visible in diff

CMT-024: Body MAY include a brief list of key changes for multi-file commits

For commits touching 5+ files, a summary list helps readers understand scope without reading the full diff. Keep it high-level — file groups or logical changes, not individual line changes.

Verification: Multi-file commits have summary when scope is large

CMT-030: Trailers MUST use RFC 822 format: Token: value (one per line, after blank line)

Git interprets trailers natively via git interpret-trailers. RFC 822 format is parseable by %(trailers:key=X,valueonly) in git log --format. Conventional Commits v1.0.0 defines footers as git trailers.

Verification: git interpret-trailers --parse <commit-msg> parses correctly

CMT-031: Co-Authored-By trailer MUST be present on all AI-assisted commits

Attribution is non-negotiable. Every commit must declare whether it was human-authored, AI-assisted, or AI-generated. GitHub recognizes Co-Authored-By for contribution graphs.

Verification: git log --format='%(trailers:key=Co-Authored-By)' shows attribution

CMT-032: Problem trailer MUST be present on all fix() type commits

Decision #0070 — every bug fix records what problem it resolves. Enables sbx resolve search to find how problems were fixed. Format: Problem: kebab-case-problem-id

Verification: All fix() commits have Problem: trailer

CMT-033: Root-Cause trailer MUST be present on fix() commits where root cause was identified

Root cause documentation prevents re-introducing the same bug. When the root cause is known, recording it is mandatory. When genuinely unknown (workaround fix), omission is acceptable.

Verification: fix() commits have Root-Cause: unless explicitly unknown

CMT-034: Solution trailer SHOULD be present when the fix/feat applies a known solution artifact

Links to .framework/knowledge/guidelines/ artifact. Creates bidirectional traceability: guideline describes the pattern, commit records each application of it. Enables: sbx resolve by-solution <name> to find all applications.

Verification: Solution: value matches an existing guidelines/**/*.yml name

CMT-035: Decision trailer SHOULD be present when the commit implements or is guided by a decision record

Links to decisions/NNNN-title/. Creates traceability from implementation back to the architectural choice that guided it. Enables: sbx resolve by-decision <id>.

Verification: Decision: #NNNN matches existing decision directory

CMT-036: Pattern trailer MAY be present when the commit applies a known design pattern

Links to .framework/knowledge/design-patterns/ artifact. Documents which design patterns informed the implementation. Enables pattern usage tracking across the codebase.

Verification: Pattern: value matches an existing patterns/*.yml name

CMT-037: Standard trailer MAY be present when the commit enforces or implements a governance standard

Links to .framework/knowledge/rules/ artifact. Documents which standards the commit adheres to or implements.

Verification: Standard: value matches an existing standards/*.yml name

CMT-038: Goal trailer SHOULD be present on feat() commits that advance a workspace goal

Links to workspace.yml goals (G1-G6). Creates vertical traceability from implementation to strategic motivation. Enables: git log --grep='Goal: G5' to see all G5-related work.

Verification: Goal: G{N} or G{N}.{M} matches workspace.yml goals

CMT-039: Breaking-Change trailer MUST be present when the commit changes public API, data format, or behavior

Conventional Commits uses BREAKING CHANGE footer for major version bumps. Explicit declaration prevents downstream breakage by alerting consumers before they update.

Verification: Breaking changes in diff have corresponding trailer

CMT-040: Keywords trailer SHOULD be present for discoverability on non-trivial commits

Free-text search terms that complement the structured trailers. Captures domain terminology, technology names, and concepts that aid future search. Format: Keywords: term1, term2, term3

Verification: Non-trivial commits have Keywords for searchability

CMT-041: Affected-Files trailer MAY be present as a scale indicator on large commits

Quick indicator of change scope without reading the diff. Format: Affected-Files: N files

Verification: Count matches git diff --stat file count

CMT-065: Component-Type trailer SHOULD be present on all feat() and fix() commits that create or modify UI components. Valid values: animation, section, layout, primitive, template, background.

Components span multiple scopes (components, animations, games). Without a type trailer, searching git history for "all animation work" requires guessing multiple grep patterns. Component-Type enables: git log --all --grep='Component-Type: animation' --oneline Retrospective evidence: TextAnimationCard had 7 fix cycles spread across 3 different commit scopes — 5 of 7 fixes were invisible to a single scope-based search.

Verification: Component commits have Component-Type trailer

CMT-066: Component-Category trailer SHOULD be present on component commits. Values are domain-specific: text, branding, card, tooltip, link-preview, nav, game, background, effect, form. Multiple categories are comma-separated.

Finer-grained than Component-Type. Enables /component-import to query: git log --grep='Component-Category: link-preview' and find ALL link-preview work regardless of commit scope or type. Retrospective evidence: link-preview required a full revert + 2 fix cycles because prior import lessons were unsearchable.

Verification: Component commits have Component-Category trailer

CMT-067: SDLC-Step trailer MAY be present to record which FDD step produced the commit

Connects implementation to the SDLC state machine. Enables: git log --grep='SDLC-Step: FDD4.UI' to see all UI implementation work. Useful for retrospectives and process improvement.

Verification: SDLC-Step matches FDD{N}.{STEP} format

CMT-068: fix() commits for components SHOULD include a LESSONS block in the body with four fields: Unprepared (what assumption failed), Issue (what went wrong), Resolution (how it was fixed), Rule (one-line prevention rule).

Fix knowledge dies at session boundaries. The /component-import skill can query git log for LESSONS blocks and inject them as context for the next import. Without structured lessons, each session rediscovers the same failures. Retrospective evidence: gradient-mesh had 3 fix cycles trying tick(), then conditional gate removal, then $effect — the winning approach was only in the third commit's unstructured body.

Verification: Component fix commits have LESSONS block with 4 fields

CMT-050: fix() commits MUST include: Problem, Root-Cause, Co-Authored-By. SHOULD include: Solution, Decision, Keywords.

Fix commits are RESOLUTION records. The minimum metadata to make a fix searchable and traceable is the problem ID and root cause. Solution and Decision link to framework governance.

Verification: All fix() commits have minimum required trailers

CMT-051: feat() commits MUST include: Co-Authored-By. SHOULD include: Goal, Decision, Keywords. MAY include: Pattern, Standard. For component work, SHOULD also include: Component-Type, Component-Category.

Feature commits advance goals. The Goal trailer creates vertical traceability. Decision and Keywords aid discoverability. Pattern/Standard document the governance foundation. Component-Type/Category enable domain-filtered git history searches.

Verification: feat() commits have goal linkage where applicable

CMT-052: refactor() commits MUST include: Co-Authored-By. SHOULD include: Keywords, Decision (if decision-driven). Body MUST explain what motivated the refactoring.

Refactoring has no user-visible change but alters code structure. Without motivation in the body, future readers cannot distinguish intentional restructuring from unnecessary churn.

Verification: refactor() body explains motivation

CMT-053: chore/docs/test/ci commits MUST include: Co-Authored-By. Other trailers are optional but encouraged for non-trivial changes.

Infrastructure commits are often low-ceremony. Requiring full trailer decoration would slow down routine maintenance. Keep the barrier low for supporting work.

Verification: At minimum Co-Authored-By present

Tags

Overview