Git Conventions

This skill governs workspace state, branch naming, and commit messages across all A-Novel backend services. Every branch and commit produced by an agent follows these conventions exactly — they drive automation (Renovate, CI tagging, changelogs) and signal intent to reviewers at a glance.

Load the Git procedure for this operation

• Before starting or finishing checkout work, or cleaning anything up, read workspace hygiene. Touch only what this session created, cleanup included, unless told otherwise; preserve other contributors' work and use an isolated checkout for sustained work.
• Before naming a branch, grouping changes, or writing, amending, or reviewing a commit message, read commit conventions. Use attribute-ai-commits for material AI contributions.
• For branch names and history changes, apply the rules below.
• For publication, PR descriptions, metadata, readiness, and final handoff, load open-pull-request; it owns those mechanics.

develop-feature owns stage timing. Existing authorization carries forward; neither a clean tree nor a local commit alone authorizes publication, merging, or changes to another person's work.

Branch Naming

<type>/<area>/<short-description>

• type: same vocabulary as commit types (feat, fix, refactor, chore, ci, docs)
• area: the layer or subsystem being changed — use the commit scope
• short-description: kebab-case, 2–5 words, describes what the branch achieves

Examples

feat/proto/add-key-revoke-rpc
feat/handlers/grpc-jwk-revoke
fix/dao/search-returns-deleted-keys
refactor/core/extract-key-rotation-logic
chore/skills/feature-workflow
docs/pkg/update-client-examples

Branch names are lowercase kebab-case only. No underscores and no slashes inside a segment. A working branch carries no version number. Only the two kinds of long-lived line do:

• release/vX.Y holds a released minor and its backports.
• v<N> develops major N until it replaces master. The line it replaces keeps its own v<N> name, and the retired-lines ruleset freezes it once master releases a later major.

Commit Workflow

# 1. Stage only the files for this logical unit
git add internal/dao/pg.jwkRevoke.go internal/dao/pg.jwkRevoke_test.go

# 2. Commit with a conventional message — a subject line, nothing more
git commit -m "feat(dao): add soft-delete repository for key revocation"

# Only when the body carries what the diff cannot (HEREDOC for multi-line):
git commit -m "$(cat <<'EOF'
fix(dao): lock the key row before revoking

Concurrent revokes both read the key as ACTIVE and wrote two audit
entries; SELECT ... FOR UPDATE is what serialises them.
EOF
)"

Rules

• A commit is its subject line. Add a body only when it says something the subject and the diff cannot — see Body.
• One signed commit per pull request. Each signature costs the developer a key touch, and the squash merge lands one commit anyway. While you work, commit checkpoints unsigned (git -c commit.gpgsign=false commit); before the first push, squash them into one signed commit (git reset --soft <base>, then commit). Each later review round adds one commit. The branch is the logical unit: implement-feature cuts one per layer.
• Stage explicit paths — never git add -A / git add .. These checkouts keep sibling worktrees under an untracked tmp/ (see Before you start). A blanket add stages each tmp/wt-* as an embedded-repo gitlink — a bogus submodule ref that rides your commit onto master if it slips through review. git show --stat HEAD betrays it as a tmp/wt-… | 1 + line. Name the files the logical unit touched; the git add … in this workflow is a list on purpose.
• Generated files belong in the same commit as the change that required them. Proto Go bindings (internal/models/proto/gen/) and mocks (internal/handlers/mocks/, internal/core/mocks/) never get their own commit — stage them with the .proto or interface change that required pnpm generate:go.
• Never commit secrets. .env files, APP_MASTER_KEY values, real credentials.
• Never skip hooks (--no-verify) unless explicitly asked.
• Never amend a pushed commit. Create a new commit instead.
• Mid-rebase, resolve, git add, then git rebase --continue; never git commit --amend. HEAD is then the previously replayed commit, so an amend folds the resolution into it and replaces its message. To undo it, git reset --soft to that commit from the reflog, commit the difference, and compare HEAD^{tree} with the amended tree to prove nothing else moved.
• Push Conventional subjects only. The commit-messages ruleset rejects any other commit, on every branch. Never push fixup!, squash!, amend! or work-in-progress commits: fold them in before the first push with git rebase --autosquash <base>, or write the follow-up as its own Conventional commit.
• Update a branch by rebasing onto its base, never by merging the base in. A merge writes a Merge branch … commit, which the ruleset rejects, and so does GitHub's default "Update branch". Its "Update with rebase" rewrites the commits unsigned, which the required-signatures rule rejects: the pull request can no longer enter the merge queue. Run git rebase origin/master and git push --force-with-lease instead, which signs them. A rebase replays the branch's commits unchanged, so it is not the amend the rule above forbids. A pull request needs no update to enter the queue, which tests it on the latest base.
• Revert with git, not GitHub's Revert button, whose Revert "…" subject the ruleset rejects: git revert --no-commit <sha>, then git commit -m "revert: <reverted subject>" -m "This reverts commit <sha>.".
• Never push to master/main — not force-push, not a plain push — without explicit consent. This is the one git action that is never safe by default. Most contributors lack the access, so the guardrail is already enforced for them; on an admin account it is yours to hold, because you have the rights to bypass it. Publish feature branches at the stage authorized by develop-feature; see Branch and PR freedom.

Git LFS

GitHub keeps every LFS object pushed to it. Deleting the file or rewriting history frees no storage; only deleting the repository or a GitHub Support request does. Squash LFS iterations into one commit before pushing, so only the final version uploads.

Check git lfs version before committing under a filter=lfs path. Without git-lfs, git ignores the attribute and silently commits the file as an ordinary blob. A checkout without git-lfs's pre-push hook pushes pointers whose content never reaches the remote. Run git lfs push origin <branch> before git push there; it skips objects the remote already holds.

Reuse the GitHub SSH Connection

The one goal: a chain of git operations must not ask a FIDO security key for presence again and again. Every new SSH connection to GitHub needs a touch. So when you start a chain of network git operations (push, fetch, pull, clone, ls-remote), reuse the shared connection if it is up, or open it:

ssh -O check git@github.com 2>/dev/null || ssh -o ControlPersist=1h -fN git@github.com

Every operation in the chain rides that connection, which closes once it sits unused for an hour. Do nothing else around the key: never probe, list, poll or wait on it or on the connection. A probe opens the device and competes with ssh-keygen for it. When a connection or a signature fails, stop and tell the developer.

That needs ~/.ssh/config to multiplex github.com, which the developer guide's GitHub page sets up: ssh -G git@github.com then prints a controlpath line. a-novel core sync checks for that same connection and reuses it, so the two never clash. Without the config, ask the developer to add the guide's block. Meanwhile, prefix each network git command with the socket the CLI opens itself:

GIT_SSH_COMMAND='ssh -o ControlMaster=auto -o ControlPath=~/.ssh/a-novel-%C -o ControlPersist=1h' git push

Prefix it rather than export it: an exported GIT_SSH_COMMAND makes the CLI skip its own sharing, which keeps a sync under GitHub's limit of ten sessions per connection.

A signature shares nothing: every signed commit or tag asks for its own touch, and a rebase signs every commit it replays again. So keep each pull request to one signed commit, as the rules above say, and put every signing step in one script: the fetch, a rebase only when workspace hygiene calls for one, the commit and the push. Master then cannot move between your check and the signatures. Check the script first, because one that fails after the developer approved it costs a second approval: run bash -n on it, and its unsigned steps (the fetch, git merge-tree, git add -n) in your own shell. Give any rebase in it GIT_EDITOR=true. Run it where the developer sees its terminal, and warn them before it starts, because git hides ssh-keygen's "Confirm user presence" prompt until it fails. Once the call returns, read the terminal with a wait of a few seconds at most. Commits nobody asked to sign must not reach the key: scratch repositories and test suites that commit inherit commit.gpgsign, so run them with -c commit.gpgsign=false or GIT_CONFIG_GLOBAL=/dev/null.

Git LFS's pre-push hook opens an SSH master of its own, so a plain push from a checkout that carries it asks for a second touch. The stack and uikit carry it, as does any checkout where this succeeds:

grep -q lfs "$(git rev-parse --git-common-dir)/hooks/pre-push"

Turn LFS's multiplexing off in every such checkout, so LFS rides the shared connection:

git -c lfs.ssh.automultiplex=false push

If the push then stalls on LFS lock verification, add -c lfs.locksverify=false.

Branch and PR Freedom

Follow develop-feature: during local drafting, keep branches and checkpoint commits local until the developer agrees on the direction, unless they explicitly requested publication. A local commit is not itself a reason to push.

After that agreement, pushing a feature branch and opening a PR within the authorized scope need no repeated permission. Use open-pull-request for the checks appropriate to the stage. Clear, small tasks can take the shorter path defined by develop-feature.

PRs can receive review while their planning issues are still being discussed. Preserve review history, keep scope and deferred coverage visible, and follow the normal history-rewrite rules. Mark a PR ready as soon as anyone other than you should look at it, as open-pull-request defines; issue scope approval, testing and cleanup gate the merge. Never treat a draft as exempt from repository safeguards or push directly to master/main without explicit consent.

Pull Request Description

Use open-pull-request for the authoritative title, body, issue linkage, validation, and handoff requirements. Keep the Conventional-Commits title under 70 characters, state breaking changes, and include only affected layers and meaningful verification.