Add Commit

---
name: add--commit
description: "Knowledge reference for smart mid-workflow commits: adaptive Conventional Commits message logic, type detection, and staging rules."
---

# add--commit — Smart Commit

<!-- uses:
- command: /add-build (conditional)
- mention: /add-done
- mention: /add-pull-request
- script: converge-gates.cjs
-->

## When to Use

- Mid-workflow commits during feature development
- Saving progress checkpoints before risky changes
- Any `git commit` with automatic message generation
- Quick commits with optional `--push` in one step

## When NOT to Use

- **Finalizing a branch** → use `/add-done` instead
- **Creating or updating a PR** → use `/add-pull-request`
- **Force push, rebase, or amend** → out of scope
- **Specific file staging** → stage manually first, then use the command

---

## Adaptive Message Logic

The message format adapts to changeset size:

**≤ 3 files changed** — single-line message:
```
type(scope): objective description in present tense
```

**> 3 files changed** — list format:
```
type: general summary

- context/module: what changed
- context/module: what changed
- context/module: what changed
```

---

## Conventional Commits Type Detection

Infer the type from the diff content:

| Type | When to use |
|------|-------------|
| `feat` | New feature, new functionality |
| `fix` | Bug fix, error correction |
| `refactor` | Code restructure without behavior change |
| `chore` | Config, deps, scripts, tooling |
| `docs` | Documentation only |
| `test` | Test files only |
| `style` | Formatting, whitespace, lint fixes |

When ambiguous, show the inferred type and ask the user to confirm.

---

## Staging Rules

Feature docs live **untracked** until their build starts, so a documental command run mid-development can leave **another feature's** `docs/features/<other>/` untracked in the working tree. NEVER sweep those into the current feature's commit.

**Canonical feature-scoped staging** (stage all code changes + ONLY the current feature's docs):

```bash
git add -A -- . ':(exclude)docs/features/*'
[ -d "${FEATURE_DIR}" ] && git add -A -- "${FEATURE_DIR}"
```

`${FEATURE_DIR}` is the current feature's `docs/features/[NNNN][L]-<slug>` dir. The exclude pathspec keeps every other feature's untracked docs out of the index; the second `add` re-includes only the current one.

---

## Checkpoint Receipt (epic checkpoints only)

A commit made by `{{cmd:add-build}}`'s Checkpoint Sequence at a subfeature
boundary carries the convergence result as a **trailer**, so the checkpoint says
why it was safe to stop there. The commit hash then points at the work AND at
the proof.

The commit carries **the six gate lines** — `GATE_REVIEW`, `GATE_QA_BASELINE`,
`GATE_EPIC`, `GATE_COVERAGE`, `GATE_LEDGER`, `GATES_OK` — **copied verbatim** from
`converge-gates.cjs`'s output, as **body lines** below the Conventional Commits
body. The script emits more keys than these (`REVIEW_PATH`, `BASELINE`,
`EPIC_PENDING`, `COVERAGE_UNCOVERED`, `QA_FEATURE_STATE`); only the six above
belong in the message.

They are **body lines, not git trailers.** `GATE_REVIEW=ok` has no `Key: value`
colon, so `git interpret-trailers` will never parse it — calling them trailers
would promise tooling behaviour that does not exist. `git log --grep=GATES_OK`
works on body lines, which is the only retrieval this needs:

```
feat(0028F-SF02): persist receipt line total on duplicate

- backend: enforce RN03 on the duplicate path
- frontend: surface the persisted total in the header

GATE_REVIEW=ok
GATE_QA_BASELINE=ok
GATE_EPIC=ok
GATE_COVERAGE=ok
GATE_LEDGER=ok
GATES_OK=5/5
```

⛔ DO NOT reformat, summarise, or re-word the gate lines. They are copied, not
authored — a reformatted receipt is indistinguishable from an invented one, and
the whole point is that `git log --grep=GATES_OK` reconstructs which
subfeatures converged and on what evidence, using nothing but git.

⛔ DO NOT write these lines on a commit whose subfeature did not converge. That
commit does not exist: the checkpoint is gated on all five gates reading `ok`,
and the ABSENCE of a commit is itself the signal.

**No new state file.** The receipt lives in the commit message, so it adds no
state file — a commit message is not a second source of truth that can drift
from the tree, it is part of the object that carries the tree.

---

## Examples

**Few files (≤ 3):**
```
feat(auth): add JWT refresh token endpoint
```

**Many files (> 3):**
```
refactor: extract service layer from controllers

- auth: move login/register logic to AuthService
- user: extract UserService from UserController
- order: decouple OrderService dependencies
- shared: add BaseService abstract class
```