Skip to content
Skills Library
Programming · Review & audit

git-policy

/git-policy

WellForge git policy — linear history (no merge commits) and Conventional Commits, in every WellForge repo including generated ones. Use whenever writing a commit message, integrating a branch, opening or merging a PR, setting up a fresh clone, fixing a rejected commit or a red commit-lint / linear-history gate, or configuring branch protection. Authoritative reference for the commit format, the four enforcement layers (local config, committed hooks, CI gates, branch protection), the rebase-not-merge integration rule, and what to do when a gate rejects your commit.

Repository
wellforge ↗
Licence
MIT
Last repository change
13.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

WellForge git policy — linear history (no merge commits) and Conventional Commits, in every WellForge repo including generated ones. Use whenever writing a commit message, integrating a branch, opening or merging a PR, setting up a fresh clone, fixing a rejected commit or a red commit-lint / linear-history gate, or configuring branch protection. Authoritative reference for the commit format, the four enforcement layers (local config, committed hooks, CI gates, branch protection), the rebase-not-merge integration rule, and what to do when a gate rejects your commit.

Original author description

WellForge git policy — linear history (no merge commits) and Conventional Commits, in every WellForge repo including generated ones. Use whenever writing a commit message, integrating a branch, opening or merging a PR, setting up a fresh clone, fixing a rejected commit or a red commit-lint / linear-history gate, or configuring branch protection. Authoritative reference for the commit format, the four enforcement layers (local config, committed hooks, CI gates, branch protection), the rebase-not-merge integration rule, and what to do when a gate rejects your commit.

How it works

  1. The commit format
  2. Integration — rebase, never merge
  3. Four enforcement layers
  4. When a gate rejects you
  5. What this does not cover
Original SKILL.md headings · 86 lines, 665 words
SKILL.md preview
---
name: git-policy
description: >
  WellForge git policy — linear history (no merge commits) and Conventional Commits, in every
  WellForge repo including generated ones. Use whenever writing a commit message, integrating
  a branch, opening or merging a PR, setting up a fresh clone, fixing a rejected commit or a
  red commit-lint / linear-history gate, or configuring branch protection. Authoritative
  reference for the commit format, the four enforcement layers (local config, committed
  hooks, CI gates, branch protection), the rebase-not-merge integration rule, and what to do
  when a gate rejects your commit.
---

# Git policy — linear history and Conventional Commits

Two rules, non-negotiable in every WellForge repo and every project WellForge generates:

1. **Linear history.** No merge commits. Rebase onto the base branch, integrate with
   `--ff-only`, and land PRs as squash or rebase.
2. **Conventional Commits.** Every commit subject is `type(scope)!: description`.

They are not style preferences. A linear history makes `git log` a readable sequence of
changes and `git bisect` meaningful; Conventional Commits is what `$wf-release`
derives the version bump and CHANGELOG from, so a malformed subject silently produces a
wrong release.

## The commit format

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

<optional body>

<optional footers>
```

Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`,
`revert`. `!` (or a `BREAKING CHANGE:` footer) marks a breaking change and drives a major
bump. Merge, revert, fixup, squash and amend commits are exempt — git generates them.

- **`feat` and `fix` move the version**, everything else does not. Choose the type by what
  the change *does* to users, not by how much work it was.
- The description says what changed, in the imperative. The body says **why**, and is where
  the failure shape belongs — the thing a future reader needs and `git log --oneline` can
  never carry.
- Reference the task and spec when there is one: `feat(export): add CSV serializer (T1,
  specs/20261109-csv-export)`.

## Integration — rebase, never merge

```bash
git fetch origin
git rebase origin/main            # replay your work on top
git switch main && git merge --ff-only <branch>
```

`git merge --no-ff` is refused by config, by hook, and by CI. If `--ff-only` fails with
`fatal: Not possible to fast-forward`, the branch was not rebased onto the current tip —
rebase again and retry. That refusal is the policy working; reaching for a flag that forces
the merge through is the one response that is always wrong.

For a parallel batch integrating several worktree branches, [`worktree-isolation`](../worktree-isolation/SKILL.md) owns the
protocol (the rebase runs **inside** each worktree — the main tree cannot rebase a branch
that is checked out elsewhere).

## Four enforcement layers

Each catches what the previous one misses; none is sufficient alone.

| Layer | What it is | Catches |
|---|---|---|
| **Local config** | `merge.ff=only`, `pull.rebase=true`, `rebase.autoStash=true` | A merge commit before it exists. Per-clone, so it ships as a script, not a file. |
| **Committed hooks** | `gates/hooks/commit-msg`, `gates/hooks/pre-merge-commit` | A malformed subject at commit time, when fixing it is free. |
| **CI gates** | `commit-lint.yml`, `linear-history.yml`, called at **every** rigor tier | What a contributor's unconfigured clone let through. History hygiene is tier-independent — unlike coverage, it cannot be repaired after the fact without rewriting published history. |
| **Branch protection** | `required_linear_history`, `allow_merge_commit=false` | The merge button in the GitHub UI, which no local setting can reach. |

Run **`./scripts/setup-git-policy.sh`** once per clone (generated projects: `mise run
git-policy`) — it applies the config and installs the hooks. A fresh clone has none of it.

## When a gate rejects you

- **`commit-msg` hook rejected the subject** → `git commit --amend` with a conforming
  subject. The validator prints the expected shape and the type list.
- **`linear-history` CI is red** → the PR range contains a merge commit. Rebase the branch
  (`git rebase origin/main`) and force-push **with `--force-with-lease`**, which refuses if
  the remote moved under you. Plain `--force` is blocked by the plugin's bash guard for that
  reason.
- **`commit-lint` CI is red on an old commit** → rebase interactively and reword it. Fixing
  the tip alone leaves the range red.
- **You are mid-rebase and lost** → `git rebase --abort` returns you to where you started.
  Nothing is lost; the branch is unchanged until the rebase completes.

## What this does not cover

Squash-merging a PR in the GitHub UI produces one commit whose subject is the **PR title** —
so the PR title must be a Conventional Commit too. Branch protection cannot enforce that;
review it like any other line of the change.

Versions

RepositoryScoreLicence
This page · matteocodogno/wellforge100MIT
matteocodogno/wellforge100MIT

Database snapshot: 13.11.2026 · package version fcd608d84caa (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100git-commit-hygiene-meaningful-commit-history
    Use this skill when crafting atomic Git commits, conventional commit messages, and clean linear Git branch histories.
  • 100git-workflow
    Conventional commits, PR creation, and quality gate verification. Use when: commit, PR, branch, push, conventional commit, create pull request, git.
  • 100commit-message
    Generate conventional commit messages - use when creating commits, writing commit messages, or asking for git commit help
  • 95git-commits
    Write clear, semantic git commit messages and PR/MR titles following Conventional Commits. Use when the user asks to write commit messages, format git history, improve commit quality, or set a PR/MR title, or mentions "commit message", "conventional commits", "merge message", or…
  • 100git-commit
    Inspect Git changes, organize logical commits, and write Conventional Commits messages. Use for /git-commit, explicit commit requests, message drafting, commit planning, and commit review. Excludes general Git troubleshooting, branch strategy, and history repair.
  • 100conventional-commits
    Use when the user asks to commit, create a commit, write a commit message, or runs /commit or /conventional-commits in any git repository - commit, commitar, mensagem de commit, conventional commits.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.