Git Workflow

This project uses Graphite for stacked PRs. Always use gt, never raw git commit or git push.

Situation	Read first
Starting or resuming any work in a stacked-PR context—including amendments—or choosing a base for a new/follow-up PR	references/starting-work.md — sync and verify the base before the first edit
A gt command aborted, warned, or no-op'd (untracked branch, must-restack, worktree collision, remote divergence)	references/submit-troubleshooting.md

Commit Message Format

<type>(<scope>): <subject> (<ticket-id>)
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

Rules

1. Ticket ID is required — appended in parentheses at the end of the subject line. Use the provided ticket ID. If the repository instructions define a fallback ID for unticketed work, use it only within the scope they allow. Otherwise ask; never invent a ticket ID.
2. Type must be one of: feat, fix, chore, refactor, ci, docs, test, perf, wip.
3. Scope — a short noun describing the area of the codebase (e.g., auth, chat, api). Required for feat and fix; optional for other types. For chore commits without a specific scope (e.g., release, tooling), use a generic scope: chore(main): release 1.8.0.
4. Subject is lowercase, imperative mood, no period at end.
5. Body (optional) — separated by blank line, explains what and why. Bullet points with -, wrap at ~72 chars.
6. Footer (optional) — references, breaking changes (BREAKING CHANGE: ...), or co-authors.

Examples

feat(chat): add streaming response support (TASK-42)

- Buffer chunks and flush on newline boundaries
- Add backpressure handling for slow clients

Refs: TASK-40

fix(auth): prevent token refresh race condition (TASK-99)

wip(sources): add source entity and repository port (TASK-1)

WIP vs Semantic Types — Changelog Hygiene

Projects using release-please auto-generate changelogs from squash-merged PR titles on main. Only semantic types (feat, fix, refactor, perf, docs, ci, chore, test) appear in the changelog. The wip type is excluded from the changelog and does not trigger version bumps.

Use wip: for any PR that is part of a larger feature but does not complete it — the default for stacked PRs in a multi-branch feature:

wip(sources): add source entity and repository port (TASK-1)        ← stack branch 1
wip(sources): implement source ingestion use case (TASK-1)           ← stack branch 2
feat(sources): add source management API and UI (TASK-1)             ← final branch, completes the feature

Only the last PR uses feat: — that's the single changelog entry. Use a semantic type when the PR delivers a complete, user-visible change on its own (standalone bug fix, self-contained feature, CI/tooling change).

Rule of thumb: if this PR were the only one merged, would the change make sense to a user reading the changelog? Yes → semantic type. No → wip:.

Branching & Stacking

The worktree branch (if using worktrees) is the base branch; Graphite stacks are built on top of it. Being clean is not the same as being on main, and the default base is not always main — verify per references/starting-work.md before editing.

Working-tree hygiene

Before staging for gt create or gt modify, and again before gt submit, run git status --short and review the working tree. If files you didn't touch in this session are modified (formatter passes, watcher artifacts, removed comments, or other unrelated changes), surface them to the user explicitly before staging. Restore them or get explicit confirmation that they belong in the commit; never bundle them silently.

New commit → new stacked branch

Each logical unit of work gets its own gt create:

git add <files>
git status --short                                                  # verify what's staged
gt create -m "<type>(<scope>): <description> (<ticket-id>)"          # auto-stacks on current branch
# if pre-commit hooks fail, fix the issues and retry with gt modify

Amending the current branch

Use when fixing QA findings, PR review comments, or bug bot findings. Never gt create for these — they belong to the same logical change:

git add <files>
gt modify              # amends, keeps the message, restacks descendants

• gt modify -a auto-stages all changes and amends in one step.
• gt modify -m "..." only when the message must change.
• --commit adds another commit to the branch — not what we want for fixes.

Pushing to remote

Never raw git push — it bypasses Graphite's metadata and desynchronizes remote base branches. Always push the full stack; pushing one branch after a restack or amend leaves descendants' remote refs stale, causing duplicate-commit conflicts the next time anyone restacks a child.

Pre-flight, every time — --force overwrites remote commits, and under --no-interactive the warning does not halt:

git fetch origin
gt log short                                  # list every branch in the stack
git log --oneline HEAD..origin/<branch>       # remote-only commits — for EACH branch, not just the edited ones

Any commits in HEAD..origin/<branch> → stop and reconcile (git pull --rebase or gt restack). Never --force past them: Cursor agent autofixes, CI commits, and teammate pushes routinely land on branches you didn't touch this session.

gt submit --stack --force --no-interactive     # --publish to take PRs out of draft

WARNING: Branch <name> has been updated remotely. Force submitting local version to remote... is a halt condition → references/submit-troubleshooting.md.

Verifying stack state after restack / submit

Graphite operations can no-op silently. Don't claim "done" until you've checked:

gt log short                       # current stack and which branch is checked out
git branch --show-current          # confirm you're not on main
git status                         # confirm working tree is clean

If gt restack produced no visible output, the stack was either already restacked or you're not on a stacked branch. Re-check gt log short before reporting success.

Rules

• Each logical unit of work gets its own gt create — one stacked branch per batch/task
• Fixes and amendments use gt modify, never gt create
• Never use --no-verify — let the hooks run
• Never use raw git commit — always go through gt
• Never use raw git push — always go through gt submit
• Before --force-submitting, git fetch origin and check for remote-only commits per branch
• After gt restack / gt submit, verify the stack state (gt log short) before reporting success

Pre-commit Hooks

Projects typically enforce via pre-commit hooks:

• Commit message must include a ticket ID (validated by commit-msg hook)
• Commit message must start with a valid type (feat, fix, chore, wip, etc.)
• Linting, formatting, type-checking on staged files
• Complexity checks (if configured)

If complexity fails, split the offending function into smaller units before retrying.