| name | ai-commit |
| description | Runs the governed commit pipeline: auto-branches from protected, stages selectively, formats and lints, scans for secrets, gates docs, composes a conventional message, pushes. Trigger for 'commit my changes', 'save my work', 'push this to remote', 'stage these files', 'ship it'. Not for opening a PR; use /ai-pr instead. Not for branch hygiene; use /ai-branch-cleanup instead. |
| effort | cheap |
| argument-hint | --force|--only|[message hint] |
| tags | ["git","commit","push","hooks","delivery"] |
| requires | {"bins":["gitleaks","ruff"]} |
Commit Workflow
Runs the governed commit pipeline -- stage, format, lint, secret-detect, compose a conventional message, push -- honoring CLAUDE.md Don't rules (binding). Use /ai-pr when the goal is a pull request; see Quick Reference for invocation forms.
Process
0. Auto-branch from protected
If current branch is main/master: infer type (feat/, fix/, chore/, docs/, refactor/), generate slug deterministically with python3 .ai-engineering/scripts/branch_slug.py --prefix <type> (reads spec.md frontmatter), then git checkout -b <output>, report new branch.
1. Work item context (optional)
If .ai-engineering/specs/spec.md frontmatter has refs: include work item refs as commit body trailers (Refs: AB#101, AB#102, #45). Only include close_on_pr items — never features.
2. Instinct consolidation
If .ai-engineering/observations/observations.yml exists, run /ai-session-watch --review to consolidate session observations before committing.
3. Stage changes
git add <file1> <file2> selectively. Use git add -A only when explicitly requested. Exclude generated files, secrets, large binaries.
4. Run gate orchestrator
ai-eng gate run --cache-aware --json --mode=local
The orchestrator runs the 2-wave collector (Wave 1 fixers serial -> Wave 2 checkers parallel) with cache-aware lookup, emitting .ai-engineering/state/gate-findings.json (schema v1) covering every check. After Wave 1 fixers rewrite files, the orchestrator re-stages the safe S_pre & M_post intersection (spec-105 D-105-09); pass --no-auto-stage to disable, or set gates.pre_commit.auto_stage: false in the manifest.
5. Handle gate result
- Exit 0 -- all checks PASS or auto-fixed. Continue to Commit.
- Exit non-zero -- parse
gate-findings.json, report failing checks per rule_id + severity, STOP. Fix root cause, re-stage, re-run /ai-commit. Override only when remediation is tracked elsewhere and the publish window forces it: ai-eng risk accept-all .ai-engineering/state/gate-findings.json --justification "<reason>" --spec <spec-id> --follow-up "<plan>" writes one DEC entry per finding with severity-default TTL (see .ai-engineering/reference/risk-acceptance-flow.md).
6. Confirm commit readiness
The documentation gate inside the orchestrator is mandatory.
See .ai-engineering/reference/gate-policy.md for the local fast-slice + CI authoritative split.
7. Commit
Compose message via python3 .ai-engineering/scripts/commit_compose.py --type <type> [--task X.Y] --desc "<desc>". --desc is mandatory (spec-139 M8 D-139-06) — derive it from the current plan.md task title (grep -m1 '^- \[ \] ' .ai-engineering/specs/plan.md) or from staged-files / operator hint on off-chain WIP commits. The legacy <DESC> placeholder fallback is deprecated. Doc-gate via python3 .ai-engineering/scripts/doc_gate.py --changed-paths "<staged>" (exit 1 → block; CHANGELOG.md or README.md must accompany changes under src/, tools/, .claude/skills/).
- With active spec:
feat(spec-NNN): Task X.Y -- <desc>, fix(spec-NNN): <desc>, chore(spec-NNN): <desc>.
- Without spec:
type(scope): description (conventional commits, imperative mood). Valid types: feat, fix, perf, refactor, style, docs, test, build, ci, chore, revert.
--force skips preview; otherwise preview and confirm.
8. Push
git push origin <current-branch>. Block if on main/master.
/commit --only
Execute the full pipeline through Commit. Skip Push.
Drift recovery
Exit 78 = stack drift. Run ai-eng doctor --fix in shell, retry. Never --no-verify.
Examples
User: "commit only the spec files and don't push yet" → /ai-commit --only .ai-engineering/specs/ stages only the named paths, runs the full pipeline (auto-branch, ruff format + lint, gitleaks scan, doc gate, conventional message) through commit, and stops before push.
Quick Reference
| Goal | Command |
|---|
| Auto-stage, format, lint, scan, commit, push | /ai-commit |
| Stage only named files | /ai-commit --only path/to/file.py |
| Provide a message hint | /ai-commit "fix(auth): ..." |
| Skip preview | /ai-commit --force |
| Stop before push | /ai-commit --only ... |
Integration
Called by: user directly (off-chain, WIP-only flows). /ai-pr carries the same Steps 0-6 inline (single-responsibility per spec-132 T-3) — it does NOT delegate back here. Calls: git, ruff, gitleaks, ai-eng spec verify --fix. Reads: manifest.yml, CLAUDE.md. See also: /ai-pr, /ai-branch-cleanup, /ai-resolve-conflicts.
$ARGUMENTS
