git

Core Rules

1. No co-author lines. Never add Co-Authored-By, Signed-off-by, or any trailer to commit messages. No exceptions.
2. LGTM before commit. Never commit without explicit user approval. Present the diff, wait for LGTM or equivalent confirmation.
3. Never commit excluded files. plan.md, *review.md, .env, .env.*, credentials, secrets, API keys — never stage these. If they appear in git status, warn the user and exclude them.
4. Never push without permission. Always ask before pushing to remote.
5. One plan item = one focused commit. Never batch multiple plan items into one commit. With multiple items dirty, stage and commit them separately, with LGTM per commit.

Commit Message Format

Commit messages are proper English sentences. Capitalized, clear, appropriately detailed. No emdashes or endashes.

Structure

<type>: <Capitalized summary: what and why, not how>

- Bullet points for notable changes (when the summary alone isn't enough)
- Each bullet is a complete thought, capitalized
- Focus on what changed and why, not implementation details

Type Prefixes

Examples

Good — right level of detail:

feat: Add HNSW partial indexes for dimension-aware vector search

- Add dimensions column to chunks and agent_memories with backfill
- Create partial HNSW indexes for 384, 768, 1024, 1536 dimensions
- Update knowledge_store and memory_repo with dimension-cast SQL
- 16 integration tests including EXPLAIN plan verification

fix: Nested markdown fences fail to parse in fact extraction

Strip all fence markers with re.sub instead of single regex match.

test: Memory SSE callbacks and hook execution tests

Bad — avoid these patterns:

feat: add hnsw partial indexes for dimension-aware vector search

(Lowercase after prefix — should be capitalized)

feat: Add HNSW partial indexes for dimension-aware vector search

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

(Co-author line — never)

(Also avoid: missing type prefix, vague summaries, run-on paragraphs. Use bullets.)

Commit Workflow

Step 1: Review changes

Run in parallel:

• git status (never use -uall)
• git diff HEAD (full picture: staged + unstaged)
• git log --oneline -5 (recent history for style reference)

Step 2: Check for excluded files

Check the diff against Core Rule 3's exclusion list. Never stage matches. Warn the user if they explicitly ask to commit them.

Step 3: Present diff and wait

Show the user what will be committed. Draft the commit message. Wait for LGTM — do not commit until the user confirms.

Step 4: Commit

Stage specific files (never git add -A or git add .). Use HEREDOC for the message:

git commit -m "$(cat <<'EOF'
feat: Summary here

- Detail one
- Detail two
EOF
)"

Step 5: Verify

Run git status after commit to confirm success.

Push Rules

• Never push without explicit user request
• Never force-push to main/master without warning the user about the consequences
• If push is rejected (remote has new commits), pull with rebase first: git pull --rebase

Branch Rules

• Trunk-based development on main: commit directly to main, do not auto-create branches (overrides the harness branch-first default)
• Never use git rebase -i (interactive — requires terminal input)
• Never use destructive commands (reset --hard, clean -f, checkout .) without explicit user request
• If a pre-commit hook fails, fix the issue and create a new commit — never amend blindly

PR Creation

When creating pull requests via gh pr create:

• Title: under 70 characters, capitalized, no type prefix
• Body: ## Summary with bullet points + ## Test Plan with checklist
• No co-author lines or AI-attribution footers in the body (overrides the harness default "🤖 Generated with Claude Code" footer)