# Commit Conventions

This document covers two things:

1. The commit message format Argyph uses (Conventional Commits).
2. The project's policy on attributing AI assistance — when a `Co-authored-by:` trailer for Claude (or any AI tool) is appropriate, and when it isn't.

The second part is the part that matters most. Read it carefully.

---

## 1. Format

Argyph uses [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/). Every commit subject follows:

```
<type>(<scope>): <description>
```

### Allowed types

| Type       | Use for                                                                  |
|------------|--------------------------------------------------------------------------|
| `feat`     | A new user-facing feature                                                |
| `fix`      | A bug fix                                                                |
| `perf`     | A change that improves performance                                       |
| `refactor` | A change that neither adds a feature nor fixes a bug                     |
| `docs`     | Documentation only                                                       |
| `test`     | Adding or correcting tests                                               |
| `build`    | Build system, dependencies, release pipeline                             |
| `ci`       | GitHub Actions or other CI config                                        |
| `chore`    | Maintenance that doesn't fit elsewhere                                   |
| `style`    | Formatting, whitespace, lint fixes with no behavior change               |
| `revert`   | Reverting a previous commit                                              |

### Allowed scopes

Scope is the crate or area: `fs`, `parse`, `graph`, `embed`, `store`, `pack`, `core`, `mcp`, `cli`, `bin`, `docs`, `ci`, `release`, `bench`. Omit the scope for cross-cutting changes.

### Examples

```
feat(graph): add get_callees query with cross-file resolution
fix(store): handle SQLite WAL checkpoint failures gracefully
perf(embed): batch ONNX inference to reduce per-chunk overhead
docs(architecture): clarify supervisor cancellation flow
build: bump tree-sitter-rust to 0.21
ci: add Windows ARM target to release matrix
refactor(mcp)!: rename search_semantic params for clarity
```

The `!` after the type/scope marks a breaking change. Breaking changes also require a `BREAKING CHANGE:` footer.

### Body and footers

The body explains *what* and *why*. The diff explains *how*. Wrap at 72 columns.

Footers (one per line, after a blank line following the body):

- `Refs: #123` — references an issue
- `Closes: #123` — closes an issue on merge
- `Fixes: #123` — same as Closes for bug fixes
- `BREAKING CHANGE: <description>` — required for any change marked `!`
- `Co-authored-by: Name <email>` — see § 2 below

---

## 2. Attribution policy (the important section)

Argyph is built by [Ezzy1630](https://github.com/Ezzy1630) with the help of AI assistants — most often Claude. We are honest about that. We are also clear-eyed about credit. The point of building Argyph is, in part, to demonstrate engineering judgment, and the public commit history is part of that demonstration.

The default position is: **the human is the author. The AI is not.** Attribution trailers for AI tools are reserved for a narrow set of cases.

### 2.1 Always

- The `Author:` field of every commit is the human who reviewed and merged the change. There is no commit in this repository where an AI agent is the named author.
- The `AUTHORS.md`, `MAINTAINERS.md`, README, package metadata, and any "about" or "by" line list humans only.

### 2.2 When `Co-authored-by:` for AI is appropriate

A `Co-authored-by:` trailer for an AI tool is appropriate **only** when all of the following are true:

1. The AI generated a substantial code contribution — typically more than ~50 lines of non-trivial code in a single commit.
2. The human reviewed, edited, and integrated that contribution rather than accepting it as-is.
3. The work was a discrete, well-scoped feature or implementation, not routine assistance.

Examples that warrant a trailer:

- Implementing the body of a new MCP tool from a specified contract.
- Generating a complete tree-sitter language pack from `.scm` queries.
- Writing the first draft of a non-trivial integration test suite.

When a trailer is appropriate, use:

```
Co-authored-by: Claude <noreply@anthropic.com>
```

Place it as a **single trailer** at the end of the message. Do not stack multiple AI tools.

### 2.3 When `Co-authored-by:` for AI is NOT appropriate

- Routine autocomplete or tab-completion.
- Small refactors, renames, or cleanups suggested mid-edit.
- Doc polish, typo fixes, formatting changes.
- Lint or test fixes generated by the AI from a failing CI run.
- Architecture, design, or product decisions — those are human work even when discussed with an AI.
- Code review — even if the AI surfaced the bug, the fix is yours.
- Anything where the AI's contribution was below "substantial" by reasonable judgment.

A useful test: would a senior engineer reading the commit log think "this person leaned on AI for that"? If yes, the trailer is fine. If a reasonable person would think "this person co-shipped that with a tool," that's misleading and the trailer should be omitted.

### 2.4 Why this policy

There is a temptation, when working with AI assistants, to add `Co-authored-by:` to every commit out of either habit or politeness. Don't. It is misleading on three fronts:

1. **It overstates the AI's contribution.** Most commits in this repo will involve some AI assistance. Most of that assistance is the modern equivalent of an IDE — autocomplete, lookups, formatting. Tagging every commit makes the trailer meaningless.
2. **It understates the human's contribution.** The architecture, the cuts, the trade-offs, the review, the integration, the call on what to ship — that is a real engineering contribution. Reflexive co-attribution dilutes it.
3. **It sends the wrong signal externally.** A commit log dominated by `Co-authored-by: Claude` reads, fairly or not, as "this person ships AI output." That is not the project this is, and not the signal we want it to send.

The correct signal is: this is a thoughtfully-architected systems project where the author used AI assistance as a tool — substantial enough to be worth acknowledging where it materially shaped a commit, routine enough that most commits don't carry the trailer.

### 2.5 Disclosure in the project metadata

To stay honest about AI assistance overall, the project discloses AI use in two places that are durable and visible:

- The README's "Contributing" section notes that the project is built with substantial AI assistance and human-reviewed.
- `CONTRIBUTING.md` includes a dedicated "AI Agent Rules" section that everyone (human and AI) follows.

That is the right level of disclosure: clear, honest, in context. It does not require a trailer on every commit.

---

## 3. Squash-merge rule

Pull requests are squash-merged. The maintainer curates the final commit message at merge time:

- The squash subject is the curated, conventional-format message.
- The squash body summarizes the change.
- Any appropriate `Co-authored-by:` trailers are added at this point, following the policy above.
- Granular work-in-progress commit messages from the PR branch (`wip`, `fix typo`, `respond to review`) do not appear in the main branch history.

This is intentional. The main branch history is curated to be readable as a story of the project's evolution.

---

## 4. Examples

### Good — AI-attribution warranted

```
feat(parse): add tree-sitter language pack for Go

Adds Go to the list of supported languages. Includes:

- tree-sitter-go dependency pin (v0.21)
- symbol-extraction queries in queries/go.scm covering
  function declarations, method declarations, struct types,
  interface types, and import statements
- chunking strategy that respects function and struct boundaries
- 28 unit tests against fixtures in examples/tiny-go-app

Refs: #142

Co-authored-by: Claude <noreply@anthropic.com>
```

### Good — AI-attribution NOT warranted

```
fix(store): debounce WAL checkpoint on rapid writes

The watcher could trigger multiple SQLite checkpoints per second
during bulk reindexing, dragging Tier 1 throughput below baseline.
Debouncer now coalesces checkpoint requests to one per 250ms.

Fixes: #178
```

(AI may have helped surface the symptom or suggest the fix; the engineering decision and integration are yours.)

### Bad — gratuitous attribution

```
docs: fix typo in ARCHITECTURE.md

Co-authored-by: Claude <noreply@anthropic.com>
```

A typo fix is not a co-authored contribution. Drop the trailer.

### Bad — AI as primary author

```
Author: Claude <noreply@anthropic.com>
```

Never. The author is always the human.

---

## 5. Enforcement

- A commit-message lint job in CI checks for valid Conventional Commits format on PR titles (which become the squash subjects).
- Reviewers are instructed to push back on commits with attribution trailers that do not meet the § 2.2 bar, and to suggest removal during PR review.
- This policy applies to maintainers as well as external contributors. There are no exceptions for the project author.
