smart-commit

Smart Commit

Analyze uncommitted changes → group by cohesion → generate commit messages → output git commands (or execute directly with --execute).

Workflow

sequenceDiagram
    participant C as Claude
    participant U as User
    C->>C: Step 1a: Detect permissions
    C->>C: Step 1b: Learn commit style
    C->>C: Step 1c: Identity diagnostics
    C->>C: Step 1d: Signing diagnostics
    C->>C: Step 1e: AI guard readiness
    C->>C: Step 2: Pre-flight check (precommit)
    C->>C: Step 3: Collect changes + exclude sensitive files
    C->>C: Step 4: Group (high cohesion)
    C->>U: Show commit plan (with Author/Signing/Guard)
    U->>C: Confirm/adjust
    loop Each commit group
        C->>C: Read diff → generate message
        C->>C: AI trailer sanitization
        alt --execute mode
            C->>C: Runtime validation → git commit
        else manual mode
            C->>U: Output git commands
        end
    end
    C->>C: Step 6: Verification + post-commit leak detection

Step 1: Detect Permissions + Learn Style

1a. Permission Detection

Read CLAUDE.md and .claude/rules/git-workflow.md to determine mode:

| Mode | Condition | Behavior | |------|-----------|----------| | manual | No --execute flag (default) | Output commands only | | execute | --execute flag passed | Execute directly (with user approval via AskUserQuestion) |

Default to manual mode. Direct execution requires explicit --execute flag regardless of project git restrictions.

--execute mode: When --execute is passed, use AskUserQuestion to show the full commit plan and get explicit user approval before executing. This is a skill-level exception to git-workflow rules (same pattern as /push-ci).

1b. Learn Commit Style

git log --oneline -15

Infer format, type vocabulary, subject conventions (capitalization/tense/ticket ID), and language from recent commits.

1c. Identity Diagnostics

Shared diagnostic (preferred path):

bash scripts/run-skill.sh git-profile git-profile.sh doctor --json

If the script succeeds, parse the JSON output:

• status: "ok" → silent continue, use effective_identity and signing fields
• status: "warn" → display warnings from issues[], continue
• status: "halt" → display halt issues, stop with guidance

If the script fails (not found, parse error, non-zero exit), fall back to the inline diagnostics below. Infrastructure failure = warn-only; never halt on fallback path itself.

Inline fallback:

# Read effective identity + origin
git config --show-origin --show-scope --get-all user.name
git config --show-origin --show-scope --get-all user.email
# Check environment variable overrides
printf "GIT_AUTHOR_NAME=%s\nGIT_AUTHOR_EMAIL=%s\nGIT_COMMITTER_NAME=%s\nGIT_COMMITTER_EMAIL=%s\n" \
  "${GIT_AUTHOR_NAME:-}" "${GIT_AUTHOR_EMAIL:-}" \
  "${GIT_COMMITTER_NAME:-}" "${GIT_COMMITTER_EMAIL:-}"

Decision logic:

| Condition | Behavior | |-----------|----------| | user.name and user.email resolve to single values | Silent continue, record identity for commit plan | | git config --get user.name returns nothing | HALT — output git config --local user.name "..." setup guidance | | git config --get user.email returns nothing | HALT — output git config --local user.email "..." setup guidance | | GIT_AUTHOR_* or GIT_COMMITTER_* env vars set | Warn: env vars will override config; commit plan shows (env override) | | --get-all returns multiple different values | AskUserQuestion: list candidate profiles, user selects once | | Conflict + CI=true env var | HALT (fail-closed) — output fix guidance, do not silently inherit |

Design principles:

• Diagnostic, not override: Do not use git -c user.name=... to override. Respect includeIf settings.
• Interrupt only on anomaly: Normal identity resolution produces no prompt.
• Conflict ≠ multiple sources: includeIf producing multiple config sources that resolve to the same value = normal.

1d. Signing Diagnostics

git config --show-origin --get commit.gpgsign 2>/dev/null || echo "unset"
git config --show-origin --get user.signingkey 2>/dev/null || echo "unset"
git config --show-origin --get gpg.format 2>/dev/null || echo "gpg"

Decision logic:

| Condition | Behavior | |-----------|----------| | commit.gpgsign=true + key exists | Display Signing: enabled (<gpg.format>) | | commit.gpgsign=true + key missing | ⚠️ Warning: signing enabled but key not configured | | commit.gpgsign unset | Display Signing: not configured (inherit) | | --execute mode signing failure | Immediate stop + fix guidance |

Post-commit visibility (--execute mode):

git log -1 --format='%G?' # N=unsigned, G=good, U=good-untrusted, etc.

Signing override flags (--sign / --no-sign):

| Flag | Effect | Git flag | |------|--------|----------| | --sign | Force signing for this batch | -S on each git commit | | --no-sign | Disable signing for this batch | --no-gpg-sign on each git commit | | Both | Error — mutually exclusive | Halt with error message | | Neither | Inherit from commit.gpgsign config | (default behavior) |

When --sign or --no-sign is used, AskUserQuestion to confirm the override and warn about potential branch protection / CI policy conflicts.

1e. AI Guard Readiness

# Detect effective hook path (handles relative paths and worktrees)
HOOK_FILE=$(git rev-parse --git-path hooks/commit-msg 2>/dev/null)
# If core.hooksPath is set, use it instead
CUSTOM_HOOKS=$(git config --get core.hooksPath 2>/dev/null)
if [ -n "$CUSTOM_HOOKS" ]; then
  # Resolve relative paths against repo root
  case "$CUSTOM_HOOKS" in
    /*) ;; # absolute — use as-is
    *)  CUSTOM_HOOKS="$(git rev-parse --show-toplevel 2>/dev/null)/${CUSTOM_HOOKS}" ;;
  esac
  HOOK_FILE="${CUSTOM_HOOKS}/commit-msg"
fi
# Check commit-msg hook
if [ -f "$HOOK_FILE" ] && [ ! -x "$HOOK_FILE" ]; then
  echo "guard:not-executable"
elif [ -x "$HOOK_FILE" ]; then
  echo "guard:installed"
else
  echo "guard:missing"
fi

Decision logic:

| Condition | Behavior | |-----------|----------| | Hook installed + executable | Display AI guard: active | | Hook not installed | ⚠️ Warning (non-blocking): suggest install (/install-scripts commit-msg-guard then cp .claude/scripts/commit-msg-guard.sh <hooks-path>/commit-msg && chmod +x <hooks-path>/commit-msg) | | Hook exists but not executable | ⚠️ Warning: suggest chmod +x <hook-path> |

Important: Hook installation is NOT a blocker for --execute mode. Runtime validation (Step 5c) provides an independent safety layer.

Step 2: Pre-flight Check

Check precommit status based on change type. Structural .md files (skills/) have test coverage (e.g., skills-schema.test.js) that can catch reference errors CI would find.

| Change Type | Required Check | Rationale | |-------------|---------------|-----------| | Code files (.ts/.js/.py/.go/.rs etc.) | /precommit or /precommit-fast passed | Code correctness + lint | | Structural .md (skills/**) | /precommit-fast passed | Schema/ref tests cover SKILL.md structure | | Other .md (README, docs/) | /codex-review-doc passed (per CLAUDE.md) | No structural tests; doc review sufficient | | Comments / trivial whitespace | Skip allowed | No test coverage expected |

| Status | Action | |--------|--------| | Required check passed in current session after last edit | Continue | | Not run, stale, or uncertain | Halt — ask user to run the required check first |

Freshness: A "passed" result is only valid if it ran after the most recent file edits in this session. Stale results from earlier in the session (before new edits) do not count.

Policy note: This pre-flight is intentionally stricter than the base auto-loop rule (@rules/auto-loop.md), which only requires /codex-review-doc for .md changes. /smart-commit is the la