ring-committing-changes

name: ring:committing-changes description: "Committing working-tree changes as atomic conventional commits: analyzes the diff, groups it into coherent commits, confirms the plan, then creates GPG-signed commits carrying the mandatory X-Lerian-Ref trailer and offers to push. Use when the user says 'commit' or has changes ready to record. Skip when the tree is clean, work is still in progress, or the user wants raw git commands without grouping."

Smart Commit Organization

When to use

• User asks to commit changes or says "commit"
• Working directory has staged or unstaged changes ready to commit
• End of a development task where changes need to be recorded

Skip when

• No changes in working directory
• Changes are still work-in-progress
• User explicitly wants raw git commands without smart grouping

Analyze changes, group into coherent atomic commits, create signed commits following repository conventions.

Smart Commit Organization

Analyze → Group → Order → Confirm → Execute.

Grouping principles:

Commit order: dependencies first → core changes → tests with implementation → docs last.

Single commit when: all changes are one coherent feature/fix, or user provides a specific message.
Multiple commits when: changes span different concerns.

⛔ HARD STOP — TRAILER RULES

THE MOST COMMON MISTAKE: Putting trailer text INSIDE the -m quotes.

# ❌ WRONG — trailer text INSIDE -m quotes
git commit -m "feat: add feature

X-Lerian-Ref: 0x1"

# ✅ CORRECT — --trailer is a SEPARATE argument OUTSIDE quotes
git commit -S -m "feat: add feature" --trailer "X-Lerian-Ref: 0x1"

Checkpoint before writing any commit command:

• -m "..." contains ONLY the commit message (no trailer text inside)
• --trailer is OUTSIDE and AFTER all -m parameters
• Structure: git commit -S -m "msg" --trailer "X-Lerian-Ref: 0x1"

MANDATORY RULES

1. NEVER include in commit message body: emoji signatures, hashtags, Co-Authored-By, "Generated by", X-Lerian-Ref text, or any system markers.
   -m contains ONLY the commit description. Period.

2. ALWAYS use --trailer "X-Lerian-Ref: 0x1" — separate command-line argument after all -m parameters.

3. ALWAYS use -S for GPG signing — skip only if GPG key not configured.

Commit Process

Step 1: Gather Context

git status
git diff && git diff --cached
git log --oneline -10  # reference style

Step 2: Analyze and Group

Determine type (feat/fix/chore/docs/refactor/test/perf/ci), scope, and logical group for each file.

Step 3: Present Plan and Confirm

Proposed Commit Plan:
1. feat(auth): add OAuth2 refresh token support
   - src/auth/oauth.ts, src/auth/oauth.test.ts
2. chore(deps): update authentication dependencies
   - package.json, package-lock.json

Proceed? [Execute plan / Single commit / Let me review]

Use AskUserQuestion to confirm. MANDATORY: get confirmation before executing.

Step 4: Draft Commit Messages

• Subject: max 50 chars, imperative mood ("add" not "added")
• Body: wrap at 72 chars, explain motivation (optional)
• NO emoji, hashtags, markers of any kind in the body

Step 5: Execute Commits

For each group:

git add <file1> <file2>
git commit -S \
  -m "<type>(<scope>): <subject>" \
  -m "<optional body>" \
  --trailer "X-Lerian-Ref: 0x1"

Step 6: Verify

git log --oneline -<N>
git log --show-signature -1  # if signed
git status  # confirm clean

Step 7: Offer Push

Ask user: push to remote? If yes: git push (or git push -u origin <branch> if no upstream).

Examples

# Feature
git commit -S -m "feat(auth): add OAuth2 refresh token support" --trailer "X-Lerian-Ref: 0x1"

# Bug fix
git commit -S -m "fix(api): handle null response in user endpoint" --trailer "X-Lerian-Ref: 0x1"

# Chore
git commit -S -m "chore(deps): update authentication dependencies" --trailer "X-Lerian-Ref: 0x1"

Trailer Query

git log --all --format="%H %s %(trailers:key=X-Lerian-Ref,valueonly)" | grep "0x1"
git log -1 --format="%(trailers)"

When User Provides Message

Skip grouping. Use their message as subject. Still sign with -S and add trailer.

git commit -S -m "fix: fix login bug" --trailer "X-Lerian-Ref: 0x1"

Anti-Patterns (FORBIDDEN)

# ❌ Trailer text inside -m
git commit -m "feat: add feature\n\nX-Lerian-Ref: 0x1"

# ❌ Emoji/hashtags in body
git commit -m "feat: add feature\n\n🤖 Generated with Claude Code"

# ❌ Co-Authored-By in body
git commit -m "feat: add feature\n\nCo-Authored-By: System <noreply@example.com>"

# ❌ Hashtag tracking
git commit -m "feat: add feature #0x1"

All of these pollute the commit message body. Use --trailer as a separate flag — always.