smart-commit

Files (6)

• SKILL.md
• execute-mode.md · references/
• git-environment.md · references/
• smart-commit-dispatch.sh · scripts/
• smart-commit-execute.sh · scripts/
• smart-commit-inspect.sh · scripts/

SKILL.md (first lines)

# Smart Commit

**Read first**: `@skills/push-ci/references/authorization-contract.md` before `--execute` commits anything — § Proactive Offer for the menu and the four Goal mode conditions, § Efficacy Boundary for what the per-use approval authorizes. If that Read fails, stop and report it; commit nothing (manual mode, which only prints commands, is unaffected).


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

## Workflow

```mermaid
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 (Goal mode: printed with a [GOAL_COMMIT] record, not asked)
    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
```

### Git Environment Policy (applies to every step below)

Every git command **this skill runs itself** — read or write, either mode — resolves the same
question: *which repository, tree, index, ancestry and configuration does it act on?* The answer is
pinned two ways, both defined in [git-environment.md](references/git-environment.md) § 1: the
inherited `GIT_*` variables are stripped, and every command carries `-C "$REPO_ROOT"`.

Where the stripping happens depends on who runs git:

| Callee | How the policy is applied |
|--------|---------------------------|
| A **fence** running `git` inline | The canonical `env -u` prefix, written out **literally** — never through a variable, because zsh does not word-split an expansion used as a command prefix |
| A helper that runs its **own** git commands and does **not** strip (`git-profile.sh`) | The prefix goes on the delegation, at the boundary |
| A helper that strips the same list **itself** (`smart-commit-inspect.sh`, `smart-commit-execute.sh`) | No prefix — the script's own `unset` block is the policy, and prefixing it as well would state the same rule twice in two places that could drift |

Every `/bin/bash -p -- "$INSPECT" …` call is the third row — all ten of them, across Steps 1b–1e,
3, 4, 5a and 6 — because `smart-commit-inspect.sh` unsets the list once for the whole process.
`$REPO_ROOT` is still re-derived in every fenced block: each block is a separate shell, so nothing
carries over.

What the skill **prints** is governed by § 2 of that file — the same list, the same spelling.

### 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 — or, under § Goal mode, without it) |

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`). The one exception to asking is § Goal mode below.

### Goal mode (git-autonomy FR-17)

While a goal **the user** set or approved is active, and `rules/git-workflow.md` § Proactive Offer
"Goal mode" says all four of its conditions hold — re-checked before every commit, including
`review-state.js goal-commit --format=json` returning `ok: true` — `--execute` runs without the plan
approval: the plan is **printed**, headed by one record line, and execution proceeds:

```
[GOAL_COMMIT] goal=<first 12 hex of `git hash-object --stdin` of the goal condition> | branch=<branch> | digest=<digest> | <ISO8601>
```

The goal text itself is never printed — a user may have put a secret in it. Everything else in this
skill is unchanged: every diagnostic and HALT, the sensitive-file exclusion, the attribution guard
on `smart-commit-execute.sh commit`, and every **judgement** question (an identity conflict, an
ambiguous grouping, a `--sign`/`--no-sign` override) still asks. `--ai-co-author` is never passed on
this path: when the user explicitly asks for it, Goal mode does not apply and the ordinary per-use
approval runs, so the attribution whitelist is always reached through the user. `needs_branch_allowance: true` means the first goal-mode commit on that protected branch
asks first (recommend a feature branch; if declined, ask to allow the branch for this goal).

**1b. Learn Commit Style**

```bash
REPO_ROOT=$(/usr/bin/env -u GIT_DIR -u GIT_WORK_TREE -u GIT_COMMON_DIR -u GIT_INDEX_FILE -u GIT_OBJECT_DIRECTORY -u GIT_ALTERNATE_OBJECT_DIRECTORIES -u GIT_NAMESPACE -u GIT_CEILING_DIRECTORIES -u GIT_GLOB_PATHSPECS -u GIT_ICASE_PATHSPECS -u GIT_NOGLOB_PATHSPECS -u GIT_LITERAL_PATHSPECS -u GIT_CONFIG -u GIT_CONFIG_PARAMETERS -u GIT_CONFIG_COUNT -u GIT_CONFIG_NOSYSTEM -u GIT_CONFIG_GLOBAL -u GIT_CONFIG_SYSTEM -u GIT_IMPLICIT_WORK_TREE -u GIT_GRAFT_FILE -u GIT_SHALLOW_FILE -u GIT_PREFIX -u GIT_NO_REPLACE_OBJECTS -u GIT_REPLACE_REF_BASE -u GIT_EXTERNAL_DIFF -u ALLOW_AI_COAUTHOR git rev-parse --show-toplevel && printf .) || { echo "⚠️ could not resolve the repository root — aborting" >&2; exit 1; }
REPO_ROOT=${REPO_ROOT%.}; REPO_ROOT=${REPO_ROOT%$'\n'}
INSPECT="$REPO_ROOT/.claude/scripts/smart-commit-inspect.sh"
[ -r "$INSPECT" ] || INSPECT="$REPO_ROOT/skills/smart-commit/scripts/smart-commit-inspect.sh"
[ -r "$INSPECT" ] || { echo "⚠️ smart-commit-inspect.sh not found — run /install-scripts" >&2; exit 1; }
/bin/bash -p -- "$INSPECT" style
```

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

| Condition | Behavior |
|-----------|----------|
| Commits listed | Infer the convention from them |
| Non-zero exit, `does not have any commits yet` on stderr | **Not an error** — this is the first commit of a new repository, which is a case `/smart-commit` exists for. Fall back to the default `<type>: <subject>` convention and continue. Do **not** apply the "stop and report the stderr" rule the later steps carry: they read state a commit depends on, this one reads history that may legitimately be empty |
| Any other non-zero exit | Stop and report the stderr — the repository could not be read |

**1c. Identity Diagnostics**

**Shared diagnostic (preferred path)**:

```bash
REPO_ROOT=$(/usr/bin/env -u GIT_DIR -u GIT_WORK_TREE -u GIT_COMMON_DIR -u GIT_INDEX_FILE -u GIT_OBJECT_DIRECTORY -u GIT_ALTERNATE_OBJECT_DIRECTORIES -u GIT_NAMESPACE -u GIT_CEILING_DIRECTORIES -u GIT_GLOB_PATHSPECS -u GIT_ICASE_PATHSPECS -u GIT_NOGLOB_PATHSPECS -u GIT_LITERAL_PATHSPECS -u GIT_CONFIG -u GIT_CONFIG_PARAMETERS -u GIT_CONFIG_COUNT -u GIT_CONFIG_NOSYSTEM -u GIT_CONFIG_GLOBAL -u GIT_CONFIG_SYSTEM -u GIT_IMPLICIT_WORK_TREE -u GIT_GRAFT_FILE -u GIT_SHALLOW_FILE -u GIT_PREFIX -u GIT_NO_REPLACE_OBJECTS -u GIT_REPLACE_REF_BASE -u GIT_EXTERNAL_DIFF -u ALLOW_AI_COAUTHOR git rev-parse --show-toplevel && printf .) || { echo "⚠️ could not resolve the repository root — aborting" >&2; exit 1; }
REPO_ROOT=${REPO_ROOT%.}; REPO_ROOT=${REPO_ROOT%$'\n'}
/usr/bin/env -u GIT_DIR -u GIT_WORK_TREE -u GIT_COMMON_DIR -u GIT_INDEX_FILE -u GIT_OBJECT_DIRECTORY -u GIT_ALTERNATE_OBJECT_DIRECTORIES -u GIT_NAMESPACE -u GIT_CEILING_DIRECTORIES -u GIT_GLOB_PATHSPECS -u GIT_ICASE_PATHSPECS -u GIT_NOGLOB_PATHSPECS -u GIT_LITERAL_PATHSPECS -u GIT_CONFIG -u GIT_CONFIG_PARAMETERS -u GIT_CONFIG_COUNT -u GIT_CONFIG_NOSYSTEM -u GIT_CONFIG_GLOBAL -u GIT_CONFIG_SYSTEM -u GIT_IMPLICIT_WORK_TREE -u GIT_GRAFT_FILE -u GIT_SHALLOW_FILE -u GIT_PREFIX -u GIT_NO_REPLACE_OBJECTS -u GIT_REPLACE_REF_BASE -u GIT_EXTERNAL_DIFF -u ALLOW_AI_COAUTHOR /bin/bash -p -- "$REPO_ROOT/scripts/run-skill.sh" git-profile git-profile.sh doctor --json
```

From sd0xdev/sd0x-harness, MIT.

More from sd0xdev/sd0x-harness